@ontrails/testing 1.0.0-beta.3 → 1.0.0-beta.30

package/CHANGELOG.md

@@ -1,18 +1,488 @@
 # @ontrails/testing
 
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.30
+- @ontrails/core@1.0.0-beta.30
+- @ontrails/http@1.0.0-beta.30
+- @ontrails/mcp@1.0.0-beta.30
+- @ontrails/observe@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.29
+- @ontrails/core@1.0.0-beta.29
+- @ontrails/http@1.0.0-beta.29
+- @ontrails/mcp@1.0.0-beta.29
+- @ontrails/observe@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.28
+- @ontrails/core@1.0.0-beta.28
+- @ontrails/http@1.0.0-beta.28
+- @ontrails/mcp@1.0.0-beta.28
+- @ontrails/observe@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.27
+- @ontrails/core@1.0.0-beta.27
+- @ontrails/http@1.0.0-beta.27
+- @ontrails/mcp@1.0.0-beta.27
+- @ontrails/observe@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/cli@1.0.0-beta.26
+  - @ontrails/http@1.0.0-beta.26
+  - @ontrails/mcp@1.0.0-beta.26
+  - @ontrails/observe@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [a9fdbc7]
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [2c08afe]
+- Updated dependencies [f1e6efa]
+- Updated dependencies [f1e6efa]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+- Updated dependencies [f7d97fc]
+- Updated dependencies [df13faf]
+  - @ontrails/mcp@1.0.0-beta.25
+  - @ontrails/core@1.0.0-beta.25
+  - @ontrails/http@1.0.0-beta.25
+  - @ontrails/cli@1.0.0-beta.25
+  - @ontrails/observe@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.24
+- @ontrails/core@1.0.0-beta.24
+- @ontrails/http@1.0.0-beta.24
+- @ontrails/mcp@1.0.0-beta.24
+- @ontrails/observe@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- Updated dependencies [9c5ecdc]
+  - @ontrails/http@1.0.0-beta.23
+  - @ontrails/cli@1.0.0-beta.23
+  - @ontrails/core@1.0.0-beta.23
+  - @ontrails/mcp@1.0.0-beta.23
+  - @ontrails/observe@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.22
+- @ontrails/core@1.0.0-beta.22
+- @ontrails/http@1.0.0-beta.22
+- @ontrails/mcp@1.0.0-beta.22
+- @ontrails/observe@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+  - @ontrails/cli@1.0.0-beta.21
+  - @ontrails/http@1.0.0-beta.21
+  - @ontrails/mcp@1.0.0-beta.21
+  - @ontrails/observe@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- Updated dependencies [851a2a3]
+- Updated dependencies [9bec01c]
+- Updated dependencies [accb9ec]
+  - @ontrails/core@1.0.0-beta.20
+  - @ontrails/mcp@1.0.0-beta.20
+  - @ontrails/cli@1.0.0-beta.20
+  - @ontrails/http@1.0.0-beta.20
+  - @ontrails/observe@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Major Changes
+
+- 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.
+
+### Minor Changes
+
+- 492f71c: Move CLI, MCP, HTTP, established-surface, and surface-parity helpers behind explicit subpaths so root contract testing imports no longer require optional surface peers. The Trails CLI scaffolder now emits `import { testAllEstablished } from '@ontrails/testing/established'` for generated verification.
+
+### 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.
+- f8d80b9: Refresh current-facing compose vocabulary in package documentation after the composition cutover.
+- 337b467: Construct declared Trails error classes when `testComposes` injects composed trail error examples.
+- 16cb740: Run examples and contract checks across live trail version entries, and project version-entry example coverage into topo and survey reports.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- f04a9ef: Tighten trail-versioning API polish by keeping executor cross-validation internals out of public options and improving absent marker diagnostics.
+- Updated dependencies [e41c382]
+- Updated dependencies [a2f1825]
+- Updated dependencies [a2f1825]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [94a8380]
+- Updated dependencies [94a8380]
+- Updated dependencies [846a597]
+- Updated dependencies [8638dae]
+- Updated dependencies [8638dae]
+- Updated dependencies [8638dae]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [92e709b]
+- 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/cli@1.0.0-beta.19
+  - @ontrails/http@1.0.0-beta.19
+  - @ontrails/mcp@1.0.0-beta.19
+  - @ontrails/observe@1.0.0-beta.19
+
+## 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
+
+- 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
+
+- f511a3a: Rename `app` field to `graph` in `CliHarnessOptions` and `McpHarnessOptions`
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/cli@1.0.0-beta.15
+  - @ontrails/observe@1.0.0-beta.15
+  - @ontrails/mcp@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @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
+
+## 1.0.0-beta.13
+
+### Minor Changes
+
+- Trail-native vocabulary cutover. Breaking API field renames across all packages:
+
+  - Trail spec: `run:` → `blaze:`, `follow:` → `crosses:`, `services:` → `provisions:`, `metadata:` → `meta:`, `emits:` → `signals:`
+  - Runtime: `ctx.follow()` → `ctx.cross()`, `ctx.emit()` → `ctx.signal()`, `ctx.signal` (abort) → `ctx.abortSignal`
+  - Entry points: `blaze(app)` → `trailhead(app)`
+  - Package rename: `@ontrails/crumbs` → `@ontrails/tracker`
+  - Wrapper types: `Layer` → `Gate`, `layers`/`middleware` → `gates`
+  - Transport: `surface` → `trailhead`, `adapter` → `connector`
+
+### Patch Changes
+
+- 6944147: Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `configGate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authService` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured signal tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Updated dependencies [6944147]
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.13
+  - @ontrails/cli@1.0.0-beta.13
+  - @ontrails/mcp@1.0.0-beta.13
+  - @ontrails/logging@1.0.0-beta.13
+
+## 1.0.0-beta.12
+
+### Patch Changes
+
+- Complete trifecta for config, permits, and tracker (formerly tracks)
+
+  - **config**: Add `configProvision`, `config.gate`, `config.trail`, and `config.workspace` trails with full `defineConfig`, `resolve`, `describe`, `explain`, `doctor`, and code generation support
+  - **permits**: Add `authProvision` and `auth.verify` trail for runtime authorization checks
+  - **tracker**: Rename tracks to tracker; add `trackerProvision` and `tracker.status` trail for structured event tracking
+  - **cli**: Fix build flag handling and improve bootstrap scaffolding
+  - **testing**: Expand test context helpers and example-based testing utilities
+  - **core/mcp/http**: Internal alignment for provision and composition updates
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.12
+  - @ontrails/cli@1.0.0-beta.12
+  - @ontrails/mcp@1.0.0-beta.12
+  - @ontrails/logging@1.0.0-beta.12
+
+## 1.0.0-beta.11
+
+### Minor Changes
+
+- Add provisions as a first-class primitive.
+
+  Provisions make infrastructure dependencies declarative, injectable, and governable. Define a provision with `provision()`, declare it on a trail with `provisions: [db]`, and access it with `db.from(ctx)` or `ctx.provision()`.
+
+  **Core:** `provision()` factory, `ProvisionSpec<T>`, `ProvisionContext`, singleton resolution in `executeTrail`, in-flight creation dedup, `isProvision` guard, `findDuplicateProvisionId`, topo provision discovery and validation, `provisions` field on trail specs.
+
+  **Testing:** Auto-resolution of `mock` factories in `testAll`, `testExamples`, `testContracts`, and `testCrosses`. Explicit `provisions` overrides with correct precedence (`explicit > ctx.extensions > auto-mock`). Provision mock propagation through crossing graphs.
+
+  **Warden:** `provision-declarations` rule validates `db.from(ctx)` and `ctx.provision()` usage matches declared `provisions: [...]`. `provision-exists` rule validates declared provision IDs resolve in project context. Scope-aware AST walking skips nested function boundaries.
+
+  **Trailheads:** Provision overrides thread through `run` and `trailhead` on CLI, MCP, and HTTP.
+
+  **Introspection:** Survey and trailhead map outputs include provision graph. Topo exposes `.provisions`, `.getProvision()`, `.hasProvision()`, `.listProvisions()`, `.provisionIds()`, `.provisionCount`.
+
+  **Docs:** ADR-009 accepted. Unified services guide, updated vocabulary, getting-started, architecture, and package READMEs.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.11
+  - @ontrails/cli@1.0.0-beta.11
+  - @ontrails/mcp@1.0.0-beta.11
+  - @ontrails/logging@1.0.0-beta.11
+
+## 1.0.0-beta.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.10
+  - @ontrails/cli@1.0.0-beta.10
+  - @ontrails/mcp@1.0.0-beta.10
+  - @ontrails/logging@1.0.0-beta.10
+
+## 1.0.0-beta.9
+
+### Minor Changes
+
+- Consolidated improvements across all trailhead packages.
+
+  **core**: Add `TrailResult<T>` utility type, `topo.ids()` and `topo.count` accessors, `run()` for headless trail execution, and extract shared `executeTrail` pipeline used by CLI/MCP/HTTP.
+
+  **http**: Detect route path collisions and return `Result` from `buildHttpRoutes()`, wire request `AbortSignal` through to trail context, and make write → POST mapping explicit in intent-to-method lookup.
+
+  **mcp**: Return `Result` from `buildMcpTools()` on collision instead of throwing.
+
+  **cli**: Verify exception catching via centralized `executeTrail`.
+
+  **testing**: Cross-context awareness improvements.
+
+  **warden**: Refactor rules as composable trails with examples.
+
+  **schema**: Error code and empty body fixes.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.9
+  - @ontrails/cli@1.0.0-beta.9
+  - @ontrails/mcp@1.0.0-beta.9
+  - @ontrails/logging@1.0.0-beta.9
+
+## 1.0.0-beta.8
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.8
+- @ontrails/core@1.0.0-beta.8
+- @ontrails/logging@1.0.0-beta.8
+- @ontrails/mcp@1.0.0-beta.8
+
+## 1.0.0-beta.7
+
+### Patch Changes
+
+- @ontrails/cli@1.0.0-beta.7
+- @ontrails/core@1.0.0-beta.7
+- @ontrails/logging@1.0.0-beta.7
+- @ontrails/mcp@1.0.0-beta.7
+
+## 1.0.0-beta.6
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.6
+  - @ontrails/cli@1.0.0-beta.6
+  - @ontrails/logging@1.0.0-beta.6
+  - @ontrails/mcp@1.0.0-beta.6
+
+## 1.0.0-beta.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.5
+  - @ontrails/logging@1.0.0-beta.5
+  - @ontrails/cli@1.0.0-beta.5
+  - @ontrails/mcp@1.0.0-beta.5
+
+## 1.0.0-beta.4
+
+### Major Changes
+
+- API simplification: unified trail model, intent enum, run, metadata.
+
+  **BREAKING CHANGES:**
+
+  - `hike()` removed — use `trail()` with optional `crosses: [...]` field
+  - `follows` renamed to `crosses` (matching `ctx.cross()`)
+  - `topo.hikes` removed — single `topo.trails` map
+  - `kind: 'hike'` removed — everything is `kind: 'trail'`
+  - `readOnly`/`destructive` booleans replaced by `intent: 'read' | 'write' | 'destroy'`
+  - `implementation` field renamed to `run`
+  - `markers` field renamed to `metadata`
+  - `testHike` renamed to `testCrosses`, `HikeScenario` to `CrossScenario`
+  - `trailhead()` now returns the trailhead handle (`Command` for CLI, `Server` for MCP)
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.4
+  - @ontrails/cli@1.0.0-beta.4
+  - @ontrails/mcp@1.0.0-beta.4
+  - @ontrails/logging@1.0.0-beta.4
+
 ## 1.0.0-beta.3
 
 ### Minor Changes
 
