@ontrails/http 1.0.0-beta.17 → 1.0.0-beta.19

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @ontrails/http
 
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- e41c382: Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+- 94a8380: Add public API examples for the shared Web Fetch route and topo handlers.
+- 94a8380: Add a public API example for the HTTP intent method table.
+- 84f56a5: Project live trail-version metadata on CLI, HTTP, and MCP surfaces and thread explicit surface version selection into shared trail execution.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- fc00aeb: Add adapter target conformance metadata and scaffold extracted HTTP adapters through `trails create adapter`.
+- ab1c77c: Advertise first-party adapter target metadata for catalog derivation.
+- 8ca5b85: Expose owner-owned HTTP adapter conformance cases from `@ontrails/http/testing`.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### Minor Changes
+
+- c0b2948: Add `@ontrails/http/fetch`, a shared Web Fetch request/response kernel for HTTP
+  surface materializers.
+- fc3219c: Add `@ontrails/http/bun`, a Bun-native HTTP surface materializer backed by the
+  shared Web Fetch kernel.
+
+### Patch Changes
+
+- bc2d327: Close HTTP package documentation around the shared `@ontrails/http/fetch` kernel, Bun-native `@ontrails/http/bun` subpath, and Hono adapter boundary before versioning.
+  - @ontrails/core@1.0.0-beta.18
+
 ## 1.0.0-beta.17
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @ontrails/http
 
-Framework-agnostic HTTP route derivation for Trails. Pair this package with `@ontrails/hono` when you want the Hono surface adapter.
+Framework-agnostic HTTP route derivation and Web Fetch request handling for Trails. Pair this package with `@ontrails/hono` when you want Hono portability, or use `@ontrails/http/bun` when you want Bun-native serving without a third-party framework.
 
 ## Usage
 
@@ -22,6 +22,26 @@ await surface(graph, { port: 3000 });
 
 This starts a Hono-based HTTP server. The `greet` trail becomes `GET /greet?name=...` because its `intent` is `'read'`.
 
+For Bun-native HTTP without Hono, use the Bun runtime materializer subpath:
+
+```typescript
+import { surface } from '@ontrails/http/bun';
+
+await surface(graph, { port: 3000 });
+```
+
+`@ontrails/http/bun` uses Bun's native `Bun.serve({ routes })` fast path and keeps the shared Web Fetch handler as the fallback. It requires Bun `>=1.2.3` and does not add a third-party runtime dependency.
+
+## Projection and materialization
+
+The HTTP package follows the surface API naming split:
+
+- `derive*` exports are pure projections from the topo. Use `deriveHttpRoutes()` for route definitions and `deriveOpenApiSpec()` for the OpenAPI contract.
+- `create*` exports materialize runtime objects without opening a network boundary. `@ontrails/http/fetch` exports `createRouteHandler()` for one route and `createFetchHandler()` for a full topo dispatcher.
+- `surface()` opens the runtime boundary. `@ontrails/hono` opens a Hono server; `@ontrails/http/bun` opens Bun's native HTTP server.
+
+The shared `@ontrails/http/fetch` kernel owns query/body parsing, content-length validation, public error projection, diagnostics, request IDs, headers, abort propagation, and webhook verification/parsing behavior. Hono and Bun both consume that kernel so route semantics stay aligned.
+
 For more control, build the routes yourself:
 
 ```typescript
@@ -44,8 +64,7 @@ import { deriveOpenApiSpec } from '@ontrails/http';
 const spec = deriveOpenApiSpec(graph, { basePath: '/api' });
 ```
 
-`deriveOpenApiSpec()` emits an OpenAPI 3.1 document from the same trail
-contracts used by `deriveHttpRoutes()`.
+`deriveOpenApiSpec()` emits an OpenAPI 3.1 document from the same trail contracts used by `deriveHttpRoutes()`.
 
 ## API
 
