@ontrails/testing 1.0.0-beta.15 → 1.0.0-beta.17

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @ontrails/testing
 
+## 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
+
+- bcdc484: Add an explicit `unmockable: { reason }` resource marker and have testing auto-mock resolution skip intentionally unmockable resources.
+- bb1cadf: Rename the generated `testAll` suite from `governance` to `contract`.
+
+### Patch Changes
+
+- d40430d: Remove the retired `@ontrails/logging` workspace from the prerelease package set. Use `@ontrails/observe` for log and trace sink contracts and `@ontrails/logtape` for LogTape forwarding.
+- 193ae78: Migrate testing logger types from the legacy `@ontrails/logging` package to `@ontrails/observe`.
+- Updated dependencies [73622ae]
+- Updated dependencies [e991a5b]
+- Updated dependencies [25f3c5c]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [a8997ed]
+- Updated dependencies [fe03945]
+- Updated dependencies [3395234]
+- Updated dependencies [d40430d]
+- Updated dependencies [bcdc484]
+- Updated dependencies [ed171d5]
+- Updated dependencies [49c2e7d]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [fbd42fc]
+- Updated dependencies [63d1aef]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [ed888e2]
+- Updated dependencies [2e05e27]
+- Updated dependencies [9cdb0f2]
+- Updated dependencies [c8caa5e]
+- Updated dependencies [f4b90c9]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [4e75129]
+- Updated dependencies [47505fe]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [66056ac]
+- Updated dependencies [0bad534]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+  - @ontrails/cli@1.0.0-beta.16
+  - @ontrails/mcp@1.0.0-beta.16
+  - @ontrails/observe@1.0.0-beta.16
+
 ## 1.0.0-beta.15
 
 ### Minor Changes
@@ -11,7 +80,7 @@
 - Updated dependencies [4ad6b25]
   - @ontrails/core@1.0.0-beta.15
   - @ontrails/cli@1.0.0-beta.15
-  - @ontrails/logging@1.0.0-beta.15
+  - @ontrails/observe@1.0.0-beta.15
   - @ontrails/mcp@1.0.0-beta.15
 
 ## 1.0.0-beta.14

package/README.md

@@ -1,6 +1,6 @@
 # @ontrails/testing
 
-Contract-driven testing for Trails. Add examples to your trails, then `testAll(graph)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full governance.
+Contract-driven testing for Trails. Add examples to your trails, then `testAll(graph)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full contract coverage.
 
 ## Usage
 
@@ -27,16 +27,18 @@ testDetours(graph);    // Validate detour constructor, recover, and ordering sem
 
 | Export | What it does |
 | --- | --- |
