okengine 0.2.8 → 0.3.2

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

@@ -2,7 +2,10 @@
  * Lazy channel binder — loaded only when Channel is declared.
  */
 
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { openConsoleChannel } from "../../drivers/channel-console.ts";
+import { openSmtpChannel } from "../../drivers/channel-smtp.ts";
+import type { ChannelDriver, ChannelOpenOptions } from "../../drivers/channel-types.ts";
 import { createChannelRuntime, type ChannelRuntime } from "../../elements/channel.ts";
 import type { BootOptions } from "../boot.ts";
 
@@ -10,12 +13,71 @@ import type { BootOptions } from "../boot.ts";
  * Construct a Channel runtime (console inbox default).
  *
  * @param options - Boot options
+ * @param env - Active environment
  * @param now - Clock
+ * @param docker - Prefer compose SMTP when active
  */
-export function bindChannel(options: BootOptions, now: () => number): ChannelRuntime {
+export function bindChannel(
+  options: BootOptions,
+  env: ConfigEnv,
+  now: () => number,
+  docker = false,
+): ChannelRuntime {
   return createChannelRuntime({
     ...(options.channel ?? {}),
-    drivers: options.channel?.drivers ?? [openConsoleChannel()],
+    drivers: options.channel?.drivers ?? [channelDriverFor(options, env, docker)],
     now,
   });
 }
+
+function channelDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver {
+  const id = resolveEmailDriverId(options, env, docker);
+  if (id === "console") return openConsoleChannel();
+  if (id === "smtp") return openSmtpChannel(smtpOptionsFromEnv(docker));
+  throw new Error(`oke boot: unknown email channel driver "${id}"`);
+}
+
+/**
+ * Resolve the configured email driver for one environment.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param docker - Docker mode
+ */
+export function resolveEmailDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): string {
+  return (
+    resolveDriverId(options.config?.drivers?.channel?.email, env) ?? (docker ? "smtp" : "console")
+  );
+}
+
+/**
+ * Resolve SMTP connection options from `SMTP_URL` plus optional auth overrides.
+ *
+ * @param docker - Whether to include the docker-specific missing URL hint
+ */
+export function smtpOptionsFromEnv(docker = false): ChannelOpenOptions {
+  const raw = process.env.SMTP_URL ?? process.env.OKE_CHANNEL_EMAIL_URL;
+  if (!raw) {
+    throw new Error(
+      docker
+        ? "oke boot: smtp driver needs SMTP_URL (did `oke dev -d` write docker/.env.docker?)"
+        : "oke boot: smtp driver needs SMTP_URL",
+    );
+  }
+  const url = new URL(raw);
+  if (url.protocol !== "smtp:") throw new Error(`oke boot: SMTP_URL must use smtp://`);
+  const urlUser = url.username ? decodeURIComponent(url.username) : undefined;
+  const urlPass = url.password ? decodeURIComponent(url.password) : undefined;
+  const user = process.env.SMTP_USER ?? urlUser;
+  const pass = process.env.SMTP_PASSWORD ?? urlPass;
+  return {
+    host: url.hostname,
+    port: url.port ? Number(url.port) : 25,
+    ...(user ? { user } : {}),
+    ...(pass ? { pass } : {}),
+  };
+}

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