-- Bug fixes across all surface packages found via parallel Codex review.
+- Bug fixes across all trailhead packages found via parallel Codex review.
 
   **core**: Fix Result.toJson false circular detection on DAGs, deserializeError subclass round-trip, topo cross-kind ID collisions, validateTopo multi-node cycle detection, error example input validation bypass, and deriveFields array type collapse.
 
-  **cli**: Switch blaze to parseAsync for proper async error handling, add boolean flag negation (--no-flag), and strict number parsing that rejects partial input.
+  **cli**: Switch trailhead to parseAsync for proper async error handling, add boolean flag negation (--no-flag), and strict number parsing that rejects partial input.
 
   **mcp**: Align BlobRef with core (including ReadableStream support) and detect tool-name collisions after normalization.
 
-  **testing**: Include hikes in testContracts validation, with follow-context awareness.
+  **testing**: Include hikes in testContracts validation, with cross-context awareness.
 
   **warden**: Collect hike detour targets, validate detour refs in hike specs, and stop implementation-returns-result from walking into nested function bodies.
 
@@ -56,12 +526,12 @@
 - Initial v1 beta release of the Trails framework.
 
   - **@ontrails/core** — Result type, error taxonomy, trail/hike/event/topo, validateTopo, validateInput/Output, deriveFields, patterns, redaction, branded types, resilience
