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

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @ontrails/testing
 
+## 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

package/README.md

@@ -29,16 +29,12 @@ testDetours(graph);    // Validate detour constructor, recover, and ordering sem
 | --- | --- |
 | `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 |
+| `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 |
-| `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 |
+| `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 |
-| `createHttpHarness(options)` | Execute HTTP route projections in-process without a server |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
@@ -57,9 +53,9 @@ testTrail(showTrail, [
 ]);
 ```
 
-## Testing composition (trails with crosses)
+## Testing composition (trails with composes)
 
-`testTrail` works the same for trails with `crosses` -- it exercises the crossing graph:
+`testTrail` works the same for trails with `composes` -- it exercises the composition graph:
 
 ```typescript
 import { testTrail } from '@ontrails/testing';
@@ -70,32 +66,43 @@ testTrail(onboardTrail, [
 ]);
 ```
 
-When you need to isolate a composite trail and stub out its dependencies, use `createCrossContext`:
+When you need to isolate a composite trail and stub out its dependencies, use `createComposeContext`:
 
 ```typescript
-import { createCrossContext, createTestContext } from '@ontrails/testing';
+import { createComposeContext, testTrail } from '@ontrails/testing';
 import { Result } from '@ontrails/core';
 
-const cross = createCrossContext({
+const compose = createComposeContext({
   responses: {
     'entity.add': Result.ok({ id: '1', name: 'Delta', type: 'tool' }),
     'search': Result.ok({ results: [] }),
   },
 });
-const ctx = { ...createTestContext(), cross };
-const result = await onboardTrail.blaze({ name: 'Delta', type: 'tool' }, ctx);
+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,
-  createHttpHarness,
-  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({ graph });
@@ -113,13 +120,14 @@ 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.
+`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 { testSurfaceParity } from '@ontrails/testing/surface-parity';
 import { graph } from '../app';
 
 const createDeterministicTestDb = () => ({});
@@ -138,16 +146,10 @@ testSurfaceParity(graph, {
 });
 ```
 
-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.
+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
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -12,6 +12,11 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./cli": "./src/cli.ts",
+    "./established": "./src/all-established.ts",
+    "./http": "./src/http.ts",
+    "./mcp": "./src/mcp.ts",
+    "./surface-parity": "./src/surface-parity.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -22,15 +27,26 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
-    "@ontrails/drizzle": "^1.0.0-beta.17",
-    "@ontrails/store": "^1.0.0-beta.17"
+    "@ontrails/drizzle": "^1.0.0-beta.19",
+    "@ontrails/store": "^1.0.0-beta.19"
   },
   "peerDependencies": {
-    "@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",
+    "@ontrails/cli": "^1.0.0-beta.19",
+    "@ontrails/core": "^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",
     "zod": "^4.3.5"
+  },
+  "peerDependenciesMeta": {
+    "@ontrails/cli": {
+      "optional": true
+    },
+    "@ontrails/http": {
+      "optional": true
+    },
+    "@ontrails/mcp": {
+      "optional": true
+    }
   }
 }

package/src/all-established.ts

