@ontrails/core 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 23ms on 60 files with 93 rules using 24 threads.
+Finished in 14ms on 64 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @ontrails/core
 
+## 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.
+
+## 1.0.0-beta.8
+
 ## 1.0.0-beta.7
 
 ## 1.0.0-beta.6

package/README.md

@@ -46,15 +46,51 @@ const onboard = trail('entity.onboard', {
 | `topo(name, ...modules)` | Collect trail modules into a queryable topology |
 | `validateTopo(topo)` | Structural validation: follow targets exist, no cycles, examples parse, output schemas present |
 
+### Execution
+
+| Export | What it does |
+| --- | --- |
+| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the implementation. Never throws -- exceptions become `Result.err(InternalError)`. |
+| `dispatch(topo, id, input, options?)` | Headless trail execution by ID. Looks up the trail in the topo, then delegates to `executeTrail`. Returns `Result.err(NotFoundError)` if the ID is not registered. |
+
+```typescript
+// executeTrail — surface adapters use this directly
+const result = await executeTrail(greet, { name: 'Alice' });
+
+// dispatch — no-surface execution by trail ID
+const result = await dispatch(app, 'greet', { name: 'Alice' });
+if (result.isOk()) console.log(result.value);
+```
+
+### Topo accessors
+
+Beyond the `trail(id, spec)` builder, `Topo` exposes these accessors:
+
+| Accessor | What it returns |
+| --- | --- |
+| `topo.ids()` | `string[]` of all registered trail IDs |
+| `topo.count` | Number of registered trails |
+| `topo.get(id)` | The `Trail` with that ID, or `undefined` |
+| `topo.has(id)` | Whether a trail ID is registered |
+| `topo.list()` | All registered trails as an array |
+
 ### Type utilities
 
 | Export | What it does |
 | --- | --- |
 | `TrailInput<T>` | Extract the input type from a `Trail` |
 | `TrailOutput<T>` | Extract the output type from a `Trail` |
+| `TrailResult<T>` | `Result<TrailOutput<T>, Error>` -- the Result type for a trail's output |
 | `inputOf(trail)` | Get the input Zod schema from a trail instance |
 | `outputOf(trail)` | Get the output Zod schema (or `undefined`) from a trail instance |
 
+### Execution option types
+
+| Type | What it describes |
+| --- | --- |
+| `ExecuteTrailOptions` | Options for `executeTrail`: `ctx`, `signal`, `layers`, `createContext` |
+| `DispatchOptions` | Same shape as `ExecuteTrailOptions`; forwarded by `dispatch` |
+
 ### Result
 
 ```typescript

package/dist/dispatch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Headless trail execution — the "no-surface" surface.
+ *
+ * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
+ * Returns a `Result` and never throws.
+ */
+import type { Topo } from './topo.js';
+import type { TrailContext } from './types.js';
+import type { Layer } from './layer.js';
+import { Result } from './result.js';
+/** Options forwarded to `executeTrail` from `dispatch`. */
+export interface DispatchOptions {
+    /** Partial context overrides merged on top of the base context. */
+    readonly ctx?: Partial<TrailContext> | undefined;
+    /** AbortSignal override (takes final precedence over ctx and factory). */
+    readonly signal?: AbortSignal | undefined;
+    /** Layers to compose around the implementation. */
+    readonly layers?: readonly Layer[] | undefined;
+    /** Factory that produces a base TrailContext (takes precedence over defaults). */
+    readonly createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+}
+/**
+ * Execute a trail by ID from a topo without mounting a surface.
+ *
+ * Resolves the trail from the topo, then runs it through the standard
+ * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
+ * trail ID is not registered. Never throws — unexpected exceptions are
+ * returned as `Result.err(InternalError)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export declare const dispatch: (topo: Topo, id: string, input: unknown, options?: DispatchOptions) => Promise<Result<unknown, Error>>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAMrC,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IACjD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAC5C,SAAS,CAAC;CACf;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GACnB,MAAM,IAAI,EACV,IAAI,MAAM,EACV,OAAO,OAAO,EACd,UAAU,eAAe,KACxB,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAUhC,CAAC"}

package/dist/dispatch.js

@@ -0,0 +1,34 @@
+/**
+ * Headless trail execution — the "no-surface" surface.
+ *
+ * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
+ * Returns a `Result` and never throws.
+ */
+import { executeTrail } from './execute.js';
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+// ---------------------------------------------------------------------------
+// dispatch()
+// ---------------------------------------------------------------------------
+/**
+ * Execute a trail by ID from a topo without mounting a surface.
+ *
+ * Resolves the trail from the topo, then runs it through the standard
+ * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
+ * trail ID is not registered. Never throws — unexpected exceptions are
+ * returned as `Result.err(InternalError)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export const dispatch = (topo, id, input, options) => {
+    const trail = topo.get(id);
+    if (trail === undefined) {
+        return Promise.resolve(Result.err(new NotFoundError(`Trail "${id}" not found in topo "${topo.name}"`)));
+    }
+    return executeTrail(trail, input, options);
+};
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAoBrC,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,IAAU,EACV,EAAU,EACV,KAAc,EACd,OAAyB,EACQ,EAAE;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,CACpB,MAAM,CAAC,GAAG,CACR,IAAI,aAAa,CAAC,UAAU,EAAE,wBAAwB,IAAI,CAAC,IAAI,GAAG,CAAC,CACpE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC,CAAC"}

package/dist/execute.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Centralized trail execution pipeline.
+ *
+ * Validates input, builds context, composes layers, and runs the
+ * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
+ * of reimplementing the pipeline.
+ */
+import type { AnyTrail } from './trail.js';
+import type { Layer } from './layer.js';
+import type { TrailContext } from './types.js';
+import { Result } from './result.js';
+/** Options for executeTrail. */
+export interface ExecuteTrailOptions {
+    /** Partial context overrides merged on top of the base context. */
+    readonly ctx?: Partial<TrailContext> | undefined;
+    /** AbortSignal override (takes final precedence over ctx and factory). */
+    readonly signal?: AbortSignal | undefined;
+    /** Layers to compose around the implementation. */
+    readonly layers?: readonly Layer[] | undefined;
+    /** Factory that produces a base TrailContext (takes precedence over defaults). */
+    readonly createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+}
+/**
+ * Execute a trail through the standard validate-context-layers-run pipeline.
+ *
+ * The function never throws -- unexpected exceptions are caught and
+ * returned as `Result.err(InternalError)`.
+ */
+export declare const executeTrail: (trail: AnyTrail, rawInput: unknown, options?: ExecuteTrailOptions) => Promise<Result<unknown, Error>>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IACjD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAC5C,SAAS,CAAC;CACf;AA8BD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,QAAQ,EACf,UAAU,OAAO,EACjB,UAAU,mBAAmB,KAC5B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAehC,CAAC"}

package/dist/execute.js

@@ -0,0 +1,58 @@
+/**
+ * Centralized trail execution pipeline.
+ *
+ * Validates input, builds context, composes layers, and runs the
+ * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
+ * of reimplementing the pipeline.
+ */
+import { composeLayers } from './layer.js';
+import { createTrailContext } from './context.js';
+import { InternalError } from './errors.js';
+import { Result } from './result.js';
+import { validateInput } from './validation.js';
+// ---------------------------------------------------------------------------
+// Context resolution
+// ---------------------------------------------------------------------------
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `signal` override takes final precedence.
+ */
+const resolveContext = async (options) => {
+    const base = options?.createContext
+        ? await options.createContext()
+        : createTrailContext();
+    const withOverrides = options?.ctx ? { ...base, ...options.ctx } : base;
+    return options?.signal
+        ? { ...withOverrides, signal: options.signal }
+        : withOverrides;
+};
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Execute a trail through the standard validate-context-layers-run pipeline.
+ *
+ * The function never throws -- unexpected exceptions are caught and
+ * returned as `Result.err(InternalError)`.
+ */
+export const executeTrail = async (trail, rawInput, options) => {
+    try {
+        const validated = validateInput(trail.input, rawInput);
+        if (validated.isErr()) {
+            return validated;
+        }
+        const ctx = await resolveContext(options);
+        const layers = options?.layers ?? [];
+        const impl = composeLayers([...layers], trail, trail.run);
+        return await impl(validated.value, ctx);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return Result.err(new InternalError(message));
+    }
+};
+//# sourceMappingURL=execute.js.map

package/dist/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAoBhD,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,KAAK,EAC1B,OAA6B,EACN,EAAE;IACzB,MAAM,IAAI,GAAG,OAAO,EAAE,aAAa;QACjC,CAAC,CAAC,MAAM,OAAO,CAAC,aAAa,EAAE;QAC/B,CAAC,CAAC,kBAAkB,EAAE,CAAC;IACzB,MAAM,aAAa,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,OAAO,OAAO,EAAE,MAAM;QACpB,CAAC,CAAC,EAAE,GAAG,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;QAC9C,CAAC,CAAC,aAAa,CAAC;AACpB,CAAC,CAAC;AAEF,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,KAAe,EACf,QAAiB,EACjB,OAA6B,EACI,EAAE;IACnC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvD,IAAI,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1D,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,CAAC;AACH,CAAC,CAAC"}

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { Implementation, TrailContext, FollowFn, ProgressCallback, Progress
 export { createTrailContext } from './context.js';
 export { trail } from './trail.js';
 export type { AnyTrail, Intent, Trail, TrailSpec, TrailExample, } from './trail.js';
-export type { TrailInput, TrailOutput } from './type-utils.js';
+export type { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
 export { inputOf, outputOf } from './type-utils.js';
 export { event } from './event.js';
 export type { AnyEvent, Event, EventSpec } from './event.js';
@@ -19,6 +19,10 @@ export type { HealthStatus, HealthResult } from './health.js';
 export type { IndexAdapter, StorageAdapter, CacheAdapter, SearchOptions, SearchResult, StorageOptions, } from './adapters.js';
 export { deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
+export { executeTrail } from './execute.js';
+export type { ExecuteTrailOptions } from './execute.js';
+export { dispatch } from './dispatch.js';
+export type { DispatchOptions } from './dispatch.js';
 export { validateInput, validateOutput, formatZodIssues, zodToJsonSchema, } from './validation.js';
 export { serializeError, deserializeError } from './serialization.js';
 export type { SerializedError } from './serialization.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -17,6 +17,10 @@ export { validateTopo } from './validate-topo.js';
 export { composeLayers } from './layer.js';
 // Derive
 export { deriveFields } from './derive.js';
+// Execute
+export { executeTrail } from './execute.js';
+// Dispatch
+export { dispatch } from './dispatch.js';
 // Validation
 export { validateInput, validateOutput, formatZodIssues, zodToJsonSchema, } from './validation.js';
 // Serialization

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,SAAS;AACT,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AAcrB,kBAAkB;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWnC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,kBAAkB;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3C,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,aAAa;AACb,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtE,aAAa;AACb,OAAO,EACL,KAAK,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,uDAAuD;AAEvD,gBAAgB;AAChB,OAAO,EACL,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,GACP,MAAM,cAAc,CAAC;AAStB,gBAAgB;AAChB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,YAAY;AACZ,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO;AACP,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGzD,SAAS;AACT,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,cAAc;AACd,OAAO,EACL,KAAK,EACL,MAAM,EACN,OAAO,EACP,MAAM,EACN,eAAe,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,SAAS;AACT,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AAcrB,kBAAkB;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWnC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,kBAAkB;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3C,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,WAAW;AACX,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,aAAa;AACb,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtE,aAAa;AACb,OAAO,EACL,KAAK,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,uDAAuD;AAEvD,gBAAgB;AAChB,OAAO,EACL,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,GACP,MAAM,cAAc,CAAC;AAStB,gBAAgB;AAChB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,YAAY;AACZ,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO;AACP,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGzD,SAAS;AACT,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,cAAc;AACd,OAAO,EACL,KAAK,EACL,MAAM,EACN,OAAO,EACP,MAAM,EACN,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/topo.d.ts

@@ -7,8 +7,10 @@ export interface Topo {
     readonly name: string;
     readonly trails: ReadonlyMap<string, AnyTrail>;
     readonly events: ReadonlyMap<string, AnyEvent>;
+    readonly count: number;
     get(id: string): AnyTrail | undefined;
     has(id: string): boolean;
+    ids(): string[];
     list(): AnyTrail[];
     listEvents(): AnyEvent[];
 }

package/dist/topo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,IAAI,IAAI,QAAQ,EAAE,CAAC;IACnB,UAAU,IAAI,QAAQ,EAAE,CAAC;CAC1B;AA0ED,eAAO,MAAM,IAAI,GACf,MAAM,MAAM,EACZ,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KACpC,IAaF,CAAC"}
+{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,GAAG,IAAI,MAAM,EAAE,CAAC;IAChB,IAAI,IAAI,QAAQ,EAAE,CAAC;IACnB,UAAU,IAAI,QAAQ,EAAE,CAAC;CAC1B;AA+ED,eAAO,MAAM,IAAI,GACf,MAAM,MAAM,EACZ,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KACpC,IAaF,CAAC"}

package/dist/topo.js

@@ -13,6 +13,7 @@ const isRegistrable = (value) => {
 // Topo implementation
 // ---------------------------------------------------------------------------
 const createTopo = (name, trails, events) => ({
+    count: trails.size,
     events,
     get(id) {
         return trails.get(id);
@@ -20,6 +21,9 @@ const createTopo = (name, trails, events) => ({
     has(id) {
         return trails.has(id);
     },
+    ids() {
+        return [...trails.keys()];
+    },
     list() {
         return [...trails.values()];
     },

package/dist/topo.js.map

@@ -1 +1 @@
-{"version":3,"file":"topo.js","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAwB9C,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,KAAgC,CAAC;IAClD,OAAO,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEF,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,UAAU,GAAG,CACjB,IAAY,EACZ,MAAqC,EACrC,MAAqC,EAC/B,EAAE,CAAC,CAAC;IACV,MAAM;IACN,GAAG,CAAC,EAAU;QACZ,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,GAAG,CAAC,EAAU;QACZ,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;IAEJ,MAAM;CACP,CAAC,CAAC;AAEH,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,QAAQ,GAAG,CACf,KAAkB,EAClB,MAA6B,EAC7B,MAA6B,EACvB,EAAE;IACR,MAAM,EAAE,EAAE,EAAE,GAAG,KAAuB,CAAC;IACvC,MAAM,UAAU,GAA+B;QAC7C,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAiB,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAiB,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;IACF,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,IAAY,EACZ,GAAG,OAAkC,EAC/B,EAAE;IACR,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC,CAAC"}
+{"version":3,"file":"topo.js","sourceRoot":"","sources":["../src/topo.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0B9C,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,KAAgC,CAAC;IAClD,OAAO,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEF,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,UAAU,GAAG,CACjB,IAAY,EACZ,MAAqC,EACrC,MAAqC,EAC/B,EAAE,CAAC,CAAC;IACV,KAAK,EAAE,MAAM,CAAC,IAAI;IAClB,MAAM;IACN,GAAG,CAAC,EAAU;QACZ,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,GAAG,CAAC,EAAU;QACZ,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;IAEJ,MAAM;CACP,CAAC,CAAC;AAEH,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,QAAQ,GAAG,CACf,KAAkB,EAClB,MAA6B,EAC7B,MAA6B,EACvB,EAAE;IACR,MAAM,EAAE,EAAE,EAAE,GAAG,KAAuB,CAAC;IACvC,MAAM,UAAU,GAA+B;QAC7C,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAiB,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAiB,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;IACF,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,IAAY,EACZ,GAAG,OAAkC,EAC/B,EAAE;IACR,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC,CAAC"}

package/dist/type-utils.d.ts

@@ -1,11 +1,22 @@
 /**
  * Type utilities for extracting input/output types from trails.
  */
+import type { Result } from './result.js';
 import type { AnyTrail, Trail } from './trail.js';
 /** Extract the input type from a Trail. */
 export type TrailInput<T extends AnyTrail> = T extends Trail<infer I, any> ? I : never;
 /** Extract the output type from a Trail. */
 export type TrailOutput<T extends AnyTrail> = T extends Trail<any, infer O> ? O : never;
+/**
+ * Extracts the full `Result<Output, Error>` type from a trail definition.
+ *
+ * @example
+ * ```typescript
+ * type SearchResult = TrailResult<typeof searchTrail>;
+ * // Result<{ results: Item[]; count: number }, Error>
+ * ```
+ */
+export type TrailResult<T extends AnyTrail> = Result<TrailOutput<T>, Error>;
 /** Get the input Zod schema from a trail, preserving the specific schema type. */
 export declare const inputOf: <T extends AnyTrail>(trail: T) => T["input"];
 /** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */

package/dist/type-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAQ5C,kFAAkF;AAClF,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,OAAO,CACnD,CAAC;AAEd,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,QAAQ,CACpD,CAAC"}
+{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAQ5E,kFAAkF;AAClF,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,OAAO,CACnD,CAAC;AAEd,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,KAAG,CAAC,CAAC,QAAQ,CACpD,CAAC"}

package/dist/type-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAqB,KAAQ,EAAc,EAAE,CAClE,KAAK,CAAC,KAAK,CAAC;AAEd,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAqB,KAAQ,EAAe,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC"}
+{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8BH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAqB,KAAQ,EAAc,EAAE,CAClE,KAAK,CAAC,KAAK,CAAC;AAEd,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAqB,KAAQ,EAAe,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/__tests__/dispatch.test.ts

@@ -0,0 +1,154 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { dispatch } from '../dispatch';
+import { InternalError, NotFoundError, ValidationError } from '../errors';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { topo } from '../topo';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  input: z.object({ value: z.string() }),
+  output: z.object({ value: z.string() }),
+  run: (input) => Result.ok({ value: input.value }),
+});
+
+const throwingTrail = trail('throws', {
+  input: z.object({}),
+  run: () => {
+    throw new Error('kaboom');
+  },
+});
+
+const testTopo = topo('test', { echoTrail, throwingTrail });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('dispatch', () => {
+  describe('happy path', () => {
+    test('dispatches by ID and returns Result.ok with expected value', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 'hello' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ value: 'hello' });
+    });
+  });
+
+  describe('not found', () => {
+    test('returns NotFoundError for unknown trail ID', async () => {
+      const result = await dispatch(testTopo, 'nonexistent', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(NotFoundError);
+      expect(result.error.message).toContain('nonexistent');
+      expect(result.error.message).toContain('test');
+    });
+  });
+
+  describe('validation', () => {
+    test('returns ValidationError for invalid input', async () => {
+      const result = await dispatch(testTopo, 'echo', { value: 42 });
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+
+  describe('layers', () => {
+    test('layer composition works through dispatch', async () => {
+      const log: string[] = [];
+      const layer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            log.push('before');
+            const r = await impl(input, ctx);
+            log.push('after');
+            return r;
+          };
+        },
+      };
+
+      const result = await dispatch(
+        testTopo,
+        'echo',
+        { value: 'x' },
+        { layers: [layer] }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(log).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('context', () => {
+    test('context overrides work through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('ctx-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('ctx-test', { ctxTrail });
+      await dispatch(
+        ctxTopo,
+        'ctx-dispatch-test',
+        {},
+        { ctx: { requestId: 'override-id' } }
+      );
+
+      expect(capturedCtx?.requestId).toBe('override-id');
+    });
+
+    test('createContext factory works through dispatch', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('factory-dispatch-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const ctxTopo = topo('factory-test', { ctxTrail });
+      const customCtx: TrailContext = {
+        cwd: '/custom',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await dispatch(
+        ctxTopo,
+        'factory-dispatch-test',
+        {},
+        { createContext: () => customCtx }
+      );
+
+      expect(capturedCtx?.requestId).toBe('factory-id');
+      expect(capturedCtx?.cwd).toBe('/custom');
+    });
+  });
+
+  describe('error handling', () => {
+    test('never throws — exceptions become InternalError', async () => {
+      const result = await dispatch(testTopo, 'throws', {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toBe('kaboom');
+    });
+  });
+});

package/src/__tests__/execute.test.ts

@@ -0,0 +1,185 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { InternalError, ValidationError } from '../errors';
+import { executeTrail } from '../execute';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  input: z.object({ value: z.string() }),
+  output: z.object({ value: z.string() }),
+  run: (input) => Result.ok({ value: input.value }),
+});
+
+const failingTrail = trail('fails', {
+  input: z.object({}),
+  run: () => Result.err(new ValidationError('bad input')),
+});
+
+const throwingTrail = trail('throws', {
+  input: z.object({}),
+  run: () => {
+    throw new Error('kaboom');
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('executeTrail', () => {
+  describe('happy path', () => {
+    test('validates input and executes trail', async () => {
+      const result = await executeTrail(echoTrail, { value: 'hello' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ value: 'hello' });
+    });
+  });
+
+  describe('validation', () => {
+    test('returns validation error for invalid input', async () => {
+      const result = await executeTrail(echoTrail, { value: 42 });
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+    });
+  });
+
+  describe('layers', () => {
+    test('composes layers around execution', async () => {
+      const log: string[] = [];
+      const layer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            log.push('before');
+            const r = await impl(input, ctx);
+            log.push('after');
+            return r;
+          };
+        },
+      };
+
+      const result = await executeTrail(
+        echoTrail,
+        { value: 'x' },
+        { layers: [layer] }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(log).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('context', () => {
+    test('accepts context overrides', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('ctx-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      await executeTrail(ctxTrail, {}, { ctx: { requestId: 'override-id' } });
+
+      expect(capturedCtx?.requestId).toBe('override-id');
+    });
+
+    test('accepts signal override', async () => {
+      let capturedSignal: AbortSignal | undefined;
+      const sigTrail = trail('sig-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedSignal = ctx.signal;
+          return Result.ok(null);
+        },
+      });
+
+      const signal = AbortSignal.timeout(9999);
+      await executeTrail(sigTrail, {}, { signal });
+
+      expect(capturedSignal).toBe(signal);
+    });
+
+    test('accepts context factory', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('factory-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const customCtx: TrailContext = {
+        cwd: '/custom',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await executeTrail(ctxTrail, {}, { createContext: () => customCtx });
+
+      expect(capturedCtx?.requestId).toBe('factory-id');
+      expect(capturedCtx?.cwd).toBe('/custom');
+    });
+
+    test('context factory + ctx overrides merge correctly', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const ctxTrail = trail('merge-test', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+      });
+
+      const baseCtx: TrailContext = {
+        cwd: '/factory',
+        requestId: 'factory-id',
+        signal: new AbortController().signal,
+      };
+
+      await executeTrail(
+        ctxTrail,
+        {},
+        {
+          createContext: () => baseCtx,
+          ctx: { requestId: 'overridden-id' },
+        }
+      );
+
+      expect(capturedCtx?.requestId).toBe('overridden-id');
+      expect(capturedCtx?.cwd).toBe('/factory');
+    });
+  });
+
+  describe('error handling', () => {
+    test('propagates Result.err from run function', async () => {
+      const result = await executeTrail(failingTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+      expect(result.error.message).toBe('bad input');
+    });
+
+    test('catches thrown exceptions and returns InternalError', async () => {
+      const result = await executeTrail(throwingTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toBe('kaboom');
+    });
+  });
+});

package/src/__tests__/topo.test.ts

@@ -116,6 +116,31 @@ describe('topo', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// topo accessors
+// ---------------------------------------------------------------------------
+
+describe('topo accessors', () => {
+  test('ids() returns all trail IDs', () => {
+    const a = mockTrail('alpha');
+    const b = mockTrail('beta');
+    const app = topo('test', { a, b });
+    expect(app.ids().toSorted()).toEqual(['alpha', 'beta']);
+  });
+
+  test('count returns number of trails', () => {
+    const a = mockTrail('alpha');
+    const app = topo('test', { a });
+    expect(app.count).toBe(1);
+  });
+
+  test('empty topo has zero count and empty ids', () => {
+    const app = topo('empty');
+    expect(app.count).toBe(0);
+    expect(app.ids()).toEqual([]);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Topo
 // ---------------------------------------------------------------------------

package/src/__tests__/type-utils.test.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 import { Result } from '../result';
 import { trail } from '../trail';
-import type { TrailInput, TrailOutput } from '../type-utils';
+import type { TrailInput, TrailOutput, TrailResult } from '../type-utils';
 import { inputOf, outputOf } from '../type-utils';
 
 const greetTrail = trail('greet', {
@@ -67,4 +67,24 @@ describe('type-utils', () => {
       expect(_output.message).toBe('hello');
     });
   });
+
+  describe('TrailResult', () => {
+    test('extracts Result<Output, Error> from a trail', () => {
+      const t = trail('test.result', {
+        input: z.object({ q: z.string() }),
+        output: z.object({ answer: z.string() }),
+        run: (input) => Result.ok({ answer: input.q }),
+      });
+
+      type Expected = Result<{ answer: string }, Error>;
+      type Actual = TrailResult<typeof t>;
+
+      // Compile-time check: assignment works in both directions
+      const _check1: Expected = {} as Actual;
+      const _check2: Actual = {} as Expected;
+
+      // Runtime: type exists and is usable
+      expect(true).toBe(true);
+    });
+  });
 });

package/src/dispatch.ts

@@ -0,0 +1,66 @@
+/**
+ * Headless trail execution — the "no-surface" surface.
+ *
+ * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
+ * Returns a `Result` and never throws.
+ */
+
+import type { Topo } from './topo.js';
+import type { TrailContext } from './types.js';
+import type { Layer } from './layer.js';
+import { executeTrail } from './execute.js';
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options forwarded to `executeTrail` from `dispatch`. */
+export interface DispatchOptions {
+  /** Partial context overrides merged on top of the base context. */
+  readonly ctx?: Partial<TrailContext> | undefined;
+  /** AbortSignal override (takes final precedence over ctx and factory). */
+  readonly signal?: AbortSignal | undefined;
+  /** Layers to compose around the implementation. */
+  readonly layers?: readonly Layer[] | undefined;
+  /** Factory that produces a base TrailContext (takes precedence over defaults). */
+  readonly createContext?:
+    | (() => TrailContext | Promise<TrailContext>)
+    | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// dispatch()
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a trail by ID from a topo without mounting a surface.
+ *
+ * Resolves the trail from the topo, then runs it through the standard
+ * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
+ * trail ID is not registered. Never throws — unexpected exceptions are
+ * returned as `Result.err(InternalError)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export const dispatch = (
+  topo: Topo,
+  id: string,
+  input: unknown,
+  options?: DispatchOptions
+): Promise<Result<unknown, Error>> => {
+  const trail = topo.get(id);
+  if (trail === undefined) {
+    return Promise.resolve(
+      Result.err(
+        new NotFoundError(`Trail "${id}" not found in topo "${topo.name}"`)
+      )
+    );
+  }
+  return executeTrail(trail, input, options);
+};

package/src/execute.ts

@@ -0,0 +1,90 @@
+/**
+ * Centralized trail execution pipeline.
+ *
+ * Validates input, builds context, composes layers, and runs the
+ * implementation. Surfaces (CLI, MCP, HTTP) delegate here instead
+ * of reimplementing the pipeline.
+ */
+
+import type { AnyTrail } from './trail.js';
+import type { Layer } from './layer.js';
+import type { TrailContext } from './types.js';
+
+import { composeLayers } from './layer.js';
+import { createTrailContext } from './context.js';
+import { InternalError } from './errors.js';
+import { Result } from './result.js';
+import { validateInput } from './validation.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for executeTrail. */
+export interface ExecuteTrailOptions {
+  /** Partial context overrides merged on top of the base context. */
+  readonly ctx?: Partial<TrailContext> | undefined;
+  /** AbortSignal override (takes final precedence over ctx and factory). */
+  readonly signal?: AbortSignal | undefined;
+  /** Layers to compose around the implementation. */
+  readonly layers?: readonly Layer[] | undefined;
+  /** Factory that produces a base TrailContext (takes precedence over defaults). */
+  readonly createContext?:
+    | (() => TrailContext | Promise<TrailContext>)
+    | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Context resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TrailContext from options.
+ *
+ * Resolution order:
+ * 1. Factory (`createContext`) or `createTrailContext()` defaults.
+ * 2. Partial `ctx` overrides merged on top.
+ * 3. `signal` override takes final precedence.
+ */
+const resolveContext = async (
+  options?: ExecuteTrailOptions
+): Promise<TrailContext> => {
+  const base = options?.createContext
+    ? await options.createContext()
+    : createTrailContext();
+  const withOverrides = options?.ctx ? { ...base, ...options.ctx } : base;
+  return options?.signal
+    ? { ...withOverrides, signal: options.signal }
+    : withOverrides;
+};
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a trail through the standard validate-context-layers-run pipeline.
+ *
+ * The function never throws -- unexpected exceptions are caught and
+ * returned as `Result.err(InternalError)`.
+ */
+export const executeTrail = async (
+  trail: AnyTrail,
+  rawInput: unknown,
+  options?: ExecuteTrailOptions
+): Promise<Result<unknown, Error>> => {
+  try {
+    const validated = validateInput(trail.input, rawInput);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const ctx = await resolveContext(options);
+    const layers = options?.layers ?? [];
+    const impl = composeLayers([...layers], trail, trail.run);
+    return await impl(validated.value, ctx);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return Result.err(new InternalError(message));
+  }
+};

package/src/index.ts

@@ -51,7 +51,7 @@ export type {
 } from './trail.js';
 
 // Type utilities
-export type { TrailInput, TrailOutput } from './type-utils.js';
+export type { TrailInput, TrailOutput, TrailResult } from './type-utils.js';
 export { inputOf, outputOf } from './type-utils.js';
 
 // Event
@@ -87,6 +87,14 @@ export type {
 export { deriveFields } from './derive.js';
 export type { Field, FieldOverride } from './derive.js';
 
+// Execute
+export { executeTrail } from './execute.js';
+export type { ExecuteTrailOptions } from './execute.js';
+
+// Dispatch
+export { dispatch } from './dispatch.js';
+export type { DispatchOptions } from './dispatch.js';
+
 // Validation
 export {
   validateInput,

package/src/topo.ts

@@ -14,8 +14,10 @@ export interface Topo {
   readonly name: string;
   readonly trails: ReadonlyMap<string, AnyTrail>;
   readonly events: ReadonlyMap<string, AnyEvent>;
+  readonly count: number;
   get(id: string): AnyTrail | undefined;
   has(id: string): boolean;
+  ids(): string[];
   list(): AnyTrail[];
   listEvents(): AnyEvent[];
 }
@@ -43,6 +45,7 @@ const createTopo = (
   trails: ReadonlyMap<string, AnyTrail>,
   events: ReadonlyMap<string, AnyEvent>
 ): Topo => ({
+  count: trails.size,
   events,
   get(id: string): AnyTrail | undefined {
     return trails.get(id);
@@ -51,6 +54,10 @@ const createTopo = (
     return trails.has(id);
   },
 
+  ids(): string[] {
+    return [...trails.keys()];
+  },
+
   list(): AnyTrail[] {
     return [...trails.values()];
   },

package/src/type-utils.ts

@@ -2,6 +2,7 @@
  * Type utilities for extracting input/output types from trails.
  */
 
+import type { Result } from './result.js';
 import type { AnyTrail, Trail } from './trail.js';
 
 // ---------------------------------------------------------------------------
@@ -18,6 +19,17 @@ export type TrailInput<T extends AnyTrail> =
 export type TrailOutput<T extends AnyTrail> =
   T extends Trail<any, infer O> ? O : never;
 
+/**
+ * Extracts the full `Result<Output, Error>` type from a trail definition.
+ *
+ * @example
+ * ```typescript
+ * type SearchResult = TrailResult<typeof searchTrail>;
+ * // Result<{ results: Item[]; count: number }, Error>
+ * ```
+ */
+export type TrailResult<T extends AnyTrail> = Result<TrailOutput<T>, Error>;
+
 /* oxlint-enable no-explicit-any */
 
 // ---------------------------------------------------------------------------

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/adapters.ts","./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/fetch.ts","./src/guards.ts","./src/health.ts","./src/index.ts","./src/job.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}
+{"root":["./src/adapters.ts","./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/dispatch.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/guards.ts","./src/health.ts","./src/index.ts","./src/job.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}