@ontrails/testing 1.0.0-beta.16 → 1.0.0-beta.18

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @ontrails/testing
 
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- Updated dependencies [c0b2948]
+- Updated dependencies [fc3219c]
+- Updated dependencies [bc2d327]
+- Updated dependencies [bf44972]
+- Updated dependencies [e0ae995]
+  - @ontrails/http@1.0.0-beta.18
+  - @ontrails/observe@1.0.0-beta.18
+  - @ontrails/cli@1.0.0-beta.18
+  - @ontrails/core@1.0.0-beta.18
+  - @ontrails/mcp@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- ce42573: Add an example-driven CLI/MCP/HTTP surface parity helper.
+- e1eb4ee: Add an HTTP surface harness and include HTTP projection validation in `testAllEstablished`.
+- Updated dependencies [3dc8254]
+- Updated dependencies [61497c5]
+  - @ontrails/core@1.0.0-beta.17
+  - @ontrails/cli@1.0.0-beta.17
+  - @ontrails/http@1.0.0-beta.17
+  - @ontrails/mcp@1.0.0-beta.17
+  - @ontrails/observe@1.0.0-beta.17
+
 ## 1.0.0-beta.16
 
 ### Minor Changes

package/README.md

@@ -32,11 +32,13 @@ testDetours(graph);    // Validate detour constructor, recover, and ordering sem
 | `testTrail(trail, scenarios)` | Custom scenarios for edge cases, error paths, and cross chains |
 | `testContracts(topo, ctx?)` | Validate output against declared schemas |
 | `testDetours(topo)` | Validate detour constructor, recover, and shadowing semantics |
+| `testSurfaceParity(topo, options?)` | Run trail examples through CLI, MCP, and HTTP and compare normalized semantics |
 | `createCrossContext(options?)` | Mock `CrossFn` for testing composite trails; returns preconfigured `Result` values keyed by trail ID |
 | `createTestContext(options?)` | `TrailContext` with sensible test defaults |
 | `createTestLogger()` | Logger that captures entries in memory for assertions |
 | `createCliHarness(options)` | Execute CLI commands in-process, capture stdout/stderr |
 | `createMcpHarness(options)` | Invoke MCP tools directly without transport |
+| `createHttpHarness(options)` | Execute HTTP route projections in-process without a server |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
@@ -89,7 +91,11 @@ Calls to unregistered trail IDs return `Result.err` with a descriptive message,
 ## Surface Harnesses
 
 ```typescript
-import { createCliHarness, createMcpHarness } from '@ontrails/testing';
+import {
+  createCliHarness,
+  createHttpHarness,
+  createMcpHarness,
+} from '@ontrails/testing';
 
 // CLI
 const cli = createCliHarness({ graph });
@@ -100,8 +106,46 @@ expect(result.exitCode).toBe(0);
 const mcp = createMcpHarness({ graph });
 const tool = await mcp.callTool('myapp_entity_show', { name: 'Alpha' });
 expect(tool.isError).toBe(false);
+
+// HTTP
+const http = createHttpHarness({ graph });
+const response = await http.get('/entity/show', { name: 'Alpha' });
+expect(response.status).toBe(200);
+```
+
+## Surface Parity
+
+`testSurfaceParity()` is a focused gate for established apps that want to prove
+their examples behave the same through every shipped surface.
+
+```typescript
+import { testSurfaceParity } from '@ontrails/testing';
+import { graph } from '../app';
+
+const createDeterministicTestDb = () => ({});
+
+testSurfaceParity(graph, {
+  createResources: () => ({
+    'db.main': createDeterministicTestDb(),
+  }),
+  exclusions: [
+    {
+      example: 'Creates generated data',
+      reason: 'output includes generated IDs that intentionally differ per surface run',
+      trailId: 'entity.add',
+    },
+  ],
+});
 ```
 