@@ -0,0 +1,168 @@
+/**
+ * testAllEstablished - contract suite plus shipped surface projection checks.
+ *
+ * This helper intentionally lives behind a surface subpath so root
+ * `@ontrails/testing` imports do not pull CLI, MCP, or HTTP peers into
+ * contract-only consumers.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import type { Topo, TrailContext } from '@ontrails/core';
+import { validateEstablishedTopo } from '@ontrails/core';
+
+import { registerContractSuite } from './all.js';
+import type { TestExecutionOptions } from './context.js';
+import { createCliHarness } from './harness-cli.js';
+import type { CliHarnessOptions } from './harness-cli.js';
+import { createHttpHarness } from './harness-http.js';
+import type { HttpHarnessOptions } from './harness-http.js';
+import { createMcpHarness } from './harness-mcp.js';
+import type { McpHarnessOptions } from './harness-mcp.js';
+
+export interface TestAllEstablishedOptions {
+  readonly cli?: Omit<CliHarnessOptions, 'graph'> | undefined;
+  readonly createPermit?:
+    | ((trail: {
+        readonly permit?:
+          | { readonly scopes: readonly string[] }
+          | 'public'
+          | undefined;
+      }) =>
+        | {
+            readonly id: string;
+            readonly scopes: readonly string[];
+          }
+        | 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;
+}
+
+type EstablishedInput =
+  | Partial<TrailContext>
+  | TestAllEstablishedOptions
+  | (() => Partial<TrailContext> | TestAllEstablishedOptions);
+
+const isEstablishedOptions = (
+  input: Partial<TrailContext> | TestAllEstablishedOptions | undefined
+): input is TestAllEstablishedOptions =>
+  input !== undefined &&
+  (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'));
+
+const normalizeEstablishedOptions = (
+  input?: Partial<TrailContext> | TestAllEstablishedOptions
+): TestAllEstablishedOptions =>
+  isEstablishedOptions(input) ? input : { ctx: input };
+
+const toExecutionOptions = (
+  options: TestAllEstablishedOptions
+): TestExecutionOptions => ({
+  ...(options.createPermit === undefined
+    ? {}
+    : { createPermit: options.createPermit }),
+  ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
+  ...(options.resources === undefined ? {} : { resources: options.resources }),
+  ...(options.strictPermits === undefined
+    ? {}
+    : { strictPermits: options.strictPermits }),
+});
+
+const toCliHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => {
+  const cliOptions = {
+    graph: topo,
+    ...options.cli,
+  };
+
+  if (options.ctx !== undefined) {
+    cliOptions.ctx = options.ctx;
+  }
+
+  return cliOptions;
+};
+
+const toMcpHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => ({
+  graph: topo,
+  ...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: () =>
+    | Partial<TrailContext>
+    | TestAllEstablishedOptions
+    | undefined
+): void => {
+  describe('surfaces', () => {
+    test('CLI projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createCliHarness(toCliHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+
+    test('MCP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createMcpHarness(toMcpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+
+    test('HTTP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createHttpHarness(toHttpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+  });
+};
+
+export const testAllEstablished = (
+  topo: Topo,
+  optionsOrFactory?: EstablishedInput
+): void => {
+  const resolveInput =
+    typeof optionsOrFactory === 'function'
+      ? optionsOrFactory
+      : () => optionsOrFactory;
+
+  registerContractSuite(
+    topo,
+    () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
+    validateEstablishedTopo
+  );
+  registerEstablishedSurfaceSuite(topo, resolveInput);
+};
+
+export type { TestAllInput } from './all.js';

package/src/all.ts

@@ -8,16 +8,12 @@
 import { describe, expect, test } from 'bun:test';
 
 import type { Topo, TrailContext } from '@ontrails/core';
-import { validateEstablishedTopo, validateTopo } from '@ontrails/core';
+import { 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';
 import { testDetours } from './detours.js';
 import { testExamples } from './examples.js';
-import type { TestAllEstablishedOptions } from './types.js';
 
 /**
  * Run the full contract test suite for a Topo.
@@ -40,7 +36,7 @@ import type { TestAllEstablishedOptions } from './types.js';
  * testAll(graph);
  * ```
  */
-type TestAllInput =
+export type TestAllInput =
   | Partial<TrailContext>
   | TestExecutionOptions
   | (() => Partial<TrailContext> | TestExecutionOptions);
@@ -74,7 +70,7 @@ const assertValidTopo = (result: ReturnType<typeof validateTopo>): void => {
   }
 };
 
