@ontrails/hono 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,321 @@
+# @ontrails/hono
+
+## 0.2.0
+
+### Patch Changes
+
+- [`664e8bb`](https://github.com/outfitter-dev/trails/commit/664e8bb049e61f1d47cec1dd246606707af5d1a8): Point public installation examples at exact approved 0.2.0 versions and distinguish the prepared source release from pending npm publication.
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+### Patch Changes
+
+- [`f5c6777`](https://github.com/outfitter-dev/trails/commit/f5c6777c39ea959d2123f17bb683151fe265386c): Move adapter package workspaces from `connectors/*` to `adapters/*` as part of
+  the package-boundary taxonomy cutover. Package names and public APIs are
+  unchanged.
+- [`e41c382`](https://github.com/outfitter-dev/trails/commit/e41c3829c2d692683b78c730e67fd5b17ac0ff4e): 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.
+- [`ed5926b`](https://github.com/outfitter-dev/trails/commit/ed5926bddebed7be19a902d69be58f2d5e8b4c51): Add missing TSDoc for public adapter and sink boundary types.
+- [`6300f70`](https://github.com/outfitter-dev/trails/commit/6300f709bb6dffc0e6cc82479fe8d0204c52bbba): Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- [`20d7a5c`](https://github.com/outfitter-dev/trails/commit/20d7a5c8e675fd3ecd8c29441bbd8a99b5c64ed0): Enforce the shared safe error projection policy for public error bodies, diagnostics, serialized payloads, and CLI stderr.
+- [`95bf132`](https://github.com/outfitter-dev/trails/commit/95bf132a15d6bd0f3a9e5fa597697393014f1e21): Wire HTTP permit resolution through the Hono adapter, including request headers for Bearer Authorization handling.
+- [`729f957`](https://github.com/outfitter-dev/trails/commit/729f957a11dfa54474c20262dc2c37866f8b437e): Harden the Hono surface by capping JSON request bodies at 1 MiB by default and
+  redacting generic internal errors while preserving server-side diagnostics.
+- [`49c2e7d`](https://github.com/outfitter-dev/trails/commit/49c2e7d5c7c063b9aa6abee1d2932bf3003133cc): Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+- [`bc2d327`](https://github.com/outfitter-dev/trails/commit/bc2d3276cf0af2c7217365a28b436ebf3023c09b): Close HTTP package documentation around the shared `@ontrails/http/fetch` kernel, Bun-native `@ontrails/http/bun` subpath, and Hono adapter boundary before versioning.
+- [`20cb72c`](https://github.com/outfitter-dev/trails/commit/20cb72cc91e48a4683f8832e18b0f55855943583): Refactor Hono route handling to delegate Web request parsing, response
+  projection, diagnostics, permits, and webhook handling through
+  `@ontrails/http/fetch`.
+- [`8105f53`](https://github.com/outfitter-dev/trails/commit/8105f538ee3a0768a21482e6b7385122c2ed90dd): Declare the Hono package as an extracted HTTP adapter and dogfood the shared
+  adapter authoring check path against its owner conformance test.
+- [`df9a7d0`](https://github.com/outfitter-dev/trails/commit/df9a7d00fe4d9ebec948b6ebed6dc4525fc8e0dc): Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+- [`61497c5`](https://github.com/outfitter-dev/trails/commit/61497c54deaaae2d067af88d0be6db0a5acb5faf): Add v1-minimum public API examples for shipped surface entrypoints.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Patch Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+## 1.0.0-beta.39
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+  - @ontrails/http@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+  - @ontrails/http@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+- @ontrails/http@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+- @ontrails/http@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+- @ontrails/http@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+- @ontrails/http@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+  - @ontrails/http@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+  - @ontrails/http@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+- @ontrails/http@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- Updated dependencies [9c5ecdc]
+  - @ontrails/http@1.0.0-beta.23
+  - @ontrails/core@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+- @ontrails/http@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+  - @ontrails/http@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+  - @ontrails/http@1.0.0-beta.20
+
+## 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.
+- ed5926b: Add missing TSDoc for public adapter and sink boundary types.
+- 8105f53: Declare the Hono package as an extracted HTTP adapter and dogfood the shared
+  adapter authoring check path against its owner conformance test.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [94a8380]
+- Updated dependencies [94a8380]
+- 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]
+- Updated dependencies [fc00aeb]
+- Updated dependencies [ab1c77c]
+- Updated dependencies [8ca5b85]
+  - @ontrails/core@1.0.0-beta.19
+  - @ontrails/http@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### 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.
+- 20cb72c: Refactor Hono route handling to delegate Web request parsing, response
+  projection, diagnostics, permits, and webhook handling through
+  `@ontrails/http/fetch`.
+- Updated dependencies [c0b2948]
+- Updated dependencies [fc3219c]
+- Updated dependencies [bc2d327]
+  - @ontrails/http@1.0.0-beta.18
+  - @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+- Updated dependencies [61497c5]
+  - @ontrails/core@1.0.0-beta.17
+  - @ontrails/http@1.0.0-beta.17
+
+## 1.0.0-beta.16
+
+### Patch Changes
+
+- f5c6777: Move adapter package workspaces from `connectors/*` to `adapters/*` as part of
+  the package-boundary taxonomy cutover. Package names and public APIs are
+  unchanged.
+- 6300f70: Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- 20d7a5c: Enforce the shared safe error projection policy for public error bodies, diagnostics, serialized payloads, and CLI stderr.
+- 95bf132: Wire HTTP permit resolution through the Hono adapter, including request headers for Bearer Authorization handling.
+- 729f957: Harden the Hono surface by capping JSON request bodies at 1 MiB by default and
+  redacting generic internal errors while preserving server-side diagnostics.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- df9a7d0: Add project-aware public export-map governance for @ontrails workspace docs,
+  imports, root barrels, and bin-only package surfaces.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [95bf132]
+- Updated dependencies [e898cc4]
+- Updated dependencies [2bf239e]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [49c2e7d]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+- Updated dependencies [df9a7d0]
+  - @ontrails/core@1.0.0-beta.16
+  - @ontrails/http@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/http@1.0.0-beta.15

package/README.md

@@ -0,0 +1,44 @@
+# @ontrails/hono
+
+Hono surface adapter for Trails. Use this package when you want to serve a topo over HTTP with Hono while keeping `@ontrails/http` focused on framework-agnostic route building and the shared Web Fetch kernel.
+
+## Usage
+
+```typescript
+import { surface } from '@ontrails/hono';
+import { graph } from './app';
+
+await surface(graph, { port: 3000 });
+```
+
+JSON request bodies are capped at 1 MiB by default. Override the cap with `maxJsonBodyBytes` when a surface intentionally accepts larger JSON payloads:
+
+```typescript
+await surface(graph, {
+  maxJsonBodyBytes: 2 * 1024 * 1024,
+  port: 3000,
+});
+```
+
+Pass `resolvePermit` to resolve HTTP `Authorization: Bearer ...` credentials into `ctx.permit` before protected trails execute. The adapter forwards request headers to the framework-agnostic HTTP route executor, so malformed Authorization headers return `401` and resolved permits with insufficient scopes return `403`.
+
+Generic non-TrailsError failures return a redacted 500 response while a redacted diagnostic rendering is written to server diagnostics. `TrailsError` responses keep their taxonomy category and class name but redact sensitive message fragments before writing the public body.
+
+For custom HTTP integrations or route inspection, keep using `deriveHttpRoutes()` from `@ontrails/http`. For a framework-neutral runtime handler, use `createRouteHandler()` or `createFetchHandler()` from `@ontrails/http/fetch`. For Bun-native serving without Hono, use `@ontrails/http/bun`.
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/http@0.2.0 @ontrails/hono@0.2.0
+```
+
+## Migration
+
+<!-- warden-ignore-next-line -->
+This package replaces the old `@ontrails/http/hono` subpath.
+
+<!-- warden-ignore-next-line -->
+- Before: `import { trailhead } from '@ontrails/http/hono'`
+- After: `import { surface } from '@ontrails/hono'`

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ontrails/hono",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "adapters/hono"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0",
+    "hono": "^4.7.0"
+  },
+  "peerDependencies": {
+    "@ontrails/http": "^0.2.0",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapter": {
+      "target": "http"
+    }
+  }
+}

package/src/caught-error.ts

@@ -0,0 +1,65 @@
+import { InternalError, Result, trail } from '@ontrails/core';
+import type { Trail } from '@ontrails/core';
+import { createRouteHandler } from '@ontrails/http';
+import type { HttpRouteDefinition } from '@ontrails/http';
+import { z } from 'zod';
+
+const caughtErrors = new Map<string, Error>();
+const caughtErrorInput = z.object({ errorId: z.string() });
+const caughtErrorTrail = trail('__ontrails.hono.error', {
+  implementation: () =>
+    Result.err(new InternalError('Hono 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('Hono error fallback missing error id')
+      );
+    }
+    const error =
+      caughtErrors.get(parsed.data.errorId) ??
+      new Error('Hono error fallback missing caught error');
+    return Result.err(error);
+  },
+  inputSource: 'query',
+  method: 'GET',
+  path: '/__ontrails/hono/error',
+  trail: caughtErrorTrail,
+  trailId: '__ontrails.hono.error',
+};
+const caughtErrorHandler = createRouteHandler(caughtErrorRoute);
+
+const materializeCaughtErrorRequest = (
+  request: Request,
+  errorId: string
+): Request => {
+  const url = new URL('/__ontrails/hono/error', request.url);
+  url.searchParams.set('errorId', errorId);
+  return new Request(url, {
+    headers: request.headers,
+    method: 'GET',
+    signal: request.signal,
+  });
+};
+
+export const handleCaughtHonoError = async (
+  error: unknown,
+  request: Request
+): Promise<Response> => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const errorId = crypto.randomUUID();
+  caughtErrors.set(errorId, err);
+  try {
+    return await caughtErrorHandler(
+      materializeCaughtErrorRequest(request, errorId)
+    );
+  } finally {
+    caughtErrors.delete(errorId);
+  }
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  createApp,
+  surface,
+  type CreateAppOptions,
+  type SurfaceHttpResult,
+} from './surface.js';

package/src/surface.ts

@@ -0,0 +1,242 @@
+/**
+ * Hono adapter for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const graph = topo("myapp", entity);
+ * await surface(graph, { port: 3000 });
+ * ```
+ */
+
+import type {
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+import { Hono } from 'hono';
+import type { Context as HonoContext } from 'hono';
+import { createRouteHandler, deriveHttpRoutes } from '@ontrails/http';
+import type {
+  HttpMethod,
+  HttpRouteDefinition,
+  ResolveHttpPermit,
+} from '@ontrails/http';
+import { handleCaughtHonoError } from './caught-error.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for building a Trails HTTP app on Hono.
+ */
+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 name?: string | undefined;
+  readonly port?: number | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+}
+
+interface RuntimeOptions {
+  readonly maxJsonBodyBytes?: number | undefined;
+}
+
+/**
+ * Runtime handle returned by the Hono surface.
+ */
+export interface SurfaceHttpResult {
+  readonly close: () => Promise<void>;
+  readonly url: string;
+}
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+const materializeHonoRequest = async (c: HonoContext): Promise<Request> => {
+  if (!c.req.raw.bodyUsed) {
+    return c.req.raw;
+  }
+
+  const body = await c.req.text();
+  return new Request(c.req.raw.url, {
+    body,
+    headers: c.req.raw.headers,
+    method: c.req.raw.method,
+    signal: c.req.raw.signal,
+  });
+};
+
+/** Create a Hono handler from a route definition. */
+const createHonoHandler = (
+  route: HttpRouteDefinition,
+  options: RuntimeOptions
+): ((c: HonoContext) => Promise<Response>) => {
+  const handler = createRouteHandler(route, {
+    maxJsonBodyBytes: options.maxJsonBodyBytes,
+  });
+  return async (c) => handler(await materializeHonoRequest(c));
+};
+
+/** Route registration keyed by HTTP method. */
+const routeRegistrars: Record<
+  HttpMethod,
+  (
+    hono: Hono,
+    path: string,
+    handler: (c: HonoContext) => Promise<Response>
+  ) => void
+> = {
+  DELETE: (hono, path, handler) => {
+    hono.delete(path, handler);
+  },
+  GET: (hono, path, handler) => {
+    hono.get(path, handler);
+  },
+  PATCH: (hono, path, handler) => {
+    hono.patch(path, handler);
+  },
+  POST: (hono, path, handler) => {
+    hono.post(path, handler);
+  },
+  PUT: (hono, path, handler) => {
+    hono.put(path, handler);
+  },
+};
+
+const registerRoutes = (
+  hono: Hono,
+  routes: HttpRouteDefinition[],
+  options: RuntimeOptions
+): void => {
+  for (const route of routes) {
+    const handler = createHonoHandler(route, options);
+    routeRegistrars[route.method](hono, route.path, handler);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+
+const handleCaughtError = async (
+  error: unknown,
+  c: HonoContext
+): Promise<Response> => handleCaughtHonoError(error, c.req.raw);
+
+const registerErrorHandler = (hono: Hono): void => {
+  // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
+  hono.onError((err, c) => handleCaughtError(err, c));
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// createApp
+// ---------------------------------------------------------------------------
+
+/**
+ * Build HTTP routes from a topo and register them on a Hono app.
+ *
+ * @remarks This is a host materialization boundary. Derivation failures are
+ * thrown for HTTP bootstrap code after `deriveHttpRoutes` has already
+ * represented the framework error as a Result.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@ontrails/hono';
+ *
+ * const app = createApp(graph, { basePath: '/api' });
+ * Bun.serve({ fetch: app.fetch, port: 3000 });
+ * ```
+ */
+export const createApp = (
+  graph: Topo,
+  options: CreateAppOptions = {}
+): Hono => {
+  const hono = new Hono();
+  const runtimeOptions = {
+    maxJsonBodyBytes: options.maxJsonBodyBytes,
+  };
+
+  registerErrorHandler(hono);
+
+  const routesResult = deriveHttpRoutes(graph, {
+    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,
+  });
+
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+
+  registerRoutes(hono, routesResult.value, runtimeOptions);
+  return hono;
+};
+
+const startServer = (
+  hono: Hono,
+  options: CreateAppOptions
+): SurfaceHttpResult => {
+  const server = Bun.serve({
+    fetch: hono.fetch,
+    hostname: options.hostname ?? '0.0.0.0',
+    port: options.port ?? 3000,
+  });
+
+  return {
+    close: async () => {
+      await server.stop(true);
+    },
+    url: String(server.url),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Hono app from a topo and start serving it with Bun.
+ *
+ * @remarks Always starts a Bun server. Use `createApp(graph)` for an
+ * unserved Hono app that you can wire into your own server.
+ *
+ * @example
+ * ```ts
+ * import { surface } from '@ontrails/hono';
+ *
+ * const server = await surface(graph, { port: 3000 });
+ * console.log(server.url);
+ * ```
+ */
+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 hono = createApp(graph, options);
+  return startServer(hono, options);
+};