+The helper compares normalized success payloads and normalized TrailsError
+category/code pairs. CLI command names, MCP tool names, HTTP method/path values,
+transport envelopes, activation consumers, internal trails, and planned
+WebSocket work stay outside the equality check. Use `createResources` when
+examples need deterministic fixtures for each surface invocation, and use
+exclusions for intentional semantic differences that should not be silently
+skipped.
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.18",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,14 +22,15 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
-    "@ontrails/drizzle": "^1.0.0-beta.15",
-    "@ontrails/store": "^1.0.0-beta.15"
+    "@ontrails/drizzle": "^1.0.0-beta.17",
+    "@ontrails/store": "^1.0.0-beta.17"
   },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.15",
-    "@ontrails/core": "^1.0.0-beta.15",
-    "@ontrails/mcp": "^1.0.0-beta.15",
-    "@ontrails/observe": "^1.0.0-beta.15",
+    "@ontrails/cli": "^1.0.0-beta.17",
+    "@ontrails/core": "^1.0.0-beta.17",
+    "@ontrails/http": "^1.0.0-beta.17",
+    "@ontrails/mcp": "^1.0.0-beta.17",
+    "@ontrails/observe": "^1.0.0-beta.17",
     "zod": "^4.3.5"
   }
 }

package/src/all.ts

@@ -11,6 +11,7 @@ import type { Topo, TrailContext } from '@ontrails/core';
 import { validateEstablishedTopo, validateTopo } from '@ontrails/core';
 
 import { createCliHarness } from './harness-cli.js';
+import { createHttpHarness } from './harness-http.js';
 import { createMcpHarness } from './harness-mcp.js';
 import { testContracts } from './contracts.js';
 import type { TestExecutionOptions } from './context.js';
@@ -108,6 +109,7 @@ const isEstablishedOptions = (
   (Object.hasOwn(input, 'cli') ||
     Object.hasOwn(input, 'createPermit') ||
     Object.hasOwn(input, 'ctx') ||
+    Object.hasOwn(input, 'http') ||
     Object.hasOwn(input, 'mcp') ||
     Object.hasOwn(input, 'resources') ||
     Object.hasOwn(input, 'strictPermits'));
@@ -154,6 +156,22 @@ const toMcpHarnessOptions = (
   ...options.mcp,
 });
 
+const toHttpHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => {
+  const httpOptions = {
+    graph: topo,
+    ...options.http,
+  };
+
+  if (options.ctx !== undefined) {
+    httpOptions.ctx = options.ctx;
+  }
+
+  return httpOptions;
+};
+
 const registerEstablishedSurfaceSuite = (
   topo: Topo,
   resolveInput: () =>
@@ -175,6 +193,13 @@ const registerEstablishedSurfaceSuite = (
         createMcpHarness(toMcpHarnessOptions(topo, options))
       ).not.toThrow();
     });
+
+    test('HTTP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createHttpHarness(toHttpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
   });
 };
 

package/src/harness-cli.ts

@@ -8,6 +8,7 @@
 import { deriveCliCommands } from '@ontrails/cli';
 import type { CliCommand } from '@ontrails/cli';
 import type { TrailContext } from '@ontrails/core';