-const registerContractSuite = (
+export const registerContractSuite = (
   topo: Topo,
   ctxOrFactory: TestAllInput | undefined,
   validate: (topo: Topo) => ReturnType<typeof validateTopo>
@@ -96,126 +92,3 @@ const registerContractSuite = (
 export const testAll = (topo: Topo, ctxOrFactory?: TestAllInput): void => {
   registerContractSuite(topo, ctxOrFactory, validateTopo);
 };
-
-type EstablishedInput =
-  | Partial<TrailContext>
-  | TestAllEstablishedOptions
-  | (() => Partial<TrailContext> | TestAllEstablishedOptions);
-
-const isEstablishedOptions = (
-  input: Partial<TrailContext> | TestAllEstablishedOptions | undefined
-): input is TestAllEstablishedOptions =>
-  input !== undefined &&
-  (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'));
-
-const normalizeEstablishedOptions = (
-  input?: Partial<TrailContext> | TestAllEstablishedOptions
-): TestAllEstablishedOptions =>
-  isEstablishedOptions(input) ? input : { ctx: input };
-
-const toExecutionOptions = (
-  options: TestAllEstablishedOptions
-): TestExecutionOptions => ({
-  ...(options.createPermit === undefined
-    ? {}
-    : { createPermit: options.createPermit }),
-  ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-  ...(options.resources === undefined ? {} : { resources: options.resources }),
-  ...(options.strictPermits === undefined
-    ? {}
-    : { strictPermits: options.strictPermits }),
-});
-
-const toCliHarnessOptions = (
-  topo: Topo,
-  options: TestAllEstablishedOptions
-) => {
-  const cliOptions = {
-    graph: topo,
-    ...options.cli,
-  };
-
-  if (options.ctx !== undefined) {
-    cliOptions.ctx = options.ctx;
-  }
-
-  return cliOptions;
-};
-
-const toMcpHarnessOptions = (
-  topo: Topo,
-  options: TestAllEstablishedOptions
-) => ({
-  graph: topo,
-  ...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: () =>
-    | Partial<TrailContext>
-    | TestAllEstablishedOptions
-    | undefined
-): void => {
-  describe('surfaces', () => {
-    test('CLI projection validates established topo', () => {
-      const options = normalizeEstablishedOptions(resolveInput());
-      expect(() =>
-        createCliHarness(toCliHarnessOptions(topo, options))
-      ).not.toThrow();
-    });
-
-    test('MCP projection validates established topo', () => {
-      const options = normalizeEstablishedOptions(resolveInput());
-      expect(() =>
-        createMcpHarness(toMcpHarnessOptions(topo, options))
-      ).not.toThrow();
-    });
-
-    test('HTTP projection validates established topo', () => {
-      const options = normalizeEstablishedOptions(resolveInput());
-      expect(() =>
-        createHttpHarness(toHttpHarnessOptions(topo, options))
-      ).not.toThrow();
-    });
-  });
-};
-
-export const testAllEstablished = (
-  topo: Topo,
-  optionsOrFactory?: EstablishedInput
-): void => {
-  const resolveInput =
-    typeof optionsOrFactory === 'function'
-      ? optionsOrFactory
-      : () => optionsOrFactory;
-
-  registerContractSuite(
-    topo,
-    () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
-    validateEstablishedTopo
-  );
-  registerEstablishedSurfaceSuite(topo, resolveInput);
-};

package/src/assertions.ts

@@ -67,7 +67,7 @@ type ResultMatchToken = OkResultMatch | ErrResultMatch;
 
 /**
  * Create a partial-match token for `Result.ok(...)` values nested inside
- * arrays or objects, such as the `Result[]` returned by batch `ctx.cross()`.
+ * arrays or objects, such as the `Result[]` returned by batch `ctx.compose()`.
  */
 export const okResultMatch = (value?: unknown): OkResultMatch => ({
   __resultMatch: 'ok',
@@ -76,7 +76,7 @@ export const okResultMatch = (value?: unknown): OkResultMatch => ({
 
 /**
  * Create a partial-match token for `Result.err(...)` values nested inside
- * arrays or objects, such as mixed-success batch `ctx.cross()`.
+ * arrays or objects, such as mixed-success batch `ctx.compose()`.
  */
 export const errResultMatch = (error?: unknown): ErrResultMatch => ({
   __resultMatch: 'err',

package/src/cli.ts

@@ -0,0 +1,6 @@
+export { createCliHarness } from './harness-cli.js';
+export type {
+  CliHarness,
+  CliHarnessOptions,
+  CliHarnessResult,
+} from './harness-cli.js';