okengine 0.21.1 → 0.22.0

package/src/kernel/idempotency.ts

@@ -0,0 +1,304 @@
+/**
+ * HTTP idempotency policy.
+ *
+ * A flow honors `Idempotency-Key` when it is reached over HTTP as REST
+ * non-GET or RPC, its inferred effects mutate or it uses `fx.raw`, and it
+ * is not a stream, live feed, or binary response. The IETF draft this header
+ * follows expired without becoming an RFC.
+ *
+ * @module
+ */
+
+import { parseDurationMs } from "../elements/clock/duration.ts";
+import type { Effects } from "../manifest/types.ts";
+import { fail } from "./errors.ts";
+import type { EffectKind } from "./effects.ts";
+import type { IdempotencyRow, StoredResponse } from "./idempotency-store.ts";
+
+/** Request header. */
+export const IDEMPOTENCY_HEADER = "idempotency-key";
+
+/** Set on a replayed response. */
+export const REPLAYED_HEADER = "idempotent-replayed";
+
+/** Default TTL stamped when the flow omits one. */
+export const IDEMPOTENCY_DEFAULT_TTL = "24h";
+
+/** Author option on `flow({ idempotency })`. */
+export type FlowIdempotencyOption =
+  | false
+  | "required"
+  | { readonly required?: boolean; readonly ttl?: string };
+
+/** Manifest / client stamp. */
+export interface ResolvedIdempotency {
+  readonly mode: "off" | "auto" | "required";
+  readonly ttl: string;
+}
+
+const MUTATING: ReadonlySet<EffectKind> = new Set([
+  "write",
+  "emit",
+  "send",
+  "call",
+  "fetch",
+  "ask",
+  "embed",
+]);
+
+const KEY_PATTERN = /^[\x20-\x7E]{16,255}$/;
+
+/**
+ * True when inferred effects include anything besides reads and secrets.
+ *
+ * @param effects - Declared or inferred effect set
+ */
+export function hasMutatingEffects(effects: Effects | undefined): boolean {
+  if (effects === undefined) return false;
+  return (
+    (effects.writes?.length ?? 0) > 0 ||
+    (effects.emits?.length ?? 0) > 0 ||
+    (effects.sends?.length ?? 0) > 0 ||
+    (effects.calls?.length ?? 0) > 0 ||
+    (effects.fetches?.length ?? 0) > 0 ||
+    (effects.asks?.length ?? 0) > 0 ||
+    (effects.embeds?.length ?? 0) > 0
+  );
+}
+
+/**
+ * True when this HTTP entry should look at `Idempotency-Key`.
+ *
+ * @param args - Trigger shape and inferred effects
+ */
+export function idempotencyEligible(args: {
+  readonly hasRequest: boolean;
+  /** HTTP method. RPC is `POST`. */
+  readonly method: string | undefined;
+  readonly stream: boolean;
+  readonly live: boolean;
+  readonly effects: Effects | undefined;
+  readonly usesRaw: boolean;
+}): boolean {
+  if (!args.hasRequest || args.stream || args.live) return false;
+  const method = (args.method ?? "POST").toUpperCase();
+  if (method === "GET") return false;
+  return args.usesRaw || hasMutatingEffects(args.effects);
+}
+
+/** What this request should do with the header. */
+export interface IdempotencyAttempt {
+  readonly claiming: boolean;
+  readonly mode: "off" | "auto" | "required";
+  readonly ttlMs: number;
+  readonly usesRaw: boolean;
+}
+
+/**
+ * Decide whether this request claims a key.
+ *
+ * A stamped `required` flow still ignores the header when this entry is not
+ * an eligible HTTP call (signal delivery, GET, stream, live, read-only).
+ *
+ * @param args - Flow stamp plus this request
+ */
+export function prepareIdempotencyAttempt(args: {
+  readonly hasRequest: boolean;
+  readonly method: string | undefined;
+  readonly stream: boolean;
+  readonly live: boolean;
+  readonly effects: Effects | undefined;
+  readonly usesRaw: boolean;
+  readonly option: FlowIdempotencyOption | undefined;
+  readonly resolved: ResolvedIdempotency | undefined;
+  readonly header: string | null;
+}): IdempotencyAttempt {
+  const eligible = idempotencyEligible(args);
+  const resolved = args.resolved ?? resolveIdempotencyMode(args.option, eligible);
+  const mode = eligible ? resolved.mode : "off";
+  const headerPresent = args.header !== null && args.header.trim().length > 0;
+  const ttlMs = idempotencyTtlMs(resolved.ttl);
+  return {
+    claiming: mode === "required" || (mode === "auto" && headerPresent),
+    mode,
+    ttlMs: ttlMs > 0 ? ttlMs : 24 * 60 * 60 * 1000,
+    usesRaw: args.usesRaw,
+  };
+}
+
+/**
+ * Resolve `off | auto | required` and the TTL string.
+ *
+ * Ineligible flows are `off` even when the option says required. Callers
+ * that parse source should reject that combination before calling this.
+ *
+ * @param option - Author option
+ * @param eligible - {@link idempotencyEligible}
+ */
+export function resolveIdempotencyMode(
+  option: FlowIdempotencyOption | undefined,
+  eligible: boolean,
+): ResolvedIdempotency {
+  const ttl = ttlOf(option);
+  if (!eligible || option === false) return { mode: "off", ttl };
+  if (option === "required") return { mode: "required", ttl };
+  if (typeof option === "object" && option.required === true) return { mode: "required", ttl };
+  return { mode: "auto", ttl };
+}
+
+/**
+ * Parse a TTL string. `0` means the string is not a duration.
+ *
+ * @param ttl - Duration such as `24h`
+ */
+export function idempotencyTtlMs(ttl: string): number {
+  return parseDurationMs(ttl);
+}
+
+/**
+ * `user:<id>`, else `apikey:<id>`, else `anon`.
+ *
+ * @param auth - Principal after the gate
+ */
+export function idempotencyPrincipal(auth: {
+  readonly userId: string | null;
+  readonly apiKeyId?: string | null;
+}): string {
+  if (auth.userId !== null && auth.userId.length > 0) return `user:${auth.userId}`;
+  if (auth.apiKeyId !== null && auth.apiKeyId !== undefined && auth.apiKeyId.length > 0) {
+    return `apikey:${auth.apiKeyId}`;
+  }
+  return "anon";
+}
+
+/**
+ * SHA-256 of canonical JSON `{ flow, input }`. Computed once at claim.
+ *
+ * @param flow - Flow name
+ * @param input - Validated input
+ */
+export function idempotencyFingerprint(flow: string, input: unknown): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(canonicalJson({ flow, input }));
+  return hasher.digest("hex");
+}
+
+/**
+ * Classify a raw header value.
+ *
+ * @param header - Header value, or null when absent
+ */
+export function classifyIdempotencyKey(header: string | null): "missing" | "invalid" | string {
+  if (header === null) return "missing";
+  const key = header.trim();
+  if (!KEY_PATTERN.test(key)) return "invalid";
+  return key;
+}
+
+/**
+ * True when this attempt recorded a non-read effect. Secrets do not count.
+ * Failed attempts stay on the ledger.
+ *
+ * @param entries - This run's ledger
+ */
+export function attemptedMutation(entries: readonly { readonly kind: EffectKind }[]): boolean {
+  return entries.some((entry) => MUTATING.has(entry.kind));
+}
+
+/**
+ * Replay a stored response and mark it `Idempotent-Replayed`.
+ *
+ * @param row - Completed row
+ */
+export function replayResponse(row: IdempotencyRow): Response {
+  const headers = new Headers();
+  const contentType = row.responseHeaders?.contentType;
+  const location = row.responseHeaders?.location;
+  if (contentType !== undefined && contentType.length > 0) headers.set("content-type", contentType);
+  if (location !== undefined && location.length > 0) headers.set("location", location);
+  headers.set(REPLAYED_HEADER, "true");
+  const status = row.responseStatus ?? 200;
+  if (status === 204) return new Response(null, { status, headers });
+  return new Response(row.responseBody ?? "", { status, headers });
+}
+
+/**
+ * Protocol failure. `IdempotencyInProgress` also sets `Retry-After`.
+ *
+ * @param code - Builtin idempotency code
+ * @param retryAfterSeconds - Seconds until the lease expires, for 409
+ */
+export function idempotencyErrorResponse(
+  code:
+    | "IdempotencyKeyMissing"
+    | "IdempotencyKeyInvalid"
+    | "IdempotencyKeyReused"
+    | "IdempotencyInProgress",
+  retryAfterSeconds?: number,
+): Response {
+  const failure = fail(
+    code,
+    code === "IdempotencyInProgress" ? { retryAfter: retryAfterSeconds } : {},
+  );
+  const headers = new Headers();
+  if (code === "IdempotencyInProgress") {
+    headers.set("retry-after", String(Math.max(1, retryAfterSeconds ?? 1)));
+  }
+  const status =
+    code === "IdempotencyKeyReused" ? 422 : code === "IdempotencyInProgress" ? 409 : 400;
+  return Response.json({ data: null, error: failure.error }, { status, headers });
+}
+
+/**
+ * Buffer a JSON envelope for storage. Streams and non-JSON bodies return
+ * undefined so the caller deletes the in-progress row.
+ *
+ * @param res - Encoded response (not the live stream)
+ */
+export async function storedFromResponse(res: {
+  readonly status: number;
+  readonly headers: { get(name: string): string | null };
+  text(): Promise<string>;
+}): Promise<StoredResponse | undefined> {
+  const contentType = res.headers.get("content-type") ?? undefined;
+  if (contentType?.includes("text/event-stream")) return undefined;
+  if (
+    contentType !== undefined &&
+    !contentType.includes("json") &&
+    !contentType.includes("text/") &&
+    res.status !== 204
+  ) {
+    return undefined;
+  }
+  const location = res.headers.get("location") ?? undefined;
+  const body = res.status === 204 ? "" : await res.text();
+  return {
+    status: res.status,
+    body,
+    ...(contentType !== undefined ? { contentType } : {}),
+    ...(location !== undefined ? { location } : {}),
+  };
+}
+
+/**
+ * Author TTL, or {@link IDEMPOTENCY_DEFAULT_TTL}.
+ *
+ * @param option - Author option
+ */
+export function ttlOf(option: FlowIdempotencyOption | undefined): string {
+  if (typeof option === "object" && option !== null && typeof option.ttl === "string") {
+    return option.ttl;
+  }
+  return IDEMPOTENCY_DEFAULT_TTL;
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj)
+    .filter((key) => obj[key] !== undefined)
+    .sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+}