@@ -3,13 +3,14 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { resolveKvDriverId, resolveSqlDriverId } from "./store.ts";
+import { resolveFilesDriverId, resolveKvDriverId, resolveSqlDriverId } from "./store.ts";
 
 describe("bindStore driver resolution", () => {
   const prev = {
     docker: process.env.OKE_DOCKER,
     sql: process.env.OKE_SQL_DRIVER,
     kv: process.env.OKE_KV_DRIVER,
+    files: process.env.OKE_FILES_DRIVER,
   };
 
   afterEach(() => {
@@ -19,6 +20,8 @@ describe("bindStore driver resolution", () => {
     else process.env.OKE_SQL_DRIVER = prev.sql;
     if (prev.kv === undefined) delete process.env.OKE_KV_DRIVER;
     else process.env.OKE_KV_DRIVER = prev.kv;
+    if (prev.files === undefined) delete process.env.OKE_FILES_DRIVER;
+    else process.env.OKE_FILES_DRIVER = prev.files;
   });
 
   test("local env keeps sqlite / memory from config", () => {
@@ -28,12 +31,14 @@ describe("bindStore driver resolution", () => {
           store: {
             sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
             kv: { local: "memory", docker: "redis", prod: "redis" },
+            files: { local: "fs", docker: "s3", prod: "s3" },
           },
         },
       },
     };
     expect(resolveSqlDriverId(options, "local", false)).toBe("sqlite");
     expect(resolveKvDriverId(options, "local", false)).toBe("memory");
+    expect(resolveFilesDriverId(options, "local", false)).toBe("fs");
   });
 
   test("docker env uses docker profile (falls back to prod)", () => {
@@ -43,18 +48,22 @@ describe("bindStore driver resolution", () => {
           store: {
             sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
             kv: { local: "memory", prod: "redis" },
+            files: { local: "fs", prod: "s3" },
           },
         },
       },
     };
     expect(resolveSqlDriverId(options, "docker", true)).toBe("postgres");
     expect(resolveKvDriverId(options, "docker", true)).toBe("redis");
+    expect(resolveFilesDriverId(options, "docker", true)).toBe("s3");
   });
 
   test("docker mode honours OKE_*_DRIVER overrides", () => {
     process.env.OKE_SQL_DRIVER = "postgres";
     process.env.OKE_KV_DRIVER = "redis";
+    process.env.OKE_FILES_DRIVER = "s3";
     expect(resolveSqlDriverId({}, "docker", true)).toBe("postgres");
     expect(resolveKvDriverId({}, "docker", true)).toBe("redis");
+    expect(resolveFilesDriverId({}, "docker", true)).toBe("s3");
   });
 });

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