-  - **@ontrails/cli** — CLI surface adapter, Commander integration, flag derivation, layers
-  - **@ontrails/mcp** — MCP surface adapter, tool generation, annotations, progress bridge
-  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape adapter
-  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, surface harnesses
+  - **@ontrails/cli** — CLI trailhead connector, Commander integration, flag derivation, gates
+  - **@ontrails/mcp** — MCP trailhead connector, tool generation, annotations, progress bridge
+  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape connector
+  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, trailhead harnesses
   - **@ontrails/warden** — AST-based code convention rules via oxc-parser, drift detection, CI formatters
-  - **@ontrails/schema** — Surface map generation, hashing, semantic diffing
+  - **@ontrails/schema** — Trailhead map generation, hashing, semantic diffing
 
 ### Patch Changes
 

package/README.md

@@ -1,14 +1,14 @@
 # @ontrails/testing
 
-Contract-driven testing for Trails. Add examples to your trails, then `testAll(app)` 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
 
 ```typescript
 import { testAll } from '@ontrails/testing';
-import { app } from '../app';
+import { graph } from '../app';
 
-testAll(app);
+testAll(graph);
 ```
 
 That single call covers example execution, contract validation, detour checks, and topo validation. For most apps, this is all you need.
@@ -18,25 +18,23 @@ If you want finer control:
 ```typescript
 import { testExamples, testContracts, testDetours } from '@ontrails/testing';
 
-testExamples(app);   // Run every trail's examples as tests
-testContracts(app);  // Validate outputs against declared schemas
-testDetours(app);    // Verify detour targets exist
+testExamples(graph);   // Run every trail's examples as tests
+testContracts(graph);  // Validate outputs against declared schemas
+testDetours(graph);    // Validate detour constructor, recover, and ordering semantics
 ```
 
 ## API
 
 | 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 and error paths |
