@ontrails/testing 1.0.0-beta.0 → 1.0.0-beta.10

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 109ms on 20 files with 93 rules using 24 threads.
+Finished in 75ms on 20 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # @ontrails/testing
 
+## 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 surface packages.
+
+  **core**: Add `TrailResult<T>` utility type, `topo.ids()` and `topo.count` accessors, `dispatch()` 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**: Follow 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 `follow: [...]` field
+  - `follows` renamed to `follow` (singular, matching `ctx.follow()`)
+  - `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 `testFollows`, `HikeScenario` to `FollowScenario`
+  - `blaze()` now returns the surface 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.
+
+  **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.
+
+  **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.
+
+  **warden**: Collect hike detour targets, validate detour refs in hike specs, and stop implementation-returns-result from walking into nested function bodies.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.3
+  - @ontrails/cli@1.0.0-beta.3
+  - @ontrails/mcp@1.0.0-beta.3
+  - @ontrails/logging@1.0.0-beta.3
+
+## 1.0.0-beta.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution in published packages. Now using bun publish
+  which correctly replaces workspace:^ with actual version numbers.
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.2
+  - @ontrails/cli@1.0.0-beta.2
+  - @ontrails/mcp@1.0.0-beta.2
+  - @ontrails/logging@1.0.0-beta.2
+
+## 1.0.0-beta.1
+
+### Patch Changes
+
+- Fix two blocking bugs from real-world migration:
+  - Published packages now resolve correctly (workspace:^ instead of workspace:\*)
+  - Error forwarding works across different success types (Err no longer carries phantom T)
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.1
+  - @ontrails/cli@1.0.0-beta.1
+  - @ontrails/mcp@1.0.0-beta.1
+  - @ontrails/logging@1.0.0-beta.1
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,40 +1,8 @@
 # @ontrails/testing
 
-Contract-driven testing utilities for Trails. Write examples for agent fluency -- get test cases for free.
+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.
 
-## Installation
-
-```bash
-bun add -d @ontrails/testing
-```
-
-Peer dependencies: `@ontrails/core`, `@ontrails/cli`, `@ontrails/mcp`, `@ontrails/logging`, `zod`.
-
-## Quick Start
-
-```typescript
-import { testExamples } from '@ontrails/testing';
-import { app } from '../app';
-
-testExamples(app);
-```
-
-One line. The entire topo is tested. Every trail, every example: input validation, implementation execution, output verification.
-
-```text
- PASS  src/__tests__/app.test.ts
-  greet
-    example: Basic greeting
-    example: Loud greeting
-  entity.show
-    example: Show entity by name
-```
-
-## API Overview
-
-### `testAll(topo, ctx?)`
-
-Single-line governance suite. Wraps topo validation, example execution, contract checks, and detour verification into one `governance` describe block:
+## Usage
 
 ```typescript
 import { testAll } from '@ontrails/testing';
@@ -43,26 +11,38 @@ import { app } from '../app';
 testAll(app);
 ```
 
-For most apps, `testAll` is the only test call you need.
+That single call covers example execution, contract validation, detour checks, and topo validation. For most apps, this is all you need.
 
-### `testExamples(app, ctx?)`
+If you want finer control:
 
-For each trail with `examples`, generates `describe`/`test` blocks using the Bun test runner.
+```typescript
+import { testExamples, testContracts, testDetours } from '@ontrails/testing';
 
-Per example:
+testExamples(app);   // Run every trail's examples as tests
+testContracts(app);  // Validate outputs against declared schemas
+testDetours(app);    // Verify detour targets exist
+```
 
-1. Validates `example.input` against the trail's Zod schema
-2. Calls the implementation with validated input
-3. Applies progressive assertion (see below)
-4. Validates output against the trail's output schema (if present)
+## API
 
-Trails with no examples produce no tests.
+| Export | What it does |
+| --- | --- |
+| `testAll(topo, ctx?)` | Single-line governance 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 follow chains |
+| `testContracts(topo, ctx?)` | Validate output against declared schemas |
+| `testDetours(topo)` | Verify every detour target exists in the topo |
+| `createFollowContext(options?)` | Mock `FollowFn` 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 |
 
-The runtime implementation is always awaited, so `testExamples()` behaves the same for sync-authored and async-authored trails.
+See the [API Reference](../../docs/api-reference.md) for the full list.
 
-### `testTrail(trail, scenarios, ctx?)`
+## testTrail
 
-Custom scenarios for edge cases, boundary values, and regressions that do not belong in agent-facing examples:
+For edge cases that do not belong in agent-facing examples:
 
 ```typescript
 import { testTrail } from '@ontrails/testing';