-| `testAll(topo, ctx?)` | Single-line governance suite: validation + examples + contracts + detours |
+| `testAll(topo, ctx?)` | Single-line contract suite: validation + examples + contracts + detours |
 | `testExamples(topo, ctx?)` | Run trail examples as `describe`/`test` blocks |
 | `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,14 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.17",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,14 +22,15 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
-    "@ontrails/drizzle": "^1.0.0-beta.14",
-    "@ontrails/store": "^1.0.0-beta.14"
+    "@ontrails/drizzle": "^1.0.0-beta.16",
+    "@ontrails/store": "^1.0.0-beta.16"
   },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.14",
-    "@ontrails/core": "^1.0.0-beta.14",
-    "@ontrails/logging": "^1.0.0-beta.14",
-    "@ontrails/mcp": "^1.0.0-beta.14",
+    "@ontrails/cli": "^1.0.0-beta.16",
+    "@ontrails/core": "^1.0.0-beta.16",
+    "@ontrails/http": "^1.0.0-beta.16",
+    "@ontrails/mcp": "^1.0.0-beta.16",
+    "@ontrails/observe": "^1.0.0-beta.16",
     "zod": "^4.3.5"
   }
 }

package/src/all.ts

@@ -1,5 +1,5 @@
 /**
- * testAll — single-line governance suite for any Topo.
+ * testAll — single-line contract suite for any Topo.
  *
  * Wraps topo validation, example execution, contract checks, and detour
  * contract validation into one describe block.
@@ -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';
@@ -19,9 +20,9 @@ import { testExamples } from './examples.js';
 import type { TestAllEstablishedOptions } from './types.js';
 
 /**
- * Run the full governance test suite for a Topo.
+ * Run the full contract test suite for a Topo.
  *
- * Generates a `governance` describe block containing:
+ * Generates a `contract` describe block containing:
  * - Structural validation via `validateTopo`
  * - Example execution via `testExamples`
  * - Output contract checks via `testContracts`
@@ -73,12 +74,12 @@ const assertValidTopo = (result: ReturnType<typeof validateTopo>): void => {
   }
 };
 
-const registerGovernanceSuite = (
+const registerContractSuite = (
   topo: Topo,
   ctxOrFactory: TestAllInput | undefined,
   validate: (topo: Topo) => ReturnType<typeof validateTopo>
 ): void => {
-  describe('governance', () => {
+  describe('contract', () => {
     test('topo validates', () => {
       expect(() => assertValidTopo(validate(topo))).not.toThrow();
     });
@@ -93,7 +94,7 @@ const registerGovernanceSuite = (
 };
 
 export const testAll = (topo: Topo, ctxOrFactory?: TestAllInput): void => {
-  registerGovernanceSuite(topo, ctxOrFactory, validateTopo);
+  registerContractSuite(topo, ctxOrFactory, validateTopo);
 };
 
 type EstablishedInput =
@@ -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();
+    });
   });
 };
 
@@ -187,7 +212,7 @@ export const testAllEstablished = (
       ? optionsOrFactory
       : () => optionsOrFactory;
 
-  registerGovernanceSuite(
+  registerContractSuite(
     topo,
     () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
     validateEstablishedTopo

package/src/context.ts

@@ -184,6 +184,9 @@ export const mergeResourceOverrides = (
 const buildMockResources = async (app: Topo): Promise<ResourceOverrideMap> => {
   const resources: Record<string, unknown> = {};
   for (const declaredResource of app.listResources()) {
+    if (declaredResource.unmockable !== undefined) {
+      continue;
+    }
     if (!declaredResource.mock) {
       continue;
     }

package/src/contracts.ts

@@ -26,18 +26,6 @@ import { deriveTrailExamples } from './effective-examples.js';
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Check if a trail requires cross() but the context doesn't provide it. */
-const needsCrossContext = (
-  t: unknown,
-  resolveCtx: () => Partial<TrailContext> | TestExecutionOptions | undefined
-): boolean => {
-  const spec = t as { crosses?: readonly string[] };
-  if (!spec.crosses || spec.crosses.length === 0) {
-    return false;
-  }
-  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.cross;
-};
-
 const validateOutputSchema = (
   outputSchema: z.ZodType,
   value: unknown,
@@ -87,10 +75,6 @@ export const testContracts = (
       if (t.examples.length === 0) {
         return;
       }
-      if (needsCrossContext(t, resolveInput)) {
-        return;
-      }
-
       const { examples, output: outputSchema } = t;
       const successExamples = examples.filter((e) => e.error === undefined);
 
@@ -111,6 +95,7 @@ export const testContracts = (
           const result = await executeTrail(t, example.input, {
             ctx: testCtx,
             resources,
+            topo: app,
           });
           const resultValue = expectOk(result);
 

package/src/examples.ts

@@ -31,6 +31,7 @@ import {
   NetworkError,
   NotFoundError,
   PermissionError,
+  PermitError,
   RateLimitError,
   RetryExhaustedError,
   executeTrail,
@@ -57,6 +58,7 @@ import {
 } from './context.js';
 import type { PermittedTrail, TestExecutionOptions } from './context.js';
 import { isDerivedExample, deriveTrailExamples } from './effective-examples.js';
+import { withSignalAssertions } from './signals.js';
 
 // ---------------------------------------------------------------------------
 // Error class name -> constructor map
@@ -74,6 +76,7 @@ const ERROR_MAP: Record<string, new (...args: never[]) => Error> = {
   NetworkError: NetworkError as new (...args: never[]) => Error,
   NotFoundError: NotFoundError as new (...args: never[]) => Error,
   PermissionError: PermissionError as new (...args: never[]) => Error,
+  PermitError: PermitError as new (...args: never[]) => Error,
   RateLimitError: RateLimitError as new (...args: never[]) => Error,
   RetryExhaustedError: RetryExhaustedError as unknown as new (
     ...args: never[]
@@ -87,7 +90,7 @@ const ERROR_MAP: Record<string, new (...args: never[]) => Error> = {
  * Resolve an error class name string to the actual constructor.
  * Falls back to generic Error if the name is not in the core taxonomy.
  */
-const resolveErrorClass = (name: string): (new (...args: never[]) => Error) =>
+const resolveErrorClass = (name: string): new (...args: never[]) => Error =>
   ERROR_MAP[name] ?? (Error as new (...args: never[]) => Error);
 
 // ---------------------------------------------------------------------------
@@ -162,7 +165,7 @@ const applyAutoPermit = (
  * Run a single example against a trail.
  * Handles validation, execution, and assertions.
  */
-const runExample = async (
+export const runExample = async (
   t: Trail<unknown, unknown, unknown>,
   example: TrailExample<unknown, unknown>,
   output: z.ZodType | undefined,
@@ -170,19 +173,21 @@ const runExample = async (
   resources?: ResourceOverrideMap,
   opts?: TestExecutionOptions
 ): Promise<void> => {
+  const ctx = opts ? applyAutoPermit(testCtx, t, opts) : testCtx;
+  const signals = withSignalAssertions(ctx, example);
   const validated = validateInput(t.input, example.input);
 
   if (handleValidationError(validated, example)) {
+    signals.assert();
     return;
   }
 
-  const ctx = opts ? applyAutoPermit(testCtx, t, opts) : testCtx;
-
   const result = await executeTrail(t, example.input, {
-    ctx,
+    ctx: signals.ctx,
     resources: resources ?? opts?.resources,
   });
   assertProgressiveMatch(result, example, output);
+  signals.assert();
 };
 
 // ---------------------------------------------------------------------------
@@ -267,23 +272,25 @@ const runCompositionExample = async (
   resources?: ResourceOverrideMap,
   opts?: TestExecutionOptions
 ): Promise<void> => {
+  const permittedCtx = opts
+    ? applyAutoPermit(baseCtx, trailDef, opts)
+    : baseCtx;
+  const signals = withSignalAssertions(permittedCtx, example);
   const validated = validateInput(trailDef.input, example.input);
 
   if (handleValidationError(validated, example)) {
+    signals.assert();
     return;
   }
 
-  const permittedCtx = opts
-    ? applyAutoPermit(baseCtx, trailDef, opts)
-    : baseCtx;
   const cross = createCoverageCross(
     called,
-    permittedCtx.cross,
+    signals.ctx.cross,
     topo,
-    permittedCtx,
+    signals.ctx,
     resources
   );
-  const testCtx: TrailContext = { ...permittedCtx, cross };
+  const testCtx: TrailContext = { ...signals.ctx, cross };
 
   // Top-level trail validates against trail.input (not merged crossInput).
   // Merged validation only applies to cross targets in executeFromMap/createCoverageCross.
@@ -292,6 +299,7 @@ const runCompositionExample = async (
     resources: resources ?? opts?.resources,
   });
   assertProgressiveMatch(result, example, output);
+  signals.assert();
 };
 
 // ---------------------------------------------------------------------------

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(),
     };
   }