package/src/kernel/index.ts

@@ -212,6 +212,7 @@ export {
   currentAbortSignal,
   isAbortError,
   linkAbort,
+  requestSignal,
   withAbortSignal,
 } from "./abort-scope.ts";
 

package/src/kernel/journal.ts

@@ -10,7 +10,9 @@
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { okid } from "../okid.ts";
+import type { IdempotencyStore } from "./idempotency-store.ts";
 import { JournalSuspend } from "./journal-suspend.ts";
+import { lazyRequire } from "./lazy-require.ts";
 
 export { JournalSuspend, isJournalSuspend } from "./journal-suspend.ts";
 
@@ -151,8 +153,21 @@ export interface JournalLeaseStore {
   listOrphans(now: number): Promise<readonly JournalRun[]>;
 }
 
+/**
+ * Load the idempotency table implementation without a static import.
+ * Computed stem so the edge profile does not inline it.
+ */
+function loadIdempotencyStore(): typeof import("./idempotency-store.ts") {
+  return lazyRequire(import.meta.dir, ["idempotency", "store"].join("-"));
+}
+
 /** Persistence backend for journal runs. */
 export interface JournalStore extends Partial<JournalLeaseStore> {
+  /**
+   * Idempotency records on this same driver. Absent on a custom store that
+   * only implements run `get` / `put`.
+   */
+  readonly idempotency?: IdempotencyStore;
   /**
    * Load a run by id.
    *
@@ -286,6 +301,11 @@ export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalS
       return [...runs.values()].map(cloneRun);
     },
     ...leaseMethods(load),
+    get idempotency(): IdempotencyStore {
+      const created = loadIdempotencyStore().createMemoryIdempotencyStore();
+      Object.defineProperty(this, "idempotency", { value: created });
+      return created;
+    },
   };
 }
 
@@ -332,6 +352,13 @@ export function createFileJournalStore(path: string): JournalStore {
     },
     // Single-host file: leases coordinate same-machine processes only.
     ...leaseMethods(load, flush),
+    get idempotency(): IdempotencyStore {
+      const created = loadIdempotencyStore().createFileIdempotencyStore(
+        `${dirname(path)}/idempotency.json`,
+      );
+      Object.defineProperty(this, "idempotency", { value: created });
+      return created;
+    },
   };
 }
 
@@ -428,6 +455,35 @@ export interface JournalSession {
   ): Promise<void>;
 }
 
+/**
+ * A journal session that forwards to a real session once one is assigned.
+ *
+ * Idempotent durable flows start the journal only after the claim, which is
+ * after `fx` has already been created.
+ */
+export function createJournalSlot(): {
+  readonly slot: { session?: JournalSession };
+  readonly facade: JournalSession;
+} {
+  const slot: { session?: JournalSession } = {};
+  const facade = new Proxy({} as JournalSession, {
+    get(_target, prop, receiver) {
+      const session = slot.session;
+      if (!session) {
+        if (prop === "runId") return "";
+        if (prop === "stampTenant") return async () => undefined;
+        if (prop === "rewind") return () => undefined;
+        return undefined;
+      }
+      const value = Reflect.get(session, prop, receiver);
+      return typeof value === "function"
+        ? (value as (...args: unknown[]) => unknown).bind(session)
+        : value;
+    },
+  });
+  return { slot, facade };
+}
+
 /** Journal facade. */
 export interface Journal {
   readonly store: JournalStore;

package/src/manifest/types.ts

@@ -201,6 +201,14 @@ export interface Flow {
   source?: string;
   plane?: FlowPlane;
   durable?: boolean;
+  /**
+   * HTTP idempotency stamp. `off` ignores `Idempotency-Key`.
+   * `auto` honors it when present. `required` rejects a missing header.
+   * `ttl` is how long a stored response (possibly PII) is kept.
+   */
+  idempotency?: { mode: "off" | "auto" | "required"; ttl: string };
+  /** True when the body calls `fx.raw`. Throws then keep the idempotency record. */
+  usesRaw?: boolean;
   /** Live signal name when this flow streams `delivery: "live"` SSE. */
   live?: string;
   cache?: boolean | string;

package/src/plugins/auth-delivery.mailpit.integration.test.ts

@@ -18,7 +18,7 @@ import { otp } from "./otp.ts";
 import { magicLink } from "./magic-link.ts";
 
 const SECRET = "test-secret-at-least-16";
-const MAILPIT_IMAGE = "axllent/mailpit:v1.31.1";
+const MAILPIT_IMAGE = "axllent/mailpit:v1.31.2";
 
 afterEach(() => {
   resetBindings();

package/src/plugins/otp.test.ts

@@ -117,7 +117,71 @@ describe("otp() provider mode boot", () => {
     const body = (await res.json()) as { data: { ok: true; devOtp?: string } };
     expect(body.data.ok).toBe(true);
     expect(body.data.devOtp).toBeUndefined();
-    expect(app.router.match("POST", "/auth/otp/resend")).toBeFalsy();
+    expect(app.router.match("POST", "/auth/otp/resend")).toBeTruthy();
+    await app.stop();
+  });
+
+  test("SMS resend issues a new request id, honors cooldown, and rejects another channel", async () => {
+    let now = 1_000_000;
+    const requestIds: string[] = [];
+    const verifications = createVerificationStore();
+    const driver = mockOtpSmsDriver();
+    const transport = driver.smsTransport as unknown as SmsOtpTransport;
+    const original = transport.sendOtp.bind(transport);
+    transport.sendOtp = async (opts) => {
+      requestIds.push(opts.requestId);
+      return original(opts);
+    };
+
+    const app = oke({
+      name: `otp-provider-resend-${crypto.randomUUID()}`,
+      env: "test",
+      registry: "ignore",
+      gate: { auth: { secret: SECRET } },
+      channel: { drivers: [driver] },
+      fx: { now: () => now },
+    }).plug(
+      otp({
+        mode: "provider",
+        resendCooldownMs: 60_000,
+        verifications,
+        now: () => now,
+      }),
+    );
+    await app.boot({ env: "test" });
+
+    const phone = "+15551234567";
+    expect((await app.fetch(jsonPost("/auth/otp/request", { phone }))).status).toBe(200);
+    const first = findActiveVerification(verifications, `otp:${phone}`, now);
+    expect(first?.value.startsWith("provider:")).toBe(true);
+    expect(first?.sealedOtp).toBeNull();
+    const firstId = first?.value.slice("provider:".length);
+
+    const cooled = await app.fetch(jsonPost("/auth/otp/resend", { phone }));
+    const cooledBody = (await cooled.json()) as { error?: { data?: { reason?: string } } };
+    expect(cooledBody.error?.data?.reason).toBe("resend_cooldown");
+
+    const other = await app.fetch(jsonPost("/auth/otp/resend", { phone, channel: "email" }));
+    const otherBody = (await other.json()) as { error?: { data?: { reason?: string } } };
+    expect(otherBody.error?.data?.reason).toBe("invalid_channel");
+
+    now += 60_001;
+    const resent = await app.fetch(jsonPost("/auth/otp/resend", { phone, channel: "sms" }));
+    expect(resent.status).toBe(200);
+    const resentBody = (await resent.json()) as { data: { channel: string; devOtp?: string } };
+    expect(resentBody.data.channel).toBe("sms");
+    expect(resentBody.data.devOtp).toBeUndefined();
+
+    const second = findActiveVerification(verifications, `otp:${phone}`, now);
+    const secondId = second?.value.slice("provider:".length);
+    expect(secondId).toBeDefined();
+    expect(secondId).not.toBe(firstId);
+    if (firstId === undefined || secondId === undefined) {
+      throw new Error("expected provider request ids");
+    }
+    expect(requestIds).toEqual([firstId, secondId]);
+    expect(findActiveVerification(verifications, `otp:${phone}`, now)?.sealedOtp).toBeNull();
+
     await app.stop();
   });
 });

package/src/plugins/otp.ts

@@ -77,7 +77,8 @@ export interface OtpProviderModeOptions extends OtpBaseOptions {
   readonly channels?: never;
   /** Forbidden in provider mode — code never exists server-side. */
   readonly exposeDevOtp?: never;
-  readonly resendCooldownMs?: never;
+  /** Spacing between provider SMS resends. Default 60s. */
+  readonly resendCooldownMs?: number;
   readonly from?: never;
 }
 
@@ -216,10 +217,7 @@ export function otp(opts: OtpOptions): PluginDef {
   const identities = resolveSharedIdentities(opts);
   const verifications = opts.verifications ?? createVerificationStore();
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const resendCooldownMs =
-    opts.mode === "app"
-      ? (opts.resendCooldownMs ?? DEFAULT_RESEND_COOLDOWN_MS)
-      : DEFAULT_RESEND_COOLDOWN_MS;
+  const resendCooldownMs = opts.resendCooldownMs ?? DEFAULT_RESEND_COOLDOWN_MS;
   const channels = opts.mode === "app" ? opts.channels : ([] as const);
   const exposeDevOtp = opts.mode === "app" && opts.exposeDevOtp === true;
   const from = opts.mode === "app" ? opts.from : undefined;
@@ -288,8 +286,61 @@ export function otp(opts: OtpOptions): PluginDef {
           attempts: 0,
           phone,
           sealedOtp: null,
+          lastDeliveredAt: now,
+          lastChannel: "sms",
+        });
+        return { ok: true as const, channel: "sms" as const };
+      },
+    });
+
+    const resendContract = {
+      in: z.object({
+        phone: z.string().min(8),
+        lang: z.enum(["en", "ar"]).optional(),
+        channel: z.enum(["sms", "whatsapp", "email"]).optional(),
+      }),
+      out: requestOut,
+      errors: { AuthFailed, AuthRateLimited },
+    };
+
+    const resend = flow("auth.resendOtp", {
+      plane: "user",
+      effects: { sends: ["sms-otp"] },
+      do: async (input, fx) => {
+        if (input.channel !== undefined && input.channel !== "sms") {
+          return fail("AuthFailed", { reason: "invalid_channel" });
+        }
+        const phone = input.phone.trim();
+        if (!E164.test(phone)) return fail("AuthFailed", { reason: "invalid_phone" });
+        const now = runtime.now();
+        const row = findActiveVerification(verifications, `otp:${phone}`, now);
+        if (!row || row.sealedOtp) {
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        if (row.lastDeliveredAt !== undefined && now - row.lastDeliveredAt < resendCooldownMs) {
+          return fail("AuthFailed", { reason: "resend_cooldown" });
+        }
+
+        const requestId = okid();
+        await fx.sendOtp({
+          to: phone,
+          requestId,
+          ...(input.lang ? { lang: input.lang } : {}),
+        });
+        invalidateVerifications(verifications, `otp:${phone}`, now);
+        putVerification(verifications, {
+          id: okid(),
+          identifier: `otp:${phone}`,
+          value: `provider:${requestId}`,
+          expiresAt: now + ttlMs,
+          createdAt: now,
+          consumedAt: null,
+          attempts: 0,
+          phone,
+          sealedOtp: null,
+          lastDeliveredAt: now,
+          lastChannel: "sms",
         });
-        // Provider mode: resend-via-different-channel is impossible — provider owns the code.
         return { ok: true as const, channel: "sms" as const };
       },
     });
@@ -373,7 +424,8 @@ export function otp(opts: OtpOptions): PluginDef {
     return plugin("otp", { version: "0.0.1", config: configSnapshot })
       .needs("auth")
       .binding(bindPublicAuth("/otp/request", request, "otp", requestContract))
-      .binding(bindPublicAuth("/otp/verify", verify, "otp", verifyContract));
+      .binding(bindPublicAuth("/otp/verify", verify, "otp", verifyContract))
+      .binding(bindPublicAuth("/otp/resend", resend, "otp", resendContract));
   }
 
   // ── App mode ───────────────────────────────────────────────────────────

package/src/release/absolute-regression.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Absolute budgets with room under the cap also fail at 2× the last value.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  absoluteBudgetOk,
+  absoluteRegressionCeiling,
+  formatBudgetsReport,
+  type BudgetsSnapshot,
+} from "./measure.ts";
+import {
+  ABSOLUTE_REGRESSION_RATIO,
+  CLIENT_BUDGET_BYTES,
+  COLD_START_BUDGET_MS,
+  CONSOLE_BUDGET_BYTES,
+  KERNEL_EDGE_BUDGET_BYTES,
+} from "./limits.ts";
+
+describe("absolute regression ceilings", () => {
+  test("ratio is 2× so a confirmed doubling fails and a single noisy run can be re-measured", () => {
+    expect(ABSOLUTE_REGRESSION_RATIO).toBe(2);
+  });
+
+  test("cold start and console initial load grow a ceiling; kernel, client, and a zero baseline do not", () => {
+    expect(absoluteRegressionCeiling(undefined, COLD_START_BUDGET_MS, "ms")).toBeUndefined();
+    expect(absoluteRegressionCeiling(0, 1, "ms")).toBeUndefined();
+    expect(absoluteRegressionCeiling(8.915, COLD_START_BUDGET_MS, "ms")).toBe(17.83);
+    expect(absoluteRegressionCeiling(353_621, CONSOLE_BUDGET_BYTES, "bytes")).toBe(707_242);
+    expect(absoluteRegressionCeiling(12_556, KERNEL_EDGE_BUDGET_BYTES, "bytes")).toBeUndefined();
+    expect(absoluteRegressionCeiling(4598, CLIENT_BUDGET_BYTES, "bytes")).toBeUndefined();
+  });
+
+  test("ok requires both the cap and the ceiling", () => {
+    expect(absoluteBudgetOk(8.915, COLD_START_BUDGET_MS, 17.83)).toBe(true);
+    expect(absoluteBudgetOk(17.83, COLD_START_BUDGET_MS, 17.83)).toBe(false);
+    expect(absoluteBudgetOk(20, COLD_START_BUDGET_MS, 17.83)).toBe(false);
+    expect(absoluteBudgetOk(80, COLD_START_BUDGET_MS, undefined)).toBe(false);
+    expect(absoluteBudgetOk(12_556, KERNEL_EDGE_BUDGET_BYTES, undefined)).toBe(true);
+  });
+
+  test("the CI log prints the 2× ceiling and the absolute cap", () => {
+    const snapshot: BudgetsSnapshot = {
+      measuredAt: "2026-09-23T00:00:00.000Z",
+      version: "0.0.0",
+      budgets: [
+        {
+          id: "coldStartMedianMs",
+          label: "Cold start on Bun",
+          value: 20,
+          limit: COLD_START_BUDGET_MS,
+          regressionLimit: 17.83,
+          unit: "ms",
+          gate: "absolute",
+          group: "core",
+          ok: false,
+        },
+      ],
+    };
+    const report = formatBudgetsReport(snapshot);
+    expect(report).toContain("[FAIL] Cold start on Bun: 20.000 ms < 17.830 ms (cap 75.000 ms)");
+  });
+});