-| `testHike(hike, scenarios)` | Test composition graphs -- follow chains, failure injection |
-| `testContracts(topo, ctx?)` | Validate implementation output against declared schemas |
-| `testDetours(topo)` | Verify every detour target exists in the topo |
+| `testTrail(trail, scenarios)` | Custom scenarios for edge cases, error paths, and composition chains |
+| `testContracts(topo, ctx?)` | Validate output against declared schemas |
+| `testDetours(topo)` | Validate detour constructor, recover, and shadowing semantics |
+| `createComposeContext(options?)` | Mock `ComposeFn` 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 |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
@@ -55,37 +53,103 @@ testTrail(showTrail, [
 ]);
 ```
 
-## testHike
+## Testing composition (trails with composes)
 
-Where `testTrail` exercises a single trail, `testHike` exercises the follow graph:
+`testTrail` works the same for trails with `composes` -- it exercises the composition graph:
 
 ```typescript
-import { testHike } from '@ontrails/testing';
+import { testTrail } from '@ontrails/testing';
 
-testHike(onboardHike, [
+testTrail(onboardTrail, [
   { description: 'happy path', input: { name: 'Delta', type: 'tool' }, expectOk: true },
   { description: 'add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
 ]);
 ```
 
-## Surface harnesses
+When you need to isolate a composite trail and stub out its dependencies, use `createComposeContext`:
+
+```typescript
+import { createComposeContext, testTrail } from '@ontrails/testing';
+import { Result } from '@ontrails/core';
+
+const compose = createComposeContext({
+  responses: {
+    'entity.add': Result.ok({ id: '1', name: 'Delta', type: 'tool' }),
+    'search': Result.ok({ results: [] }),
+  },
+});
+testTrail(onboardTrail, [
+  {
+    description: 'uses mocked composes',
+    input: { name: 'Delta', type: 'tool' },
+    expectOk: true,
+  },
+], { compose });
+```
+
+Calls to unregistered trail IDs return `Result.err` with a descriptive message, so missing stubs fail loudly.
+
+## Surface Harnesses
+
+Surface harnesses live on explicit subpaths so projects that only import contract helpers from `@ontrails/testing` do not need CLI, MCP, or HTTP peers. Install the peer package for the subpath you use:
+
+- `@ontrails/testing/cli` requires `@ontrails/cli`
+- `@ontrails/testing/mcp` requires `@ontrails/mcp`
+- `@ontrails/testing/http` requires `@ontrails/http`
+- `@ontrails/testing/established` and `@ontrails/testing/surface-parity`
+  require all three shipped surface peers
 
 ```typescript
-import { createCliHarness, createMcpHarness } from '@ontrails/testing';
+import { createCliHarness } from '@ontrails/testing/cli';
+import { createHttpHarness } from '@ontrails/testing/http';
+import { createMcpHarness } from '@ontrails/testing/mcp';
 
 // CLI
-const cli = createCliHarness({ app });
+const cli = createCliHarness({ graph });
 const result = await cli.run('entity show --name Alpha --output json');
 expect(result.exitCode).toBe(0);
 
 // MCP
-const mcp = createMcpHarness({ app });
+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);
+```
+
+Use `testAllEstablished()` from `@ontrails/testing/established` when an established app should run the root contract suite and validate CLI, MCP, and HTTP projections in one call.
+
+## 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/surface-parity';
+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
-bun add -d @ontrails/testing
+bun add -d @ontrails/testing@beta
 ```