+import { projectPublicSurfaceError } from '@ontrails/core';
 
 import { mergeTestContext } from './context.js';
 import type {
@@ -207,10 +208,16 @@ const buildErrorResult = (
   streams: CapturedStreams
 ): CliHarnessResult => {
   streams.restore();
-  const message = error instanceof Error ? error.message : String(error);
+  const actualError = error instanceof Error ? error : new Error(String(error));
+  const projection = projectPublicSurfaceError('cli', actualError);
   return {
+    error: {
+      category: projection.category,
+      code: projection.name,
+      message: projection.message,
+    },
     exitCode: 1,
-    stderr: streams.getStderr() || message,
+    stderr: streams.getStderr() || projection.message,
     stdout: streams.getStdout(),
   };
 };
@@ -227,9 +234,15 @@ const executeCommand = async (
   streams.restore();
 
   if (result.isErr()) {
+    const projection = projectPublicSurfaceError('cli', result.error);
     return {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
       exitCode: 1,
-      stderr: streams.getStderr() || result.error.message,
+      stderr: streams.getStderr() || projection.message,
       stdout: streams.getStdout(),
     };
   }

package/src/harness-http.ts

@@ -0,0 +1,263 @@
+/**
+ * HTTP integration test harness.
+ *
+ * Builds framework-agnostic HTTP routes from a graph and executes them
+ * directly, without Hono or a listening server.
+ */
+
+import { deriveHttpRoutes } from '@ontrails/http';
+import type { HttpMethod, HttpRouteDefinition } from '@ontrails/http';
+import type { TrailContext, TrailContextInit } from '@ontrails/core';
+import { NotFoundError, projectPublicSurfaceError } from '@ontrails/core';
+
+import { mergeTestContext } from './context.js';
+import type {
+  HttpHarness,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+} from './types.js';
+
+const TEST_ORIGIN = 'http://ontrails.test';
+
+const normalizeMethod = (method: HttpMethod): HttpMethod =>
+  method.toUpperCase() as HttpMethod;
+
+const collectQueryParams = (url: URL): Record<string, unknown> => {
+  const query: Record<string, unknown> = {};
+  const seen = new Set<string>();
+
+  for (const key of url.searchParams.keys()) {
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    const values = url.searchParams.getAll(key);
+    query[key] = values.length > 1 ? values : values[0];
+  }
+
+  return query;
+};
+
+const findRoute = (
+  routes: readonly HttpRouteDefinition[],
+  method: HttpMethod,
+  path: string
+): HttpRouteDefinition | undefined =>
+  routes.find((route) => route.method === method && route.path === path);
+
+const mapError = (error: Error): HttpHarnessResult => {
+  const projection = projectPublicSurfaceError('http', error);
+  const body = {
+    error: {
+      category: projection.category,
+      code: projection.name,
+      message: projection.message,
+    },
+  };
+  return {
+    body,
+    error: body.error,
+    ok: false,
+    status: projection.code,
+  };
+};
+
+const mapSuccess = (data: unknown): HttpHarnessResult => ({
+  body: { data },
+  data,
+  ok: true,
+  status: 200,
+});
+
+const isWebhookParseResult = (
+  input: unknown
+): input is {
+  readonly error?: Error | undefined;
+  isErr(): boolean;
+  readonly value?: unknown | undefined;
+} =>
+  typeof input === 'object' &&
+  input !== null &&
+  'isErr' in input &&
+  typeof input.isErr === 'function';
+
+const mergeContextInit = (
+  base: TrailContextInit | undefined,
+  ctx: Partial<TrailContext> | undefined
+): TrailContextInit => ({
+  ...base,
+  ...mergeTestContext({ ...base, ...ctx }),
+});
+
+const createHarnessContextFactory = (
+  options: HttpHarnessOptions
+): (() => TrailContextInit | Promise<TrailContextInit>) => {
+  const { createContext, ctx } = options;
+  return async () => {
+    const base = await createContext?.();
+    return mergeContextInit(base, ctx);
+  };
+};
+
+const buildInput = (
+  route: HttpRouteDefinition,
+  url: URL,
+  request: HttpHarnessRequest
+): unknown => {
+  if (route.inputSource === 'query') {
+    return {
+      ...collectQueryParams(url),
+      ...request.query,
+    };
+  }
+  return request.body ?? {};
+};
+
+const executeRouteWithInput = async (
+  route: HttpRouteDefinition,
+  input: unknown,
+  request: HttpHarnessRequest
+): Promise<HttpHarnessResult> => {
+  const result = await route.execute(
+    input,
+    request.requestId,
+    request.abortSignal,
+    { headers: request.headers }
+  );
+
+  if (result.isErr()) {
+    return mapError(result.error);
+  }
+
+  return mapSuccess(result.value);
+};
+
+const executeRoute = async (
+  route: HttpRouteDefinition,
+  url: URL,
+  request: HttpHarnessRequest
+): Promise<HttpHarnessResult> => {
+  const parsedInput = buildInput(route, url, request);
+  if (route.inputSource === 'webhook' && route.parseWebhookInput) {
+    const parsed = route.parseWebhookInput(parsedInput);
+    if (isWebhookParseResult(parsed)) {
+      if (parsed.isErr()) {
+        return mapError(parsed.error ?? new Error('Invalid webhook input'));
+      }
+      return await executeRouteWithInput(route, parsed.value, request);
+    }
+    return await executeRouteWithInput(route, parsed, request);
+  }
+
+  return await executeRouteWithInput(route, parsedInput, request);
+};
+
+// ---------------------------------------------------------------------------
+// createHttpHarness
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an HTTP harness for integration testing.
+ *
+ * @example
+ * ```ts
+ * import { createHttpHarness } from '@ontrails/testing';
+ *
+ * const http = createHttpHarness({ graph });
+ * const result = await http.get('/entity/show', { name: 'Alpha' });
+ * expect(result.status).toBe(200);
+ * ```
+ */
+export const createHttpHarness = (
+  harnessOptions: HttpHarnessOptions
+): HttpHarness => {
+  const { ctx: _ctx, graph, ...deriveOptions } = harnessOptions;
+  const routesResult = deriveHttpRoutes(graph, {
+    ...deriveOptions,
+    createContext: createHarnessContextFactory(harnessOptions),
+  });
+  if (routesResult.isErr()) {
+    throw routesResult.error;
+  }
+  const routes = routesResult.value;
+
+  const request = async (
+    rawRequest: HttpHarnessRequest
+  ): Promise<HttpHarnessResult> => {
+    const method = normalizeMethod(rawRequest.method);
+    const url = new URL(rawRequest.path, TEST_ORIGIN);
+    const route = findRoute(routes, method, url.pathname);
+
+    if (!route) {
+      return mapError(
+        new NotFoundError(`No HTTP route found for ${method} ${url.pathname}`)
+      );
+    }
+
+    return await executeRoute(route, url, { ...rawRequest, method });
+  };
+
+  return {
+    delete: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'DELETE',
+        path,
+      }),
+    get: async (
+      path: string,
+      query?: Record<string, unknown>,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        method: 'GET',
+        path,
+        query: {
+          ...requestOptions?.query,
+          ...query,
+        },
+      }),
+    patch: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'PATCH',
+        path,
+      }),
+    post: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'POST',
+        path,
+      }),
+    put: async (
+      path: string,
+      body?: unknown,
+      requestOptions?: HttpHarnessRequestOptions
+    ) =>
+      await request({
+        ...requestOptions,
+        body,
+        method: 'PUT',
+        path,
+      }),
+    request,
+  };
+};