@@ -3,11 +3,13 @@
  */
 
 import { resolveDomainDdlMode, resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import { fsDriver } from "../../drivers/fs.ts";
 import { memoryDrivers } from "../../drivers/memory.ts";
 import { postgresDriver } from "../../drivers/postgres.ts";
 import { redisDriver } from "../../drivers/redis.ts";
+import { s3Driver } from "../../drivers/s3.ts";
 import { sqliteDriver } from "../../drivers/sqlite.ts";
-import type { KvDriver, SqlDriver } from "../../drivers/types.ts";
+import type { FilesDriver, KvDriver, SqlDriver } from "../../drivers/types.ts";
 import { createStoreRuntime, type StoreRuntime } from "../../elements/store.ts";
 import type { StoreDecl } from "../../elements/store/declare.ts";
 import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
@@ -31,11 +33,14 @@ export function bindStore(
 ): StoreRuntime {
   const sqlId = resolveSqlDriverId(options, env, docker);
   const kvId = resolveKvDriverId(options, env, docker);
+  const filesId = resolveFilesDriverId(options, env, docker);
   const sqlUrl = sqlUrlFor(sqlId, docker);
   const kvUrl = kvUrlFor(kvId, docker);
+  const filesRoot = filesRootFor(filesId);
 
   const sqlBindings: Record<string, { name: string; primary: { url: string } }> = {};
   const kvBindings: Record<string, { url?: string }> = {};
+  const filesBindings: Record<string, { root?: string }> = {};
 
   for (const decl of options.stores ?? []) {
     if (isSqlDecl(decl)) {
@@ -45,6 +50,8 @@ export function bindStore(
       };
     } else if (isKvDecl(decl)) {
       kvBindings[decl.name] = kvUrl !== undefined ? { url: kvUrl } : {};
+    } else if (isFilesDecl(decl)) {
+      filesBindings[decl.name] = filesRoot !== undefined ? { root: filesRoot } : {};
     }
   }
 
@@ -55,11 +62,12 @@ export function bindStore(
     drivers: {
       sql: sqlDriverFor(sqlId),
       kv: kvDriverFor(kvId),
-      files: memoryDrivers.files,
+      files: filesDriverFor(filesId),
       index: memoryDrivers.index,
     },
     sql: sqlBindings,
     kv: kvBindings,
+    files: filesBindings,
     now,
     domainDdl,
   });
@@ -107,6 +115,23 @@ export function resolveKvDriverId(options: BootOptions, env: ConfigEnv, docker:
   return docker ? "redis" : "memory";
 }
 
+/**
+ * @param options - Boot options
+ * @param env - Active env
+ * @param docker - Docker mode
+ */
+export function resolveFilesDriverId(
+  options: BootOptions,
+  env: ConfigEnv,
+  docker: boolean,
+): string {
+  const fromEnv = process.env.OKE_FILES_DRIVER?.trim();
+  if (docker && fromEnv) return fromEnv;
+  const resolved = resolveDriverId(options.config?.drivers?.store?.files, env);
+  if (resolved) return resolved;
+  return docker ? "s3" : "memory";
+}
+
 function sqlDriverFor(id: string): SqlDriver {
   switch (id) {
     case "postgres":
@@ -131,6 +156,19 @@ function kvDriverFor(id: string): KvDriver {
   }
 }
 
+function filesDriverFor(id: string): FilesDriver {
+  switch (id) {
+    case "s3":
+      return s3Driver;
+    case "fs":
+      return fsDriver;
+    case "memory":
+      return memoryDrivers.files;
+    default:
+      throw new Error(`oke boot: unknown files driver "${id}"`);
+  }
+}
+
 function sqlUrlFor(sqlId: string, docker: boolean): string {
   if (sqlId === "postgres") {
     const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
@@ -162,6 +200,11 @@ function kvUrlFor(kvId: string, docker: boolean): string | undefined {
   return url;
 }
 
+function filesRootFor(filesId: string): string | undefined {
+  if (filesId !== "s3") return undefined;
+  return process.env.S3_BUCKET ?? process.env.OKE_STORE_FILES_DB ?? undefined;
+}
+
 function isSqlDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "sql" }> {
   return decl.facet === "sql";
 }
@@ -169,3 +212,7 @@ function isSqlDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "sql" }
 function isKvDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "kv" }> {
   return decl.facet === "kv";
 }
+
+function isFilesDecl(decl: StoreDecl): decl is Extract<StoreDecl, { facet: "files" }> {
+  return decl.facet === "files";
+}

package/src/kernel/boot.test.ts

@@ -100,7 +100,6 @@ describe("boot — lazy element needs", () => {
         external: [
           "@duckdb/node-api",
           "@duckdb/*",
-          "age-encryption",
           "sently",
           "sently/*",
           "ajv",

package/src/kernel/boot.ts

@@ -374,7 +374,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   // 5. Channel
   let channel = pre.channel;
   if (needs.channel && !channel) {
-    channel = channelBind!.bindChannel(options, now);
+    channel = channelBind!.bindChannel(options, env, now, docker);
   }
 
   // 6. AI

package/src/kernel/edge.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Plugin edge handlers — the contribution that answers HTTP requests no
+ * flow owns (CORS preflight being the prime example), with the plain 404
+ * preserved as the floor.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { plugin } from "./plugin.ts";
+import { createPluginRegistry } from "./registry.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("plugin edge handlers", () => {
+  test("an edge handler answers an unmatched request; the flow still owns matched ones", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const edge = plugin("edge-test", { version: "0.0.1" }).edge((_request, info) => {
+      if (info.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers: { "x-edge": "yes" } });
+      }
+      return undefined;
+    });
+    const app = oke({ name: "edge" }).plug(edge);
+
+    const preflight = await app.fetch(new Request("http://localhost/x", { method: "OPTIONS" }));
+    expect(preflight.status).toBe(204);
+    expect(preflight.headers.get("x-edge")).toBe("yes");
+
+    const matched = await app.fetch(new Request("http://localhost/x"));
+    expect(matched.status).toBe(200);
+    expect(matched.headers.get("x-edge")).toBeNull();
+  });
+
+  test("returning undefined falls through to the next handler, then the plain 404", async () => {
+    const pass = plugin("edge-pass", { version: "0.0.1" }).edge(() => undefined);
+    const answer = plugin("edge-answer", { version: "0.0.1" }).edge(
+      () => new Response("answered", { status: 418 }),
+    );
+    const app = oke({ name: "edge-order" }).plug(pass).plug(answer);
+
+    const res = await app.fetch(new Request("http://localhost/nowhere", { method: "OPTIONS" }));
+    expect(res.status).toBe(418);
+    expect(await res.text()).toBe("answered");
+
+    const noPlugins = oke({ name: "edge-none" });
+    const missing = await noPlugins.fetch(
+      new Request("http://localhost/nowhere", { method: "OPTIONS" }),
+    );
+    expect(missing.status).toBe(404);
+    expect(await missing.text()).toBe("Not Found");
+  });
+
+  test("edge is recorded as an intercept capability", () => {
+    const registry = createPluginRegistry();
+    const registration = registry.plug(
+      plugin("edge-cap", { version: "0.0.1" }).edge(() => undefined),
+      { kind: "app" },
+    );
+    expect(registration?.capabilities.intercepts).toContain("edge");
+    expect(registry.edgeHandlers()).toHaveLength(1);
+  });
+});

