@ontrails/testing 1.0.0-beta.7 → 1.0.0-beta.9

package/.turbo/turbo-lint.log

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

package/CHANGELOG.md

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

package/README.md

@@ -32,6 +32,7 @@ testDetours(app);    // Verify detour targets exist
 | `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 |
@@ -67,6 +68,24 @@ testTrail(onboardTrail, [
 ]);
 ```
 
+When you need to isolate a composite trail and stub out its dependencies, use `createFollowContext`:
+
+```typescript
+import { createFollowContext, createTestContext } from '@ontrails/testing';
+import { Result } from '@ontrails/core';
+
+const follow = createFollowContext({
+  responses: {
+    'entity.add': Result.ok({ id: '1', name: 'Delta', type: 'tool' }),
+    'search': Result.ok({ results: [] }),
+  },
+});
+const ctx = { ...createTestContext(), follow };
+const result = await onboardTrail.run({ name: 'Delta', type: 'tool' }, ctx);
+```
+
+Calls to unregistered trail IDs return `Result.err` with a descriptive message, so missing stubs fail loudly.
+
 ## Surface harnesses
 
 ```typescript

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/harness-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harness-mcp.d.ts","sourceRoot":"","sources":["../src/harness-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,iBAAiB,KAAG,UAgC7D,CAAC"}
+{"version":3,"file":"harness-mcp.d.ts","sourceRoot":"","sources":["../src/harness-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,iBAAiB,KAAG,UAmC7D,CAAC"}

package/dist/harness-mcp.js

@@ -21,9 +21,12 @@ import { buildMcpTools } from '@ontrails/mcp';
  * ```
  */
 export const createMcpHarness = (options) => {
-    const tools = buildMcpTools(options.app);
+    const toolsResult = buildMcpTools(options.app);
+    if (toolsResult.isErr()) {
+        throw toolsResult.error;
+    }
     const toolMap = new Map();
-    for (const tool of tools) {
+    for (const tool of toolsResult.value) {
         toolMap.set(tool.name, tool);
     }
     return {

package/dist/harness-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-mcp.js","sourceRoot":"","sources":["../src/harness-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAS9C,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAA0B,EAAc,EAAE;IACzE,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,IAA6B;YAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;oBAC1D,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBACtC,aAAa,EAAE,SAAS;gBACxB,YAAY,EAAE,SAAS;gBACvB,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;aACjC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"harness-mcp.js","sourceRoot":"","sources":["../src/harness-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAS9C,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAA0B,EAAc,EAAE;IACzE,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,WAAW,CAAC,KAAK,CAAC;IAC1B,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,IAA6B;YAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;oBAC1D,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBACtC,aAAa,EAAE,SAAS;gBACxB,YAAY,EAAE,SAAS;gBACvB,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;aACjC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -5,10 +5,11 @@ export { testTrail } from './trail.js';
 export { testContracts } from './contracts.js';
 export { testDetours } from './detours.js';
 export { assertErrorMatch, assertFullMatch, assertSchemaMatch, expectErr, expectOk, } from './assertions.js';
-export { createTestContext } from './context.js';
+export { createFollowContext, createTestContext } from './context.js';
 export { createTestLogger } from './logger.js';
 export { createCliHarness } from './harness-cli.js';
 export { createMcpHarness } from './harness-mcp.js';
+export type { CreateFollowContextOptions } from './context.js';
 export type { TestFollowOptions } from './follows.js';
 export type { FollowScenario, TestScenario, TestLogger, TestTrailContextOptions, CliHarness, CliHarnessOptions, CliHarnessResult, McpHarness, McpHarnessOptions, McpHarnessResult, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,YAAY,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -8,7 +8,7 @@ export { testDetours } from './detours.js';
 // Assertions
 export { assertErrorMatch, assertFullMatch, assertSchemaMatch, expectErr, expectOk, } from './assertions.js';
 // Mock factories
-export { createTestContext } from './context.js';
+export { createFollowContext, createTestContext } from './context.js';
 export { createTestLogger } from './logger.js';
 // Surface harnesses
 export { createCliHarness } from './harness-cli.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,iBAAiB;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAEzB,iBAAiB;AACjB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,10 +14,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.6",
-    "@ontrails/core": "^1.0.0-beta.6",
-    "@ontrails/logging": "^1.0.0-beta.6",
-    "@ontrails/mcp": "^1.0.0-beta.6",
+    "@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",
     "zod": "^4.3.5"
   }
 }

package/src/__tests__/context.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from 'bun:test';
 
-import { createTestContext } from '../context.js';
+import { Result } from '@ontrails/core';
+
+import { createFollowContext, createTestContext } from '../context.js';
 import type { TestLogger } from '../types.js';
 
 // ---------------------------------------------------------------------------
@@ -58,3 +60,36 @@ describe('createTestContext', () => {
     expect(env).toEqual({ CUSTOM: '1', NODE_ENV: 'test' });
   });
 });
+
+describe('createFollowContext', () => {
+  test('returns configured ok response for registered id', async () => {
+    const follow = createFollowContext({
+      responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
+    });
+    const result = await follow('entity.add', { name: 'Alpha' });
+    expect(result.unwrap()).toEqual({ id: '1', name: 'Alpha' });
+  });
+
+  test('returns configured err response for registered id', async () => {
+    const err = new Error('conflict');
+    const follow = createFollowContext({
+      responses: { 'entity.add': Result.err(err) },
+    });
+    const result = await follow('entity.add', {});
+    expect(result.isErr()).toBe(true);
+    expect(result.error?.message).toBe('conflict');
+  });
+
+  test('returns err with descriptive message for unregistered id', async () => {
+    const follow = createFollowContext();
+    const result = await follow('unknown.trail', {});
+    expect(result.isErr()).toBe(true);
+    expect(result.error?.message).toContain('unknown.trail');
+  });
+
+  test('no options defaults to empty responses', async () => {
+    const follow = createFollowContext();
+    const result = await follow('any.id', {});
+    expect(result.isErr()).toBe(true);
+  });
+});

package/src/context.ts

@@ -2,7 +2,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 { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
@@ -28,6 +29,46 @@ export const createTestContext = (
   workspaceRoot: overrides?.cwd ?? process.cwd(),
 });
 
+// ---------------------------------------------------------------------------
+// createFollowContext
+// ---------------------------------------------------------------------------
+
+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 const createFollowContext = (
+  options?: CreateFollowContextOptions
+): FollowFn => {
+  const responses = options?.responses ?? {};
+  return <O>(id: string, _input: unknown): Promise<Result<O, Error>> => {
+    const response = responses[id];
+    if (response === undefined) {
+      return Promise.resolve(
+        Result.err(new Error(`No mock response for follow("${id}")`)) as Result<
+          O,
+          Error
+        >
+      );
+    }
+    return Promise.resolve(response as Result<O, Error>);
+  };
+};
+
 /**
  * Merge a Partial<TrailContext> into a test context.
  * Used internally when the public API accepts Partial<TrailContext>.

package/src/harness-mcp.ts

@@ -31,9 +31,12 @@ import type {
  * ```
  */
 export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
-  const tools = buildMcpTools(options.app);
+  const toolsResult = buildMcpTools(options.app);
+  if (toolsResult.isErr()) {
+    throw toolsResult.error;
+  }
   const toolMap = new Map<string, McpToolDefinition>();
-  for (const tool of tools) {
+  for (const tool of toolsResult.value) {
     toolMap.set(tool.name, tool);
   }
 

package/src/index.ts

@@ -16,7 +16,7 @@ export {
 } from './assertions.js';
 
 // Mock factories
-export { createTestContext } from './context.js';
+export { createFollowContext, createTestContext } from './context.js';
 export { createTestLogger } from './logger.js';
 
 // Surface harnesses
@@ -24,6 +24,7 @@ export { createCliHarness } from './harness-cli.js';
 export { createMcpHarness } from './harness-mcp.js';
 
 // Types
+export type { CreateFollowContextOptions } from './context.js';
 export type { TestFollowOptions } from './follows.js';
 
 export type {