@@ -53,6 +72,25 @@ contracts used by `deriveHttpRoutes()`.
 | --- | --- |
 | `deriveHttpRoutes(graph, options?)` | Build framework-agnostic route definitions from a topo |
 | `deriveOpenApiSpec(graph, options?)` | Generate an OpenAPI 3.1 document for the HTTP surface |
+| `@ontrails/http/fetch` | Shared Web Fetch `createRouteHandler()` and `createFetchHandler()` kernel |
+| `@ontrails/http/bun` | Bun-native `createApp()` and `surface()` materializer |
+| `@ontrails/http/testing` | Owner-owned adapter conformance factory for HTTP adapter authors |
+
+## Adapter authoring
+
+HTTP adapter authors should validate adapters through the owner-owned testing subpath instead of copying conformance behavior into each adapter:
+
+```typescript
+import {
+  createHttpAdapterConformanceCases,
+  runConformance,
+} from '@ontrails/http/testing';
+import { myHttpAdapter } from './adapter.js';
+
+runConformance(myHttpAdapter, createHttpAdapterConformanceCases());
+```
+
+The adapter under test provides a `name` and `createApp(graph, options)` method that returns an object with a Web Fetch-compatible `fetch(request)` handler. The conformance cases cover query and body input projection, validation envelopes, public error redaction, request context, abort propagation, and webhook verification/parsing behavior.
 
 ## Route derivation
 
@@ -73,7 +111,7 @@ Trail IDs map to paths: `entity.show` becomes `/entity/show`. Dots become slashe
 
 ## Resource resolution
 
-Declared resources on each trail are resolved into the context before the implementation runs.
+Declared resources on each trail are resolved into the context before the blaze receives input.
 
 ## Filtering
 
@@ -84,9 +122,7 @@ const result = deriveHttpRoutes(graph, {
 });
 ```
 
-`*` matches one dotted segment and `**` matches any depth. Trails declared
-with `visibility: 'internal'` stay hidden unless you include their exact trail
-ID intentionally.
+`*` matches one dotted segment and `**` matches any depth. Trails declared with `visibility: 'internal'` stay hidden unless you include their exact trail ID intentionally.
 
 ## Request context and abort propagation
 
@@ -103,17 +139,16 @@ Each route definition produced by `deriveHttpRoutes` includes:
 | `trailId` | `string` | The trail ID this route was derived from |
 | `inputSource` | `'query' \| 'body'` | Where to read input |
 | `trail` | `Trail` | The original trail definition |
-| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the implementation |
+| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the blazed trail |
 
-For GET routes on the Hono surface, repeated query keys are passed through as
-arrays (`?tag=one&tag=two` -> `{ tag: ['one', 'two'] }`) while a single
-occurrence stays a scalar string. The adapter does not coerce singleton query
-values into arrays.
+For GET routes on the Hono surface, repeated query keys are passed through as arrays (`?tag=one&tag=two` -> `{ tag: ['one', 'two'] }`) while a single occurrence stays a scalar string. The adapter does not coerce singleton query values into arrays.
 
 ## Installation
 
 ```bash
