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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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

package/README.md

@@ -30,27 +30,17 @@ 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.
+`@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.
+- `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.
+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:
 
@@ -74,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
 
@@ -85,6 +74,23 @@ contracts used by `deriveHttpRoutes()`.
 | `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
 
@@ -105,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
 
@@ -116,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
 
@@ -135,19 +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
+bun add @ontrails/http@beta
 ```
 
 ## Migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -14,6 +14,7 @@
     ".": "./src/index.ts",
     "./bun": "./src/bun.ts",
     "./fetch": "./src/fetch.ts",
+    "./testing": "./src/testing.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -24,9 +25,25 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.17"
+    "@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/fetch.ts

@@ -488,6 +488,21 @@ const handleWebhookRoute = async (
 
 /**
  * Build a Web Fetch handler for one framework-agnostic HTTP route.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpRoutes } from '@ontrails/http';
+ * import { createRouteHandler } from '@ontrails/http/fetch';
+ *
+ * const routes = deriveHttpRoutes(graph, { basePath: '/api' });
+ * if (routes.isErr()) throw routes.error;
+ *
+ * const route = routes.value[0];
+ * if (!route) throw new Error('No routes derived');
+ *
+ * const handle = createRouteHandler(route);
+ * const response = await handle(new Request('https://example.test/api/hello'));
+ * ```
  */
 export const createRouteHandler = (
   route: HttpRouteDefinition,
@@ -534,6 +549,16 @@ export const createRouteHandler = (
 
 /**
  * Build a Web Fetch dispatcher for all HTTP routes in a topo.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler } from '@ontrails/http/fetch';
+ *
+ * const fetch = createFetchHandler(graph, { basePath: '/api' });
+ * const response = await fetch(
+ *   new Request('https://example.test/api/hello?name=Matt')
+ * );
+ * ```
  */
 export const createFetchHandler = (
   graph: Topo,

package/src/method.ts

@@ -6,6 +6,17 @@ export type HttpOperationMethod = Lowercase<HttpMethod>;
 
 export type InputSource = 'query' | 'body' | 'webhook';
 
+/**
+ * Owner table for projecting trail intent onto HTTP methods.
+ *
+ * @example
+ * ```ts
+ * import { httpMethodByIntent } from '@ontrails/http';
+ *
+ * const readMethod = httpMethodByIntent.read;
+ * // readMethod === 'GET'
+ * ```
+ */
 export const httpMethodByIntent = {
   destroy: 'DELETE',
   read: 'GET',

package/src/testing.ts

@@ -0,0 +1,339 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  PermissionError,
+  Result,
+  getWebhookHeader,
+  trail,
+  topo,
+  webhook,
+} from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import type {
+  DeriveHttpRoutesOptions,
+  HttpHeaderSource,
+  ResolveHttpPermit,
+} from './build.js';
+import type { CreateRouteHandlerOptions } from './fetch.js';
+
+export interface HttpAdapterConformanceApp {
+  readonly fetch: (request: Request) => Response | Promise<Response>;
+}
+
+export interface HttpAdapterConformanceOptions
+  extends DeriveHttpRoutesOptions, CreateRouteHandlerOptions {
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+}
+
+export interface HttpAdapterConformanceAdapter {
+  readonly createApp: (
+    graph: Topo,
+    options?: HttpAdapterConformanceOptions
+  ) => HttpAdapterConformanceApp | Promise<HttpAdapterConformanceApp>;
+  readonly name: string;
+}
+
+export interface HttpAdapterConformanceCase {
+  readonly check: (adapter: HttpAdapterConformanceAdapter) => Promise<void>;
+  readonly name: string;
+}
+
+const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ reply: input.message }),
+  input: z.object({ message: z.string() }),
+  intent: 'read',
+  output: z.object({ reply: z.string() }),
+});
+
+const tagsTrail = trail('tags', {
+  blaze: (input) => Result.ok({ tags: input.tags }),
+  input: z.object({ tags: z.array(z.string()) }),
+  intent: 'read',
+  output: z.object({ tags: z.array(z.string()) }),
+});
+
+const echoBodyTrail = trail('echo.body', {
+  blaze: (input) => Result.ok({ length: input.message.length }),
+  input: z.object({ message: z.string() }),
+  intent: 'write',
+  output: z.object({ length: z.number() }),
+});
+
+const genericRedactionError = (): Error =>
+  new Error('database password=secret');
+
+const genericErrorTrail = trail('generic.error', {
+  blaze: () => Result.err(genericRedactionError()),
+  input: z.object({}),
+  intent: 'read',
+  output: z.object({ ok: z.boolean() }),
+});
+
+const protectedTrail = trail('permit.scope', {
+  blaze: (_input, ctx) =>
+    Result.ok({
+      permitId: ctx.permit?.id,
+      requestId: ctx.requestId,
+    }),
+  input: z.object({}),
+  intent: 'read',
+  output: z.object({
+    permitId: z.string().optional(),
+    requestId: z.string().optional(),
+  }),
+  permit: { scopes: ['thing:read'] },
+});
+
+const abortingTrail = trail('abort.check', {
+  blaze: (_input, ctx) => Result.ok({ aborted: ctx.abortSignal.aborted }),
+  input: z.object({}),
+  intent: 'read',
+  output: z.object({ aborted: z.boolean() }),
+});
+
+const webhookSecret = 'secret';
+const paymentWebhook = webhook('webhook.payment.received', {
+  parse: z.object({ paymentId: z.string() }),
+  path: '/webhooks/payment',
+  verify: (request) =>
+    getWebhookHeader(request, 'x-webhook-secret') === webhookSecret
+      ? Result.ok()
+      : Result.err(new PermissionError('Invalid webhook secret')),
+});
+
+const paymentWebhookTrail = trail('payment.receive', {
+  blaze: (input) => Result.ok({ paymentId: input.paymentId }),
+  input: z.object({ paymentId: z.string() }),
+  on: [paymentWebhook],
+  output: z.object({ paymentId: z.string() }),
+});
+
+const buildRequest = (path: string, init: RequestInit = {}): Request =>
+  new Request(new URL(path, 'http://localhost').toString(), init);
+
+const readHeader = (
+  headers: HttpHeaderSource | undefined,
+  name: string
+): string | undefined => {
+  if (headers === undefined) {
+    return undefined;
+  }
+  if (headers instanceof Headers) {
+    return headers.get(name) ?? undefined;
+  }
+  const needle = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== needle || value === undefined) {
+      continue;
+    }
+    return typeof value === 'string' ? value : value[0];
+  }
+  return undefined;
+};
+
+const expectJson = async (
+  response: Response
+): Promise<Record<string, unknown>> =>
+  (await response.json()) as Record<string, unknown>;
+
+const materialize = async (
+  adapter: HttpAdapterConformanceAdapter,
+  graph: Topo,
+  options?: HttpAdapterConformanceOptions
+): Promise<HttpAdapterConformanceApp> =>
+  await adapter.createApp(graph, options);
+
+const expectOkResponse = async (
+  response: Response,
+  data: Record<string, unknown>
+): Promise<void> => {
+  expect(response.status).toBe(200);
+  expect(await expectJson(response)).toEqual({ data });
+};
+
+const request = async (
+  adapter: HttpAdapterConformanceAdapter,
+  graph: Topo,
+  path: string,
+  init?: RequestInit,
+  options?: HttpAdapterConformanceOptions
+): Promise<Response> => {
+  const app = await materialize(adapter, graph, options);
+  return await app.fetch(buildRequest(path, init));
+};
+
+const readRouteCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  const response = await request(
+    adapter,
+    topo('http-conformance-read', { echoTrail }),
+    '/echo?message=hello'
+  );
+
+  await expectOkResponse(response, { reply: 'hello' });
+};
+
+const writeRouteCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  const response = await request(
+    adapter,
+    topo('http-conformance-write', { echoBodyTrail }),
+    '/echo/body',
+    {
+      body: JSON.stringify({ message: 'hello' }),
+      headers: { 'Content-Type': 'application/json' },
+      method: 'POST',
+    }
+  );
+
+  await expectOkResponse(response, { length: 5 });
+};
+
+const repeatedQueryCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  const graph = topo('http-conformance-query', { tagsTrail });
+  const repeated = await request(adapter, graph, '/tags?tags=red&tags=blue');
+  const singleton = await request(adapter, graph, '/tags?tags=solo');
+
+  await expectOkResponse(repeated, { tags: ['red', 'blue'] });
+  expect(singleton.status).toBe(400);
+  expect(await expectJson(singleton)).toMatchObject({
+    error: { category: 'validation' },
+  });
+};
+
+const publicErrorCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  const response = await request(
+    adapter,
+    topo('http-conformance-errors', { genericErrorTrail }),
+    '/generic/error',
+    { headers: { 'X-Request-ID': 'req-123 forged/line' } }
+  );
+  const body = await expectJson(response);
+
+  expect(response.status).toBe(500);
+  expect(body).toEqual({
+    error: {
+      category: 'internal',
+      code: 'InternalError',
+      message: 'Internal server error',
+    },
+  });
+  expect(JSON.stringify(body)).not.toContain('secret');
+};
+
+const requestContextCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  let observedTenant: string | null | undefined;
+  const resolvePermit: ResolveHttpPermit = ({ headers }) => {
+    observedTenant = readHeader(headers, 'x-tenant-id');
+    return Result.ok({ id: 'user-1', scopes: ['thing:read'] });
+  };
+  const graph = topo('http-conformance-context', {
+    abortingTrail,
+    protectedTrail,
+  });
+  const app = await materialize(adapter, graph, { resolvePermit });
+  const controller = new AbortController();
+  controller.abort();
+
+  const permitResponse = await app.fetch(
+    buildRequest('/permit/scope', {
+      headers: {
+        Authorization: 'Bearer strong',
+        'X-Request-ID': 'req-1',
+        'X-Tenant-ID': 'tenant-1',
+      },
+    })
+  );
+  const abortResponse = await app.fetch(
+    buildRequest('/abort/check', { signal: controller.signal })
+  );
+
+  await expectOkResponse(permitResponse, {
+    permitId: 'user-1',
+    requestId: 'req-1',
+  });
+  expect(observedTenant).toBe('tenant-1');
+  await expectOkResponse(abortResponse, { aborted: true });
+};
+
+const webhookCase = async (
+  adapter: HttpAdapterConformanceAdapter
+): Promise<void> => {
+  const graph = topo('http-conformance-webhooks', { paymentWebhookTrail });
+  const verified = await request(adapter, graph, '/webhooks/payment', {
+    body: JSON.stringify({ paymentId: 'pay_1' }),
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Webhook-Secret': webhookSecret,
+    },
+    method: 'POST',
+  });
+  const denied = await request(adapter, graph, '/webhooks/payment', {
+    body: JSON.stringify({ paymentId: 'pay_1' }),
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Webhook-Secret': 'wrong',
+    },
+    method: 'POST',
+  });
+  const invalidPayload = await request(adapter, graph, '/webhooks/payment', {
+    body: JSON.stringify({ paymentId: 123 }),
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Webhook-Secret': webhookSecret,
+    },
+    method: 'POST',
+  });
+
+  await expectOkResponse(verified, { paymentId: 'pay_1' });
+  expect(denied.status).toBe(403);
+  expect(await expectJson(denied)).toMatchObject({
+    error: { category: 'permission' },
+  });
+  expect(invalidPayload.status).toBe(400);
+  expect(await expectJson(invalidPayload)).toMatchObject({
+    error: { category: 'validation' },
+  });
+};
+
+export const createHttpAdapterConformanceCases =
+  (): readonly HttpAdapterConformanceCase[] => [
+    { check: readRouteCase, name: 'serves read trails from query parameters' },
+    { check: writeRouteCase, name: 'serves write trails from JSON bodies' },
+    {
+      check: repeatedQueryCase,
+      name: 'preserves repeated query keys before validation',
+    },
+    {
+      check: publicErrorCase,
+      name: 'projects generic errors as redacted public 500 responses',
+    },
+    {
+      check: requestContextCase,
+      name: 'threads request context and abort signals',
+    },
+    { check: webhookCase, name: 'handles webhook verification and parsing' },
+  ];
+
+export const runConformance = (
+  adapter: HttpAdapterConformanceAdapter,
+  cases: readonly HttpAdapterConformanceCase[] = createHttpAdapterConformanceCases()
+): void => {
+  describe(`${adapter.name} HTTP adapter conformance`, () => {
+    for (const conformanceCase of cases) {
+      test(conformanceCase.name, async () => {
+        await conformanceCase.check(adapter);
+      });
+    }
+  });
+};