package/src/release/http-graph.test.ts

@@ -0,0 +1,25 @@
+/**
+ * `okengine/http` must not statically import heavy modules.
+ * Forbidden ids live in {@link HTTP_STATIC_GRAPH_FORBIDDEN}.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { forbiddenHttpGraphHits, readStaticGraphSpecifiers } from "./http-graph.ts";
+
+describe("okengine/http static import graph", () => {
+  test("zod and the hybrid-search runtime are not in the graph", async () => {
+    const specifiers = await readStaticGraphSpecifiers();
+    expect(specifiers.length).toBeGreaterThan(10);
+    expect(forbiddenHttpGraphHits(specifiers)).toEqual([]);
+  });
+
+  test("the forbidden list matches zod and search-runtime, and nothing nearby", () => {
+    expect(forbiddenHttpGraphHits(["node_modules/zod/index.js"])).toEqual(["zod"]);
+    expect(forbiddenHttpGraphHits(["zod"])).toEqual(["zod"]);
+    expect(forbiddenHttpGraphHits(["src/elements/store/search-runtime.ts"])).toEqual([
+      "hybrid-search runtime",
+    ]);
+    expect(forbiddenHttpGraphHits(["src/elements/store/search-lsh.ts"])).toEqual([]);
+    expect(forbiddenHttpGraphHits(["src/kernel/app.ts"])).toEqual([]);
+  });
+});