-bun add @ontrails/http @ontrails/hono
+bun add @ontrails/http@beta @ontrails/hono@beta
+# or, for Bun-native serving:
+bun add @ontrails/http@beta
 ```
 
 ## Migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.17",
+  "version": "1.0.0-beta.19",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -12,6 +12,9 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./bun": "./src/bun.ts",
+    "./fetch": "./src/fetch.ts",
+    "./testing": "./src/testing.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -22,9 +25,25 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.16"
+    "@ontrails/core": "^1.0.0-beta.19"
   },
   "peerDependencies": {
     "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapterTargets": {
+      "http": {
+        "conformance": {
+          "adapterType": "HttpAdapterConformanceAdapter",
+          "casesFactory": "createHttpAdapterConformanceCases",
+          "runner": "runConformance"
+        },
+        "placements": [
+          "extracted",
+          "subpath"
+        ],
+        "testingImport": "@ontrails/http/testing"
+      }
+    }
   }
 }

package/src/build.ts

@@ -12,6 +12,7 @@ import {
   ValidationError,
   buildActivationProvenanceTraceAttrs,
   collectAttachedTypedLayers,
+  deriveSurfaceTrailVersionProjections,
   executeTrail,
   filterSurfaceTrails,
   getActivationWherePredicate,
@@ -39,9 +40,11 @@ import type {
   BaseSurfaceOptions,
   Layer,
   ResourceOverrideMap,
+  SurfaceTrailVersionProjection,
   TraceContext,
   Topo,
   Trail,
+  TrailVersionReference,
   TrailContextInit,
   WebhookSource,
   WebhookVerifyRequest,
@@ -72,6 +75,7 @@ export type HttpHeaderSource =
 
 export interface HttpExecutionContext {
   readonly headers?: HttpHeaderSource | undefined;
+  readonly version?: TrailVersionReference | undefined;
 }
 
 export interface ResolveHttpPermitInput {
@@ -93,6 +97,7 @@ export interface HttpRouteDefinition {
   readonly trailId: string;
   readonly inputSource: InputSource;
   readonly trail: Trail<unknown, unknown, unknown>;
+  readonly versions?: readonly SurfaceTrailVersionProjection[] | undefined;
   /**
    * JSON Schema for the merged request input (trail input + projected layer
    * input fields). Empty/undefined when the trail declares no input and no
@@ -126,7 +131,7 @@ export interface HttpRouteDefinition {
     | undefined;
   readonly webhookSource?: WebhookSource | undefined;
   /**
-   * Validate input, compose layers, and execute the trail implementation.
+   * Validate input, compose layers, and run the blazed trail.
    *
    * The caller is responsible for parsing raw input from the request and
    * mapping the Result to an HTTP response. This function is framework-agnostic.
@@ -572,6 +577,67 @@ const mergeHttpInputSchemas = (
   return merged;
 };
 
+const TRAIL_VERSION_INPUT_FIELD = 'trailVersion';
+const TRAILS_VERSION_HEADERS = ['x-trails-version', 'x-trail-version'];
+
+const versionInputSchema = (): Record<string, unknown> => ({
+  properties: {
+    [TRAIL_VERSION_INPUT_FIELD]: {
+      description: 'Live trail version number or marker prefix',
+      type: 'string',
+    },
+  },
+  type: 'object',
+});
+
+const addVersionInputSchema = (
+  trail: Trail<unknown, unknown, unknown>,
+  schema: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined =>
+  trail.version === undefined
+    ? schema
+    : mergeHttpInputSchemas(schema, versionInputSchema());
+
+const readVersionFromHeaders = (
+  headers: HttpHeaderSource | undefined
+): TrailVersionReference | undefined => {
+  for (const name of TRAILS_VERSION_HEADERS) {
+    const value = readHeader(headers, name);
+    if (value !== undefined && value.length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+};
+
+const splitHttpSurfaceVersion = (
+  input: unknown,
+  context: HttpExecutionContext | undefined,
+  supportsVersions: boolean
+): {
+  readonly input: unknown;
+  readonly version: TrailVersionReference | undefined;
+} => {
+  if (!supportsVersions) {
+    return { input, version: undefined };
+  }
+
+  const headerVersion =
+    context?.version ?? readVersionFromHeaders(context?.headers);
+  if (!isJsonObjectSchema(input)) {
+    return { input, version: headerVersion };
+  }
+
+  const record = input as Record<string, unknown>;
+  const { [TRAIL_VERSION_INPUT_FIELD]: fieldVersion, ...rest } = record;
+  const version =
+    headerVersion ??
+    (typeof fieldVersion === 'string' || typeof fieldVersion === 'number'
+      ? fieldVersion
+      : undefined);
+  return { input: rest, version };
+};
+
 /**
  * Partition a parsed request input into the trail input plus per-layer
  * inputs, using each layer's routing table.
@@ -639,8 +705,13 @@ const createExecute =
     layerProjections: readonly HttpLayerInputProjection[]
   ): HttpRouteDefinition['execute'] =>
   async (input, requestId, abortSignal, request) => {
-    const { trailInput, layerInputs } = partitionHttpInput(
+    const versionedInput = splitHttpSurfaceVersion(
       input,
+      request,
+      t.version !== undefined
+    );
+    const { trailInput, layerInputs } = partitionHttpInput(
+      versionedInput.input,
       layerProjections
     );
     const permitResolution = await resolveHttpPermit(
@@ -664,6 +735,9 @@ const createExecute =
       surfaceLayers: layers,
       topo: graph,
       topoLayers: graph.layers,
+      ...(versionedInput.version === undefined
+        ? {}
+        : { version: versionedInput.version }),
     });
   };
 
@@ -721,8 +795,13 @@ const createWebhookConsumerExecute =
       'activation.webhook',
       'ok'
     );
-    const { trailInput, layerInputs } = partitionHttpInput(
+    const versionedInput = splitHttpSurfaceVersion(
       input,
+      request,
+      t.version !== undefined
+    );
+    const { trailInput, layerInputs } = partitionHttpInput(
+      versionedInput.input,
       layerProjections
     );
     const permitResolution = await resolveHttpPermit(
@@ -746,6 +825,9 @@ const createWebhookConsumerExecute =
       surfaceLayers: layers,
       topo: graph,
       topoLayers: graph.layers,
+      ...(versionedInput.version === undefined
+        ? {}
+        : { version: versionedInput.version }),
     });
   };
 
@@ -836,6 +918,8 @@ const buildRoute = (
     options.layers
   );
   const inputProjection = projectHttpInputSchema(trail, attachedLayers);
+  const inputSchema = addVersionInputSchema(trail, inputProjection.schema);
+  const versions = deriveSurfaceTrailVersionProjections(trail);
   return {
     execute: createExecute(
       graph,
@@ -844,9 +928,7 @@ const buildRoute = (
       options,
       inputProjection.projections
     ),
-    ...(inputProjection.schema === undefined
-      ? {}
-      : { inputSchema: inputProjection.schema }),
+    ...(inputSchema === undefined ? {} : { inputSchema }),
     inputSource: deriveHttpInputSource(method),
     ...(inputProjection.projections.length === 0
       ? {}
@@ -855,6 +937,7 @@ const buildRoute = (
     path,
     trail,
     trailId: trail.id,
+    ...(versions === undefined ? {} : { versions }),
   };
 };
 
@@ -973,6 +1056,8 @@ const buildWebhookRoute = (
     options.layers
   );
   const inputProjection = projectHttpInputSchema(trail, attachedLayers);
+  const inputSchema = addVersionInputSchema(trail, inputProjection.schema);
+  const versions = deriveSurfaceTrailVersionProjections(trail);
   const consumerExecute = createWebhookConsumerExecute(
     graph,
     trail,
@@ -991,9 +1076,7 @@ const buildWebhookRoute = (
     [WEBHOOK_CONSUMERS]: [consumerExecute],
     [WEBHOOK_INVALID_RECORDERS]: [consumerInvalidRecorder],
     execute: createWebhookExecute(consumerExecute),
-    ...(inputProjection.schema === undefined
-      ? {}
-      : { inputSchema: inputProjection.schema }),
+    ...(inputSchema === undefined ? {} : { inputSchema }),
     inputSource: 'webhook',
     ...(inputProjection.projections.length === 0
       ? {}
@@ -1007,6 +1090,7 @@ const buildWebhookRoute = (
     trail,
     trailId: trail.id,
     verifyWebhook: (request) => verifyWebhookRequest(source.value, request),
+    ...(versions === undefined ? {} : { versions }),
     webhookSource: source.value,
   };
   return Result.ok(route);

package/src/bun.ts

@@ -0,0 +1,270 @@
+import {
+  InternalError,
+  NotFoundError,
+  Result,
+  projectPublicSurfaceError,
+  trail,
+} from '@ontrails/core';
+import type {
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  Trail,
+  TrailContextInit,
+} from '@ontrails/core';
+import { z } from 'zod';
+
+import { deriveHttpRoutes } from './build.js';
+import type {
+  HttpMethod,
+  HttpRouteDefinition,
+  ResolveHttpPermit,
+} from './build.js';
+import { createRouteHandler } from './fetch.js';
+import type { CreateRouteHandlerOptions } from './fetch.js';
+
+export interface CreateAppOptions extends BaseSurfaceOptions {
+  readonly basePath?: string | undefined;
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  readonly hostname?: string | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  /** Maximum JSON request body size in bytes. Defaults to 1 MiB. */
+  readonly maxJsonBodyBytes?: number | undefined;
+  readonly port?: number | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+}
+
+export interface SurfaceHttpResult {
+  readonly close: () => Promise<void>;
+  readonly url: string;
+}
+
+type RouteHandler = (request: Request) => Promise<Response>;
+
+type BunRouteMethod = HttpMethod | 'HEAD';
+type BunRouteRecord = Record<
+  string,
+  Partial<Record<BunRouteMethod, RouteHandler>>
+>;
+
+export interface BunHttpApp {
+  readonly fetch: RouteHandler;
+  readonly onError: (error: Error) => Promise<Response>;
+  readonly routes: BunRouteRecord;
+}
+
+const json = (body: Record<string, unknown>, status: number): Response =>
+  Response.json(body, { status });
+
+const mapErrorResponse = (error: Error): Response => {
+  const projection = projectPublicSurfaceError('http', error);
+  return json(
+    {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
+    },
+    projection.code
+  );
+};
+
+const notFoundResponse = (request: Request): Response => {
+  const path = new URL(request.url).pathname;
+  return mapErrorResponse(new NotFoundError(`HTTP route not found: ${path}`));
+};
+
+const methodNotAllowedResponse = (
+  request: Request,
+  route: Partial<Record<BunRouteMethod, RouteHandler>>
+): Response => {
+  const path = new URL(request.url).pathname;
+  return Response.json(
+    {
+      error: {
+        category: 'validation',
+        code: 'MethodNotAllowed',
+        message: `HTTP method not allowed: ${request.method.toUpperCase()} ${path}`,
+      },
+    },
+    {
+      headers: { Allow: Object.keys(route).toSorted().join(', ') },
+      status: 405,
+    }
+  );
+};
+
+const bodylessHeadResponse = (response: Response): Response =>
+  new Response(null, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+
+const caughtErrors = new Map<string, Error>();
+const caughtErrorInput = z.object({ errorId: z.string() });
+const caughtErrorTrail = trail('__ontrails.http.bun.error', {
+  blaze: () =>
+    Result.err(new InternalError('Bun error fallback executed directly')),
+  input: caughtErrorInput,
+  intent: 'read',
+  output: z.object({}),
+}) as Trail<unknown, unknown, unknown>;
+
+const caughtErrorRoute: HttpRouteDefinition = {
+  execute: async (input) => {
+    const parsed = caughtErrorInput.safeParse(input);
+    if (!parsed.success) {
+      return Result.err(
+        new InternalError('Bun error fallback missing error id')
+      );
+    }
+    const error =
+      caughtErrors.get(parsed.data.errorId) ??
+      new Error('Bun error fallback missing caught error');
+    return Result.err(error);
+  },
+  inputSource: 'query',
+  method: 'GET',
+  path: '/__ontrails/http/bun/error',
+  trail: caughtErrorTrail,
+  trailId: '__ontrails.http.bun.error',
+};
+const caughtErrorHandler = createRouteHandler(caughtErrorRoute);
+
+const materializeCaughtErrorRequest = (errorId: string): Request => {
+  const url = new URL('/__ontrails/http/bun/error', 'http://localhost');
+  url.searchParams.set('errorId', errorId);
+  return new Request(url);
+};
+
+const deriveOptions = (options: CreateAppOptions) => ({
+  basePath: options.basePath,
+  configValues: options.configValues,
+  createContext: options.createContext,
+  exclude: options.exclude,
+  include: options.include,
+  intent: options.intent,
+  layers: options.layers,
+  resolvePermit: options.resolvePermit,
+  resources: options.resources,
+  validate: options.validate,
+});
+
+const routeHandlerOptions = (
+  options: CreateAppOptions
+): CreateRouteHandlerOptions => ({
+  maxJsonBodyBytes: options.maxJsonBodyBytes,
+});
+
+const registerRoute = (
+  routes: BunRouteRecord,
+  route: HttpRouteDefinition,
+  options: CreateRouteHandlerOptions
+): void => {
+  const methods = routes[route.path] ?? {};
+  const handler = createRouteHandler(route, options);
+  methods[route.method] = handler;
+  if (route.method === 'GET') {
+    methods.HEAD = async (request) => {
+      const response = await handler(request);
+      return bodylessHeadResponse(response);
+    };
+  }
+  routes[route.path] = methods;
+};
+
+const routeForRequest = (
+  routes: BunRouteRecord,
+  request: Request
+): Partial<Record<BunRouteMethod, RouteHandler>> | undefined => {
+  const path = new URL(request.url).pathname;
+  return routes[path];
+};
+
+/**
+ * Build Bun-compatible HTTP route handlers from a topo.
+ *
+ * @remarks This materializes `deriveHttpRoutes` onto Bun's native `routes`
+ * table while preserving `fetch` as the fallback path for unmatched requests.
+ */
+export const createApp = (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): BunHttpApp => {
+  const routesResult = deriveHttpRoutes(graph, deriveOptions(options));
+
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+
+  const handlerOptions = routeHandlerOptions(options);
+  const routes: BunRouteRecord = {};
+  for (const route of routesResult.value) {
+    registerRoute(routes, route, handlerOptions);
+  }
+
+  return {
+    fetch: async (request) => {
+      const method = request.method.toUpperCase() as BunRouteMethod;
+      const route = routeForRequest(routes, request);
+      if (route === undefined) {
+        const response = notFoundResponse(request);
+        return method === 'HEAD' ? bodylessHeadResponse(response) : response;
+      }
+      const methodHandler = route[method];
+      const response =
+        methodHandler === undefined
+          ? methodNotAllowedResponse(request, route)
+          : await methodHandler(request);
+      return method === 'HEAD' ? bodylessHeadResponse(response) : response;
+    },
+    onError: async (error) => {
+      const errorId = crypto.randomUUID();
+      caughtErrors.set(errorId, error);
+      try {
+        return await caughtErrorHandler(materializeCaughtErrorRequest(errorId));
+      } finally {
+        caughtErrors.delete(errorId);
+      }
+    },
+    routes,
+  };
+};
+
+const startServer = (
+  app: BunHttpApp,
+  options: CreateAppOptions
+): SurfaceHttpResult => {
+  const server = Bun.serve({
+    error: app.onError,
+    fetch: app.fetch,
+    hostname: options.hostname ?? '0.0.0.0',
+    port: options.port ?? 3000,
+    routes: app.routes,
+  });
+
+  return {
+    close: async () => {
+      await server.stop(true);
+    },
+    url: String(server.url),
+  };
+};
+
+/**
+ * Build a Bun-native HTTP app from a topo and start serving it.
+ */
+export const surface = async (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): Promise<SurfaceHttpResult> => {
+  // oxlint-disable-next-line require-await -- async ensures createApp() throws become rejected promises, not uncaught exceptions
+  const app = createApp(graph, options);
+  return startServer(app, options);
+};