package/src/kernel/errors.registry.test.ts

@@ -26,7 +26,7 @@ describe("OKE error-code registry", () => {
   test("OkeError docsUrl matches docs origin /e/{code}", () => {
     for (const def of Object.values(OKE_ERRORS) as OkeErrorDefinition[]) {
       const err = new OkeError(def);
-      expect(err.docsUrl).toBe(`https://okengine.vercel.app/e/${def.code}`);
+      expect(err.docsUrl).toBe(`https://oke.omqkhafi.dev/e/${def.code}`);
       expect(err.message).toContain(err.docsUrl);
       expect(err.message).toContain(`OKE${def.code}`);
       expect(err.message).toContain("→");

package/src/kernel/flow.ts

@@ -62,6 +62,11 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
    * Cross-plane invocation is a compile error.
    */
   readonly plane?: FlowPlane;
+  /**
+   * Acknowledge intentional Manifest contract breaks for this flow
+   * (`oke doctor --diff` / CI gate).
+   */
+  readonly breaking?: boolean;
   /** The behavior. */
   readonly do: FlowHandler<I, O>;
 }
@@ -150,6 +155,8 @@ export interface FlowDef<
   readonly slo: Slo | undefined;
   /** Plane (user vs operator). */
   readonly plane: FlowPlane | undefined;
+  /** Intentional contract-break acknowledgement for Manifest Diff. */
+  readonly breaking: boolean;
   /** Handler body. */
   readonly do: FlowHandler<I, O>;
   /** Triggers bound via {@link on} (zero or more). */
@@ -219,6 +226,7 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
     cache: options.cache,
     slo: options.slo,
     plane: options.plane,
+    breaking: options.breaking ?? false,
     do: options.do as FlowHandler<InferFlowIn<Opts>, InferFlowOut<Opts>>,
     triggers,
     $trigger: undefined,

package/src/kernel/fx.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { createCapabilityToken } from "./capability.ts";
 import { createEffectLedger, reversibilityOf } from "./effects.ts";
 import { fail, formatOkeMessage, lookupOkeError, OKE_ERRORS, OkeError } from "./errors.ts";
-import { createFx, createFxContext, type Fx, type FxStubStoreHandle } from "./fx.ts";
+import {
+  createFx,
+  createFxContext,
+  jsonResultBrand,
+  type Fx,
+  type FxStubStoreHandle,
+} from "./fx.ts";
 
 /** Narrow stub handle for tests that exercise the in-memory store. */
 function stub(fx: Fx, ref: string): FxStubStoreHandle {
@@ -28,7 +34,7 @@ describe("fx — capability enforcement", () => {
     expect(oke.code).toBe(1001);
     expect(oke.causeText).toBe('Flow "bookings.create" reads "sql:users" without declaring it.');
     expect(oke.fix).toBe('Add "sql:users" to this flow\'s effects.reads.');
-    expect(oke.docsUrl).toBe("https://okengine.vercel.app/e/1001");
+    expect(oke.docsUrl).toBe("https://oke.omqkhafi.dev/e/1001");
     expect(oke.message).toBe(formatOkeMessage(1001, oke.causeText, oke.fix, oke.docsUrl));
   });
 
@@ -158,6 +164,20 @@ describe("fx — wholesale swap", () => {
       operator: { id: null },
       tenant: { id: "t1" },
       fail,
+      json: {
+        ok(value, opts) {
+          return { [jsonResultBrand]: true, status: 200, value, meta: opts?.meta };
+        },
+        create(value) {
+          return { [jsonResultBrand]: true, status: 201, value };
+        },
+        empty() {
+          return { [jsonResultBrand]: true, status: 204 };
+        },
+        with(data, meta) {
+          return { [jsonResultBrand]: true, status: 200, value: data, meta };
+        },
+      },
       async step(_name, fn) {
         return fn();
       },
@@ -185,7 +205,7 @@ describe("errors — registry", () => {
     });
     expect(err.message).toContain("OKE1042");
     expect(err.message).toContain("no subscriber");
-    expect(err.message).toContain("https://okengine.vercel.app/e/1042");
+    expect(err.message).toContain("https://oke.omqkhafi.dev/e/1042");
     expect(err.message).toContain("→");
   });
 

package/src/kernel/fx.ts

@@ -10,7 +10,14 @@
  */
 
 import type { Effects, ResourceRef } from "../manifest/types.ts";
-import type { StoreDecl, StoreHandle, StoreRuntime, SqlStoreHandle } from "../elements/store.ts";
+import type {
+  SelectOrderBuilder,
+  StoreDecl,
+  StoreHandle,
+  StoreRuntime,
+  SqlStoreHandle,
+} from "../elements/store.ts";
+import type { SqlRow } from "../drivers/types.ts";
 import type { SignalRuntime } from "../elements/signal.ts";
 import type { VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
@@ -183,6 +190,40 @@ export interface FxSearchOptions {
   readonly topK?: number;
 }
 
+/** Brand for {@link JsonResult} (kept internal — flows never construct it). */
+export const jsonResultBrand: unique symbol = Symbol.for("oke.json");
+
+/** Carrier from {@link FxJson} — status + body read by the response encoder. */
+export interface JsonResult<T = unknown> {
+  readonly [jsonResultBrand]: true;
+  readonly status: number;
+  readonly value?: T;
+  readonly meta?: Record<string, unknown>;
+}
+
+/** True when `value` is an {@link FxJson} carrier. */
+export function isJsonResult(value: unknown): value is JsonResult {
+  return (
+    typeof value === "object" && value !== null && (value as JsonResult)[jsonResultBrand] === true
+  );
+}
+
+/**
+ * JSON response helpers. `fx.json.create` answers 201; `fx.json.ok` can carry
+ * a top-level `meta` (Stripe-style `{ data, meta?, error }`);
+ * `fx.json.empty` answers 204.
+ */
+export interface FxJson {
+  /** 200 — body `{ data: value, meta?, error: null }`. */
+  ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T>;
+  /** 201 — body `{ data: value, error: null }`. */
+  create<T>(value: T): JsonResult<T>;
+  /** 204 — no body. */
+  empty(): JsonResult<never>;
+  /** 200 — body `{ data, meta, error: null }` (paginated lists). */
+  with<T>(data: T, meta: Record<string, unknown>): JsonResult<T>;
+}
+
 /**
  * The `fx` context object — v1 surface.
  *
@@ -287,6 +328,8 @@ export interface Fx {
    * @param opts - Optional message
    */
   fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E>;
+  /** JSON response helpers (status + Stripe-style envelope). */
+  readonly json: FxJson;
   /**
    * Named durable step — never re-runs on journal replay.
    *
@@ -523,30 +566,53 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       select(columns?) {
         return {
           from(table) {
-            const all = gated("read", ref, async () => {
-              const h = await ensure();
-              return h.select(columns).from(table);
+            const run = (plan: {
+              where?: unknown;
+              orders?: readonly unknown[];
+              limit?: number;
+              offset?: number;
+            }): Promise<SqlRow[]> =>
+              gated("read", ref, async () => {
+                const h = await ensure();
+                const from = h.select(columns).from(table);
+                const filtered = plan.where === undefined ? from : from.where(plan.where);
+                const ordered =
+                  plan.orders === undefined ? filtered : filtered.orderBy(...plan.orders);
+                if (plan.offset !== undefined) return ordered.offset(plan.offset);
+                return plan.limit === undefined ? ordered : ordered.limit(plan.limit);
+              });
+
+            const tail = (plan: {
+              where?: unknown;
+              orders?: readonly unknown[];
+            }): SelectOrderBuilder => ({
+              limit(n) {
+                return run({ ...plan, limit: n });
+              },
+              offset(n) {
+                return run({ ...plan, offset: n });
+              },
+              then(onfulfilled, onrejected) {
+                return run(plan).then(onfulfilled, onrejected);
+              },
             });
+
             return {
               where(where) {
-                const filtered = gated("read", ref, async () => {
-                  const h = await ensure();
-                  return h.select(columns).from(table).where(where);
-                });
                 return {
-                  limit(n) {
-                    return gated("read", ref, async () => {
-                      const h = await ensure();
-                      return h.select(columns).from(table).where(where).limit(n);
-                    });
-                  },
-                  then(onfulfilled, onrejected) {
-                    return filtered.then(onfulfilled, onrejected);
-                  },
+                  ...tail({ where }),
+                  orderBy: (...orders: readonly unknown[]) => tail({ where, orders }),
                 };
               },
+              orderBy: (...orders: readonly unknown[]) => tail({ orders }),
+              limit(n: number) {
+                return run({ limit: n });
+              },
+              offset(n: number) {
+                return run({ offset: n });
+              },
               then(onfulfilled, onrejected) {
-                return all.then(onfulfilled, onrejected);
+                return run({}).then(onfulfilled, onrejected);
               },
             };
           },
@@ -635,6 +701,18 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return h.raw(sql, params);
         });
       },
+      count(table, where) {
+        return gated("read", ref, async () => {
+          const h = await ensure();
+          return h.count(table, where);
+        });
+      },
+      page(table, pageOptions) {
+        return gated("read", ref, async () => {
+          const h = await ensure();
+          return h.page(table, pageOptions);
+        });
+      },
       ensureTable(table) {
         return gated("write", ref, async () => {
           refuseDryRunWrite();
@@ -932,6 +1010,25 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     operator,
     tenant,
     fail,
+    json: {
+      ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T> {
+        return {
+          [jsonResultBrand]: true,
+          status: 200,
+          value,
+          ...(opts?.meta !== undefined ? { meta: opts.meta } : {}),
+        } as JsonResult<T>;
+      },
+      create<T>(value: T): JsonResult<T> {
+        return { [jsonResultBrand]: true, status: 201, value } as JsonResult<T>;
+      },
+      empty(): JsonResult<never> {
+        return { [jsonResultBrand]: true, status: 204 } as JsonResult<never>;
+      },
+      with<T>(data: T, meta: Record<string, unknown>): JsonResult<T> {
+        return { [jsonResultBrand]: true, status: 200, value: data, meta } as JsonResult<T>;
+      },
+    },
     async step<T>(name: string, fn: () => T | Promise<T>): Promise<T> {
       if (journal) {
         return journal.step(name, fn);

package/src/kernel/hooks.test.ts

@@ -146,6 +146,39 @@ describe("hooks — order and composition", () => {
     expect(order).toEqual(["onAuth", "onResponse"]);
   });
 
+  test("onResponse sees the serialized data response and may replace it", async () => {
+    let seenAtHook: Response | undefined;
+
+    on(
+      http.get("/data"),
+      flow({
+        name: "data",
+        do: () => ({ ok: true }),
+      }),
+    );
+
+    const app = oke({ name: "data-res" }).hook("onResponse", (ctx) => {
+      seenAtHook = ctx.response;
+      if (!ctx.response) return;
+      const headers = new Headers(ctx.response.headers);
+      headers.set("x-stamped", "yes");
+      ctx.response = new Response(ctx.response.body, {
+        status: ctx.response.status,
+        headers,
+      });
+    });
+
+    const res = await app.fetch(new Request("http://localhost/data"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-stamped")).toBe("yes");
+    // The hook saw the real serialized response, not undefined.
+    expect(seenAtHook).toBeDefined();
+    expect(seenAtHook!.headers.get("content-type")).toContain("application/json");
+    // The body survived the rebuild untouched.
+    const body = (await res.json()) as { data?: { ok: boolean } };
+    expect(body.data?.ok).toBe(true);
+  });
+
   test("hook short-circuits with FlowFailure and runs onError", async () => {
     const order: string[] = [];