@@ -71,151 +51,59 @@ import { ValidationError, NotFoundError } from '@ontrails/core';
 testTrail(showTrail, [
   { description: 'empty name', input: { name: '' }, expectOk: true },
   { description: 'missing name', input: {}, expectErr: ValidationError },
-  {
-    description: 'exact match',
-    input: { name: 'Alpha' },
-    expectValue: { name: 'Alpha', type: 'concept' },
-  },
-  {
-    description: 'not found',
-    input: { name: 'missing' },
-    expectErr: NotFoundError,
-    expectErrMessage: 'not found',
-  },
+  { description: 'not found', input: { name: 'missing' }, expectErr: NotFoundError },
 ]);
 ```
 
-### `testHike(hike, scenarios, ctx?)`
+## Testing composition (trails with follow)
 
-Tests a hike's composition graph -- follow chains, failure injection, and multi-trail interactions:
+`testTrail` works the same for trails with `follow` -- it exercises the follow graph:
 
 ```typescript
-import { testHike } from '@ontrails/testing';
+import { testTrail } from '@ontrails/testing';
 
-testHike(onboardHike, [
-  { description: 'successful onboard', input: { name: 'Delta', type: 'tool' }, expectOk: true },
-  { description: 'fails when add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
+testTrail(onboardTrail, [
+  { description: 'happy path', input: { name: 'Delta', type: 'tool' }, expectOk: true },
+  { description: 'add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
 ]);
 ```
 
-Where `testTrail` exercises a single trail in isolation, `testHike` exercises the follow graph and verifies that upstream failures propagate correctly.
-
-### `testContracts(app, ctx?)`
-
-Catches implementation-schema drift. Runs every example through the implementation, then validates the result against the trail's `output` schema. Reports detailed Zod errors on mismatch.
+When you need to isolate a composite trail and stub out its dependencies, use `createFollowContext`:
 
 ```typescript
-import { testContracts } from '@ontrails/testing';
-
-testContracts(app);
-// Fails if any implementation returns data that doesn't match its declared output schema
-```
-
-### `testDetours(app)`
-
-Structural validation of detour declarations. Verifies every detour target trail exists in the topo. No implementation execution needed.
-
-```typescript
-import { testDetours } from '@ontrails/testing';
-
-testDetours(app);
-// Fails: Trail "entity.show" has detour target "entity.search" which does not exist in the topo
-```
-
-### Progressive Assertion
+import { createFollowContext, createTestContext } from '@ontrails/testing';
+import { Result } from '@ontrails/core';
 
-What `testExamples` checks depends on what the example declares:
-
-**Full match** -- example has `expected`:
-
-```typescript
-{
-  name: 'Found',
-  input: { name: 'Alpha' },
-  expected: { name: 'Alpha', type: 'concept' },
-}
-```
-
-Asserts `result.isOk()` and `result.value` deep-equals `expected`.
-
-**Schema-only match** -- example has no `expected` and no `error`:
-
-```typescript
-{ name: 'Returns something valid', input: { name: 'Alpha' } }
-```
-
-Asserts `result.isOk()` and validates against the trail's output schema.
-
-**Error match** -- example has `error`:
-
-```typescript
-{ name: 'Not found', input: { name: 'missing' }, error: 'NotFoundError' }
-```
-
-Asserts `result.isErr()` and `instanceof` check.
-
-### Test Context and Mocks
-
-```typescript
-import { createTestContext, createTestLogger } from '@ontrails/testing';
-
-// TrailContext with sensible test defaults
-const ctx = createTestContext({
-  requestId: 'test-001',
-  env: { TRAILS_ENV: 'test' },
+const follow = createFollowContext({
+  responses: {
+    'entity.add': Result.ok({ id: '1', name: 'Delta', type: 'tool' }),
+    'search': Result.ok({ results: [] }),
+  },
 });
-
-// Logger that captures entries in memory
-const logger = createTestLogger();
-logger.info('hello');
-logger.entries; // All captured records
-logger.assertLogged('info', 'hello'); // Passes if any entry matches
-logger.clear(); // Reset
+const ctx = { ...createTestContext(), follow };
+const result = await onboardTrail.run({ name: 'Delta', type: 'tool' }, ctx);
 ```
 
-### Surface Harnesses
+Calls to unregistered trail IDs return `Result.err` with a descriptive message, so missing stubs fail loudly.
 
-**CLI harness** -- execute commands in-process and capture stdout/stderr:
+## Surface harnesses
 
 ```typescript
-import { createCliHarness } from '@ontrails/testing';
-
-const harness = createCliHarness({ app });
-const result = await harness.run('entity show --name Alpha --output json');
+import { createCliHarness, createMcpHarness } from '@ontrails/testing';
 
+// CLI
+const cli = createCliHarness({ app });
+const result = await cli.run('entity show --name Alpha --output json');
 expect(result.exitCode).toBe(0);
-expect(result.json).toMatchObject({ name: 'Alpha' });
-```
-
-**MCP harness** -- invoke tools directly without transport:
-
-```typescript
-import { createMcpHarness } from '@ontrails/testing';
-
-const harness = createMcpHarness({ app });
-const result = await harness.callTool('myapp_entity_show', { name: 'Alpha' });
 
-expect(result.isError).toBe(false);
+// MCP
+const mcp = createMcpHarness({ app });
+const tool = await mcp.callTool('myapp_entity_show', { name: 'Alpha' });
+expect(tool.isError).toBe(false);
 ```
 
-## Exports
+## Installation
 
-```typescript
-import {
-  testAll,
-  testExamples,
-  testTrail,
-  testHike,
-  testContracts,
-  testDetours,
-  createTestContext,
-  createTestLogger,
-  createCliHarness,
-  createMcpHarness,
-} from '@ontrails/testing';
+```bash
+bun add -d @ontrails/testing
 ```
-
-## Further Reading
-
-- [Testing Guide](../../docs/testing.md)
-- [Getting Started](../../docs/getting-started.md)

package/dist/context.d.ts

@@ -1,7 +1,8 @@
 /**
  * Test context factory for creating TrailContext instances suitable for testing.
  */
-import type { TrailContext } from '@ontrails/core';
+import type { FollowFn, TrailContext } from '@ontrails/core';
+import { Result } from '@ontrails/core';
 import type { TestTrailContextOptions } from './types.js';
 /**
  * Create a TrailContext with deterministic, test-friendly defaults.
@@ -11,6 +12,24 @@ import type { TestTrailContextOptions } from './types.js';
  * - `signal`: a non-aborted AbortController signal
  */
 export declare const createTestContext: (overrides?: TestTrailContextOptions) => TrailContext;
+export interface CreateFollowContextOptions {
+    readonly responses?: Record<string, Result<unknown, Error>> | undefined;
+}
+/**
+ * Create a mock `FollowFn` for testing composite trails.
+ *
+ * Returns preconfigured `Result` values keyed by trail ID. Calls to
+ * unregistered IDs return `Result.err` with a descriptive message.
+ *
+ * @example
+ * ```ts
+ * const follow = createFollowContext({
+ *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
+ * });
+ * const ctx = { ...createTestContext(), follow };
+ * ```
+ */
+export declare const createFollowContext: (options?: CreateFollowContextOptions) => FollowFn;
 /**
  * Merge a Partial<TrailContext> into a test context.
  * Used internally when the public API accepts Partial<TrailContext>.

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAM1D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,uBAAuB,KAClC,YAMD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,OAAO,CAAC,YAAY,CAAC,KAAG,YAO9D,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAM1D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,uBAAuB,KAClC,YAMD,CAAC;AAMH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC;CACzE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,0BAA0B,KACnC,QAcF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,OAAO,CAAC,YAAY,CAAC,KAAG,YAO9D,CAAC"}

package/dist/context.js

@@ -1,6 +1,7 @@
 /**
  * Test context factory for creating TrailContext instances suitable for testing.
  */
+import { Result } from '@ontrails/core';
 import { createTestLogger } from './logger.js';
 // ---------------------------------------------------------------------------
 // createTestContext
@@ -19,6 +20,30 @@ export const createTestContext = (overrides) => ({
     signal: overrides?.signal ?? new AbortController().signal,
     workspaceRoot: overrides?.cwd ?? process.cwd(),
 });
+/**
+ * Create a mock `FollowFn` for testing composite trails.
+ *
+ * Returns preconfigured `Result` values keyed by trail ID. Calls to
+ * unregistered IDs return `Result.err` with a descriptive message.
+ *
+ * @example
+ * ```ts
+ * const follow = createFollowContext({
+ *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
+ * });
+ * const ctx = { ...createTestContext(), follow };
+ * ```
+ */
+export const createFollowContext = (options) => {
+    const responses = options?.responses ?? {};
+    return (id, _input) => {
+        const response = responses[id];
+        if (response === undefined) {
+            return Promise.resolve(Result.err(new Error(`No mock response for follow("${id}")`)));
+        }
+        return Promise.resolve(response);
+    };
+};
 /**
  * Merge a Partial<TrailContext> into a test context.
  * Used internally when the public API accepts Partial<TrailContext>.

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAmC,EACrB,EAAE,CAAC,CAAC;IAClB,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE;IAC7C,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,gBAAgB,EAAE;IAC/C,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,kBAAkB;IACrD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM;IACzD,aAAa,EAAE,SAAS,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;CAC/C,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAA2B,EAAgB,EAAE;IAC5E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,iBAAiB,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;AAC7B,CAAC,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAmC,EACrB,EAAE,CAAC,CAAC;IAClB,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE;IAC7C,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,gBAAgB,EAAE;IAC/C,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,kBAAkB;IACrD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM;IACzD,aAAa,EAAE,SAAS,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;CAC/C,CAAC,CAAC;AAUH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,OAAoC,EAC1B,EAAE;IACZ,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAC3C,OAAO,CAAI,EAAU,EAAE,MAAe,EAA6B,EAAE;QACnE,MAAM,QAAQ,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,OAAO,CACpB,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,gCAAgC,EAAE,IAAI,CAAC,CAG3D,CACF,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,QAA4B,CAAC,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAA2B,EAAgB,EAAE;IAC5E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,iBAAiB,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;AAC7B,CAAC,CAAC"}

package/dist/contracts.d.ts

@@ -7,7 +7,7 @@
  */
 import type { Topo, TrailContext } from '@ontrails/core';
 /**
- * Verify that every trail's implementation output matches its declared
+ * Verify that every trail implementation output matches its declared
  * output schema. Catches implementation-schema drift.
  *
  * Trails without output schemas or examples are skipped.

package/dist/contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAuB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA8B9E;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,IAAI,EACT,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAmCF,CAAC"}
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAuB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA0C9E;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,IAAI,EACT,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAoCF,CAAC"}

package/dist/contracts.js

@@ -12,6 +12,14 @@ import { mergeTestContext } from './context.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+/** Check if a trail requires follow() but the context doesn't provide it. */
+const needsFollowContext = (t, resolveCtx) => {
+    const spec = t;
+    if (!spec.follow || spec.follow.length === 0) {
+        return false;
+    }
+    return !resolveCtx()?.follow;
+};
 const validateOutputSchema = (outputSchema, value, trailId, exampleName) => {
     const parsed = outputSchema.safeParse(value);
     if (!parsed.success) {
@@ -23,30 +31,32 @@ const validateOutputSchema = (outputSchema, value, trailId, exampleName) => {
 // testContracts
 // ---------------------------------------------------------------------------
 /**
- * Verify that every trail's implementation output matches its declared
+ * Verify that every trail implementation output matches its declared
  * output schema. Catches implementation-schema drift.
  *
  * Trails without output schemas or examples are skipped.
  */
 export const testContracts = (app, ctxOrFactory) => {
     const resolveCtx = typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-    const trailEntries = [...app.trails];
+    const allEntries = app.list();
     describe('contracts', () => {
-        describe.each(trailEntries)('%s', (_id, trailDef) => {
-            const t = trailDef;
+        describe.each(allEntries)('$id', (t) => {
             if (t.output === undefined) {
                 return;
             }
             if (t.examples === undefined || t.examples.length === 0) {
                 return;
             }
+            if (needsFollowContext(t, resolveCtx)) {
+                return;
+            }
             const { examples, output: outputSchema } = t;
             const successExamples = examples.filter((e) => e.error === undefined);
             test.each(successExamples)('contract: $name', async (example) => {
                 const testCtx = mergeTestContext(resolveCtx());
                 const validated = validateInput(t.input, example.input);
                 const validatedInput = expectOk(validated);
-                const result = await t.implementation(validatedInput, testCtx);
+                const result = await t.run(validatedInput, testCtx);
                 const resultValue = expectOk(result);
                 validateOutputSchema(outputSchema, resultValue, t.id, example.name);
             });

package/dist/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}

package/dist/examples.d.ts

@@ -3,14 +3,14 @@
  *
  * Iterates every trail in the app's topo. For each trail with examples,
  * generates describe/test blocks using bun:test. Progressive assertion
- * determines which check to run per example. For hikes with `follows`
+ * determines which check to run per example. For trails with `follow`
  * declarations, checks that every declared follow was called at least once.
  */
 import type { Topo, TrailContext } from '@ontrails/core';
 /**
  * Generate describe/test blocks for every trail example in the app.
  *
- * For hikes with `follows` declarations and examples, also verifies that
+ * For trails with `follow` declarations and examples, also verifies that
  * every declared follow ID was called at least once across all examples.
  *
  * One line in your test file:

package/dist/examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAGV,IAAI,EAGJ,YAAY,EACb,MAAM,gBAAgB,CAAC;AAkQxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,IAAI,EACT,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAuBF,CAAC"}
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAEV,IAAI,EAGJ,YAAY,EACb,MAAM,gBAAgB,CAAC;AAiMxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,IAAI,EACT,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAqDF,CAAC"}