package/src/harness-mcp.ts

@@ -63,6 +63,8 @@ export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
       return {
         content: result.content,
         isError: result.isError ?? false,
+        meta: result._meta,
+        structuredContent: result.structuredContent,
       };
     },
   };

package/src/index.ts

@@ -6,6 +6,10 @@ export { testCrosses } from './crosses.js';
 export { testTrail } from './trail.js';
 export { testContracts } from './contracts.js';
 export { testDetours } from './detours.js';
+export {
+  runSurfaceParityExample,
+  testSurfaceParity,
+} from './surface-parity.js';
 
 // Assertions
 export {
@@ -32,6 +36,7 @@ export { createTestLogger } from './logger.js';
 
 // Surface harnesses
 export { createCliHarness } from './harness-cli.js';
+export { createHttpHarness } from './harness-http.js';
 export { createMcpHarness } from './harness-mcp.js';
 
 // Types
@@ -54,7 +59,19 @@ export type {
   CliHarness,
   CliHarnessOptions,
   CliHarnessResult,
+  HttpHarness,
+  HttpHarnessErrorBody,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+  HttpHarnessSuccessBody,
   McpHarness,
   McpHarnessOptions,
   McpHarnessResult,
+  NormalizedSurfaceParityResult,
+  SurfaceParityExclusion,
+  SurfaceParityOptions,
+  SurfaceParitySurface,
 } from './types.js';
+export type { SurfaceParityComparison } from './surface-parity.js';

package/src/surface-parity.ts

@@ -0,0 +1,356 @@
+/**
+ * Example-driven parity checks across shipped surfaces.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { deriveCliPath, filterSurfaceTrails } from '@ontrails/core';
+import type { Topo, Trail, TrailContext, TrailExample } from '@ontrails/core';
+import { deriveHttpInputSource, deriveHttpMethod } from '@ontrails/http';
+import type { HttpMethod } from '@ontrails/http';
+import { MCP_TOOL_ERROR_META_KEY, deriveToolName } from '@ontrails/mcp';
+
+import {
+  createMockResources,
+  defaultCreatePermit,
+  mergeResourceOverrides,
+  mergeTestContext,
+} from './context.js';
+import { deriveTrailExamples } from './effective-examples.js';
+import { createCliHarness } from './harness-cli.js';
+import { createHttpHarness } from './harness-http.js';
+import { createMcpHarness } from './harness-mcp.js';
+import type {
+  CliHarnessResult,
+  HttpHarnessResult,
+  McpHarnessResult,
+  NormalizedSurfaceParityResult,
+  SurfaceParityExclusion,
+  SurfaceParityOptions,
+} from './types.js';
+
+type ParityTrail = Trail<unknown, unknown, unknown>;
+
+export interface SurfaceParityComparison {
+  readonly cli: NormalizedSurfaceParityResult;
+  readonly http: NormalizedSurfaceParityResult;
+  readonly mcp: NormalizedSurfaceParityResult;
+}
+
+const httpPathForTrail = (trailId: string): string =>
+  `/${trailId.replaceAll('.', '/')}`;
+
+const escapeWhitespaceForCliToken = (value: string): string =>
+  value.replaceAll(/\s/gu, (char) => {
+    let escaped = '';
+
+    for (let index = 0; index < char.length; index += 1) {
+      const codePoint = char.codePointAt(index);
+
+      if (codePoint !== undefined) {
+        escaped += `\\u${codePoint.toString(16).padStart(4, '0')}`;
+      }
+    }
+
+    return escaped;
+  });
+
+const cliCommandForExample = (
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>
+): string => {
+  const path = deriveCliPath(trail.id).join(' ');
+  const inputJson = escapeWhitespaceForCliToken(
+    JSON.stringify(example.input ?? {})
+  );
+  return `${path} --input-json ${inputJson} --output json`;
+};
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const readTextContent = (content: unknown): string | undefined => {
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+  const firstText = content.find(
+    (item): item is { readonly text: string; readonly type: string } =>
+      isObjectRecord(item) &&
+      item['type'] === 'text' &&
+      typeof item['text'] === 'string'
+  );
+  return firstText?.text;
+};
+
+const parseJsonText = (text: string | undefined): unknown => {
+  if (text === undefined) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+const structuredContentValue = (
+  structuredContent: Record<string, unknown> | undefined
+): unknown => {
+  if (structuredContent === undefined) {
+    return undefined;
+  }
+  const keys = Object.keys(structuredContent);
+  return keys.length === 1 && keys[0] === 'data'
+    ? structuredContent['data']
+    : structuredContent;
+};
+
+const normalizeCliResult = (
+  result: CliHarnessResult
+): NormalizedSurfaceParityResult =>
+  result.exitCode === 0
+    ? { ok: true, value: result.json }
+    : {
+        error: {
+          category: result.error?.category ?? 'internal',
+          code: result.error?.code ?? 'InternalError',
+        },
+        ok: false,
+      };
+
+const normalizeHttpResult = (
+  result: HttpHarnessResult
+): NormalizedSurfaceParityResult =>
+  result.ok
+    ? { ok: true, value: result.data }
+    : {
+        error: {
+          category: result.error?.category ?? 'internal',
+          code: result.error?.code ?? 'InternalError',
+        },
+        ok: false,
+      };
+
+const readMcpError = (
+  result: McpHarnessResult
+): { readonly category: string; readonly code: string } => {
+  const errorMeta = result.meta?.[MCP_TOOL_ERROR_META_KEY];
+  if (isObjectRecord(errorMeta)) {
+    return {
+      category:
+        typeof errorMeta['category'] === 'string'
+          ? errorMeta['category']
+          : 'internal',
+      code:
+        typeof errorMeta['name'] === 'string'
+          ? errorMeta['name']
+          : 'InternalError',
+    };
+  }
+  return { category: 'internal', code: 'InternalError' };
+};
+
+const normalizeMcpResult = (
+  result: McpHarnessResult
+): NormalizedSurfaceParityResult =>
+  result.isError
+    ? { error: readMcpError(result), ok: false }
+    : {
+        ok: true,
+        value:
+          result.structuredContent === undefined
+            ? parseJsonText(readTextContent(result.content))
+            : structuredContentValue(result.structuredContent),
+      };
+
+const applyAutoPermit = (
+  ctx: TrailContext,
+  trail: ParityTrail,
+  options: SurfaceParityOptions
+): TrailContext => {
+  if (options.strictPermits || ctx.permit !== undefined) {
+    return ctx;
+  }
+  const permit = (options.createPermit ?? defaultCreatePermit)(trail);
+  return permit === undefined ? ctx : { ...ctx, permit };
+};
+
+const createInvocationContext = async (
+  app: Topo,
+  trail: ParityTrail,
+  options: SurfaceParityOptions
+) => {
+  const autoResources =
+    options.createResources === undefined
+      ? await createMockResources(app)
+      : await options.createResources();
+  const resources = mergeResourceOverrides(
+    autoResources,
+    options.ctx,
+    options.resources
+  );
+  const ctx = applyAutoPermit(mergeTestContext(options.ctx), trail, options);
+  return { ctx, resources };
+};
+
+const mergeSurfaceContext = (
+  ctx: TrailContext,
+  surfaceCtx: Partial<TrailContext> | undefined
+): TrailContext =>
+  surfaceCtx === undefined ? ctx : mergeTestContext({ ...ctx, ...surfaceCtx });
+
+const runCliExample = async (
+  app: Topo,
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>,
+  options: SurfaceParityOptions
+): Promise<NormalizedSurfaceParityResult> => {
+  const { ctx, resources } = await createInvocationContext(app, trail, options);
+  const cliOptions = options.cli;
+  const harness = createCliHarness({
+    graph: app,
+    ...cliOptions,
+    ctx: mergeSurfaceContext(ctx, cliOptions?.ctx),
+    resources,
+  });
+  return normalizeCliResult(
+    await harness.run(cliCommandForExample(trail, example))
+  );
+};
+
+const runMcpExample = async (
+  app: Topo,
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>,
+  options: SurfaceParityOptions
+): Promise<NormalizedSurfaceParityResult> => {
+  const { ctx, resources } = await createInvocationContext(app, trail, options);
+  const mcpOptions = options.mcp;
+  const harness = createMcpHarness({
+    graph: app,
+    ...mcpOptions,
+    createContext: async () =>
+      mergeSurfaceContext(ctx, await mcpOptions?.createContext?.()),
+    resources,
+  });
+  const toolName = deriveToolName(app.name, trail.id);
+  return normalizeMcpResult(
+    await harness.callTool(
+      toolName,
+      isObjectRecord(example.input) ? example.input : {}
+    )
+  );
+};
+
+const httpRequestForExample = (
+  method: HttpMethod,
+  trailId: string,
+  example: TrailExample<unknown, unknown>
+) => {
+  const input = isObjectRecord(example.input) ? example.input : {};
+  return deriveHttpInputSource(method) === 'query'
+    ? { method, path: httpPathForTrail(trailId), query: input }
+    : { body: input, method, path: httpPathForTrail(trailId) };
+};
+
+const runHttpExample = async (
+  app: Topo,
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>,
+  options: SurfaceParityOptions
+): Promise<NormalizedSurfaceParityResult> => {
+  const { ctx, resources } = await createInvocationContext(app, trail, options);
+  const httpOptions = options.http;
+  const harness = createHttpHarness({
+    graph: app,
+    ...httpOptions,
+    ctx: mergeSurfaceContext(ctx, httpOptions?.ctx),
+    resources,
+  });
+  const method = deriveHttpMethod(trail.intent);
+  return normalizeHttpResult(
+    await harness.request(httpRequestForExample(method, trail.id, example))
+  );
+};
+
+export const runSurfaceParityExample = async (
+  app: Topo,
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>,
+  options: SurfaceParityOptions = {}
+): Promise<SurfaceParityComparison> => {
+  // CLI harness output capture is process-scoped, so keep surface execution
+  // ordered even though MCP and HTTP do not share that constraint.
+  const cli = await runCliExample(app, trail, example, options);
+  const mcp = await runMcpExample(app, trail, example, options);
+  const http = await runHttpExample(app, trail, example, options);
+  return { cli, http, mcp };
+};
+
+const findExclusion = (
+  exclusions: readonly SurfaceParityExclusion[] | undefined,
+  trail: ParityTrail,
+  example: TrailExample<unknown, unknown>
+): SurfaceParityExclusion | undefined =>
+  exclusions?.find(
+    (exclusion) =>
+      exclusion.trailId === trail.id &&
+      (exclusion.example === undefined || exclusion.example === example.name)
+  );
+
+const parityTrails = (app: Topo): readonly ParityTrail[] =>
+  filterSurfaceTrails(app.list()).filter(
+    (trail) => deriveTrailExamples(trail).length > 0
+  );
+
+/**
+ * Register example-driven parity tests for CLI, MCP, and HTTP.
+ *
+ * @example
+ * ```ts
+ * import { testSurfaceParity } from '@ontrails/testing';
+ * import { graph } from '../src/app.js';
+ *
+ * testSurfaceParity(graph);
+ * ```
+ */
+export const testSurfaceParity = (
+  app: Topo,
+  optionsOrFactory?:
+    | SurfaceParityOptions
+    | (() => SurfaceParityOptions | undefined)
+): void => {
+  const resolveOptions =
+    typeof optionsOrFactory === 'function'
+      ? optionsOrFactory
+      : () => optionsOrFactory;
+
+  describe('surface parity', () => {
+    for (const trail of parityTrails(app)) {
+      describe(trail.id, () => {
+        for (const example of deriveTrailExamples(trail)) {
+          const options = resolveOptions() ?? {};
+          const exclusion = findExclusion(options.exclusions, trail, example);
+          const testName = `example: ${example.name}`;
+          if (exclusion !== undefined) {
+            test.skip(`${testName} (excluded: ${exclusion.reason})`, () => {
+              throw new Error('Skipped parity exclusion should not execute');
+            });
+            continue;
+          }
+
+          test(testName, async () => {
+            const comparison = await runSurfaceParityExample(
+              app,
+              trail,
+              example,
+              resolveOptions() ?? {}
+            );
+            expect(comparison.mcp).toEqual(comparison.cli);
+            expect(comparison.http).toEqual(comparison.cli);
+          });
+        }
+      });
+    }
+  });
+};

package/src/types.ts

@@ -3,10 +3,16 @@
  */
 
 import type { DeriveCliCommandsOptions } from '@ontrails/cli';
+import type {
+  DeriveHttpRoutesOptions,
+  HttpHeaderSource,
+  HttpMethod,
+} from '@ontrails/http';
 import type { McpExtra, DeriveMcpToolsOptions } from '@ontrails/mcp';
 import type {
   AnyTrail,
   Logger,
+  ResourceOverrideMap,
   Topo,
   TraceFn,
   TrailContext,
@@ -98,6 +104,13 @@ export interface CliHarness {
 
 /** The result of a CLI harness command execution. */
 export interface CliHarnessResult {
+  readonly error?:
+    | {
+        readonly category: string;
+        readonly code: string;
+        readonly message: string;
+      }
+    | undefined;
   readonly exitCode: number;
   /** Parsed JSON output if --output json was used. */
   readonly json?: unknown | undefined;
@@ -128,8 +141,129 @@ export interface McpHarness {
 export interface McpHarnessResult {
   readonly content: unknown;
   readonly isError: boolean;
+  readonly meta?: Record<string, unknown> | undefined;
+  readonly structuredContent?: Record<string, unknown> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP Harness
+// ---------------------------------------------------------------------------
+
+/** Options for creating an HTTP harness. */
+export interface HttpHarnessOptions extends DeriveHttpRoutesOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly graph: Topo;
 }
 
+export interface HttpHarnessRequest {
+  readonly abortSignal?: AbortSignal | undefined;
+  readonly body?: unknown | undefined;
+  readonly headers?: HttpHeaderSource | undefined;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly query?: Record<string, unknown> | undefined;
+  readonly requestId?: string | undefined;
+}
+
+export interface HttpHarnessRequestOptions extends Omit<
+  HttpHarnessRequest,
+  'body' | 'method' | 'path' | 'query'
+> {
+  readonly query?: Record<string, unknown> | undefined;
+}
+
+/** A test harness for HTTP route projections. */
+export interface HttpHarness {
+  /** Execute a raw HTTP-style harness request. */
+  request(request: HttpHarnessRequest): Promise<HttpHarnessResult>;
+  /** Execute a GET request, reading input from query params. */
+  get(
+    path: string,
+    query?: Record<string, unknown>,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a POST request, reading input from the JSON-like body value. */
+  post(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PUT request. */
+  put(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a PATCH request. */
+  patch(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+  /** Execute a DELETE request. */
+  delete(
+    path: string,
+    body?: unknown,
+    options?: HttpHarnessRequestOptions
+  ): Promise<HttpHarnessResult>;
+}
+
+export interface HttpHarnessErrorBody {
+  readonly error: {
+    readonly category: string;
+    readonly code: string;
+    readonly message: string;
+  };
+}
+
+export interface HttpHarnessSuccessBody {
+  readonly data: unknown;
+}
+
+/** The result of an HTTP harness request. */
+export interface HttpHarnessResult {
+  readonly body: HttpHarnessErrorBody | HttpHarnessSuccessBody;
+  readonly data?: unknown | undefined;
+  readonly error?: HttpHarnessErrorBody['error'] | undefined;
+  readonly ok: boolean;
+  readonly status: number;
+}
+
+// ---------------------------------------------------------------------------
+// Surface parity
+// ---------------------------------------------------------------------------
+
+export type SurfaceParitySurface = 'cli' | 'mcp' | 'http';
+
+export interface SurfaceParityExclusion {
+  /** Optional example name. Omit to exclude every example for the trail. */
+  readonly example?: string | undefined;
+  /** Human-readable reason shown in the skipped test name. */
+  readonly reason: string;
+  /** Trail ID to exclude. */
+  readonly trailId: string;
+}
+
+export interface SurfaceParityOptions extends TestAllEstablishedOptions {
+  readonly createResources?:
+    | (() => ResourceOverrideMap | Promise<ResourceOverrideMap>)
+    | undefined;
+  readonly exclusions?: readonly SurfaceParityExclusion[] | undefined;
+}
+
+export type NormalizedSurfaceParityResult =
+  | {
+      readonly ok: true;
+      readonly value: unknown;
+    }
+  | {
+      readonly error: {
+        readonly category: string;
+        readonly code: string;
+      };
+      readonly ok: false;
+    };
+
 // ---------------------------------------------------------------------------
 // Established verification
 // ---------------------------------------------------------------------------
@@ -150,6 +284,7 @@ export interface TestAllEstablishedOptions {
         | undefined)
     | undefined;
   readonly ctx?: Partial<TrailContext> | undefined;
+  readonly http?: Omit<HttpHarnessOptions, 'graph'> | undefined;
   readonly mcp?: Omit<McpHarnessOptions, 'graph'> | undefined;
   readonly resources?: Record<string, unknown> | undefined;
   readonly strictPermits?: boolean | undefined;