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

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # @ontrails/core
 
+## 1.0.0-beta.10
+
+### Minor Changes
+
+- Cleanup and hardening pass across all packages.
+
+  **core**: Deduplicate `DispatchOptions` as type alias of `ExecuteTrailOptions`. Replace `TrailContext` index signature with typed `extensions` field for type safety. Deep-merge `extensions` in `executeTrail` context resolution. Remove unused `Surface` type, `adapters.ts`, `health.ts`, and `job.ts` proof-of-concept from published package.
+
+  **cli**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out via `validate: false`.
+
+  **http**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out.
+
+  **mcp**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out.
+
+  **warden**: Project-aware rule context preserved in trail wrappers.
+
+## 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
+
+### Patch Changes
+
+- Fix Codex review findings on type-utils and follow-declarations.
+
+  **core**: `inputOf()`/`outputOf()` now preserve the exact Zod schema subtype instead of widening to `z.ZodType`.
+
+  **warden**: `follow-declarations` rule now recognizes single-object trail overload, detects any context parameter name (not just `ctx`), matches destructured `follow()` calls, resolves const identifiers in `follow` arrays, and restricts run body extraction to top-level config properties.
+
+## 1.0.0-beta.5
+
+### Minor Changes
+
+- Type utilities and follow-declarations warden rule.
+
+  **core**: Add `TrailInput<T>`, `TrailOutput<T>` utility types and `inputOf()`, `outputOf()` runtime schema accessors.
+
+  **warden**: Add `follow-declarations` rule — statically analyzes `ctx.follow()` calls against declared `follow: [...]` arrays. Errors on undeclared calls, warns on unused declarations.
+
+## 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)
+
+## 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.
+
+## 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.
+
+## 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)
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,179 +1,149 @@
 # @ontrails/core
 
-The foundation of Trails. Result type, error taxonomy, trail/hike/event definitions, topo, validation, patterns, redaction, branded types, and collection utilities. One external dependency: `zod`.
+The foundation. Define trails, compose them into topos, return typed Results, and let the framework derive everything else.
 
-## Installation
-
-```bash
-bun add @ontrails/core
-```
-
-## Quick Start
+## Usage
 
 ```typescript
-import { trail, hike, topo, Result } from '@ontrails/core';
+import { trail, topo, Result } from '@ontrails/core';
 import { z } from 'zod';
 
-// Define a trail -- the atomic unit of work
-const show = trail('entity.show', {
-  input: z.object({ name: z.string().describe('Entity name') }),
-  output: z.object({ name: z.string(), type: z.string() }),
-  readOnly: true,
+const greet = trail('greet', {
+  input: z.object({ name: z.string().describe('Who to greet') }),
+  output: z.object({ message: z.string() }),
+  intent: 'read',
   examples: [
-    {
-      name: 'Show an entity',
-      input: { name: 'Alpha' },
-      expected: { name: 'Alpha', type: 'concept' },
-    },
+    { name: 'Hello', input: { name: 'World' }, expected: { message: 'Hello, World!' } },
   ],
-  implementation: (input) => Result.ok({ name: input.name, type: 'concept' }),
+  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
-// Define a hike -- a composite that follows other trails
-const onboard = hike('entity.onboard', {
-  follows: ['entity.add', 'entity.relate'],
+const app = topo('myapp', { greet });
+```
+
+Trails compose other trails through `follow` and `ctx.follow()`:
+
+```typescript
+const onboard = trail('entity.onboard', {
+  follow: ['entity.add', 'entity.relate'],
   input: z.object({ name: z.string(), type: z.string() }),
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     const added = await ctx.follow('entity.add', input);
     if (added.isErr()) return added;
     return Result.ok({ entity: added.value });
   },
 });
-
-// Collect into an app
-import * as entity from './trails/entity';
-const app = topo('myapp', entity);
 ```
 
-Pure trails can return `Result` directly. Hikes and other I/O-bound trails can stay `async`; core normalizes both forms to one awaitable runtime shape before layers and surfaces execute them.
-
-## API Overview
+## API
 
-### Trail Primitives
+### Trail primitives
 
-- **`trail(id, spec)`** -- Define an atomic unit of work. Typed input via Zod, returns `Result`. Authoring may be sync or async.
-- **`hike(id, spec)`** -- Define a composite that follows multiple trails via `ctx.follow()`. Declares dependencies with `follows: string[]`.
-- **`event(id, spec)`** -- Define a server-originated push with a typed data schema.
-- **`topo(name, ...modules)`** -- Collect trail modules into an app. Scans exports for `Trail` shapes and builds the topo.
+| Export | What it does |
+| --- | --- |
+| `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `follow` for composition |
+| `event(id, spec)` | Define a server-originated push with a typed data schema |
+| `topo(name, ...modules)` | Collect trail modules into a queryable topology |
+| `validateTopo(topo)` | Structural validation: follow targets exist, no cycles, examples parse, output schemas present |
 
-### Result Type
+### Execution
 
-Built-in `Result<T, E>` with no external dependency.
+| 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
-Result.ok(value); // Create a success
-Result.err(error); // Create a failure
-Result.combine(results); // Collect Result<T>[] into Result<T[]>
-
-result.isOk(); // Type guard for Ok
-result.isErr(); // Type guard for Err
-result.map(fn); // Transform success value
-result.flatMap(fn); // Chain Result-returning functions
-result.match({ ok, err }); // Pattern match
-result.unwrapOr(fallback); // Value or fallback
-```
-
-Implementations return `Result`, never `throw`.
+// executeTrail — surface adapters use this directly
+const result = await executeTrail(greet, { name: 'Alice' });
 
-### Error Taxonomy
+// dispatch — no-surface execution by trail ID
+const result = await dispatch(app, 'greet', { name: 'Alice' });
+if (result.isOk()) console.log(result.value);
+```
 
-13 error classes across 10 categories, all extending `TrailsError`. Each maps to CLI exit codes, HTTP status codes, JSON-RPC codes, and retryability.
+### Topo accessors
 
-| Category | Classes | Exit | HTTP | Retryable |
-| --- | --- | --- | --- | --- |
-| `validation` | `ValidationError`, `AmbiguousError`, `AssertionError` | 1 | 400 | No |
-| `not_found` | `NotFoundError` | 2 | 404 | No |
-| `conflict` | `AlreadyExistsError`, `ConflictError` | 3 | 409 | No |
-| `permission` | `PermissionError` | 4 | 403 | No |
-| `timeout` | `TimeoutError` | 5 | 504 | Yes |
-| `rate_limit` | `RateLimitError` | 6 | 429 | Yes |
-| `network` | `NetworkError` | 7 | 502 | Yes |
-| `internal` | `InternalError` | 8 | 500 | No |
-| `auth` | `AuthError` | 9 | 401 | No |
-| `cancelled` | `CancelledError` | 130 | 499 | No |
+Beyond the `trail(id, spec)` builder, `Topo` exposes these accessors:
 
-All extend `TrailsError` directly (class inheritance, no factory pattern). Pattern matching via `instanceof` or `error.category`.
+| 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 |
 
-### Patterns (`@ontrails/core/patterns`)
+### Type utilities
 
-Reusable Zod schemas for common input/output shapes:
+| 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 |
 
-- **Pagination** -- `paginationInput`, `paginationOutput` (cursor-based)
-- **Bulk operations** -- `bulkInput`, `bulkOutput` (batch with per-item results)
-- **Timestamps** -- `timestamps` (`createdAt`/`updatedAt`)
-- **Date ranges** -- `dateRangeInput` (`since`/`until`)
-- **Sorting** -- `sortInput` (`sortBy`/`sortOrder`)
-- **Status** -- `statusField` (lifecycle state)
-- **Change tracking** -- `changeOutput` (before/after snapshots)
-- **Progress** -- `progressOutput` (completion reporting)
+### Execution option types
 
-### Redaction (`@ontrails/core/redaction`)
+| Type | What it describes |
+| --- | --- |
+| `ExecuteTrailOptions` | Options for `executeTrail`: `ctx`, `signal`, `layers`, `createContext` |
+| `DispatchOptions` | Same shape as `ExecuteTrailOptions`; forwarded by `dispatch` |
 
-Strip sensitive data from logs and outputs.
+### Result
 
 ```typescript
-import {
-  createRedactor,
-  DEFAULT_PATTERNS,
-  DEFAULT_SENSITIVE_KEYS,
-} from '@ontrails/core/redaction';
-
-const redactor = createRedactor({
-  patterns: DEFAULT_PATTERNS,
-  sensitiveKeys: DEFAULT_SENSITIVE_KEYS,
-});
+Result.ok(value);            // Success
+Result.err(error);           // Failure
+Result.combine(results);     // Result<T>[] → Result<T[]>
+Result.fromJson(json);       // Parse JSON string into Result
+Result.toJson(value);        // Serialize to JSON string as Result
+Result.fromFetch(response);  // Convert fetch Response to Result
+
+result.isOk();               // Type guard
+result.isErr();              // Type guard
+result.map(fn);              // Transform success
+result.flatMap(fn);          // Chain Result-returning functions
+result.match({ ok, err });   // Pattern match
+result.unwrapOr(fallback);   // Value or fallback
 ```
 
-### Validation
-
-- **`validateInput(schema, data)`** -- Validate data against a Zod schema, returning `Result`.
-- **`formatZodIssues(issues)`** -- Format Zod issues into human-readable strings.
-- **`zodToJsonSchema(schema)`** -- Convert a Zod schema to JSON Schema for MCP/HTTP surfaces.
+### Error taxonomy
 
-### Branded Types
+13 error classes across 10 categories. Each maps deterministically to exit codes, HTTP status, and JSON-RPC codes on every surface.
 
-Nominal typing for IDs and domain-specific strings that should not be interchangeable.
+| Category | Classes | HTTP | Retryable |
+| --- | --- | --- | --- |
+| `validation` | `ValidationError`, `AmbiguousError`, `AssertionError` | 400 | No |
+| `not_found` | `NotFoundError` | 404 | No |
+| `conflict` | `AlreadyExistsError`, `ConflictError` | 409 | No |
+| `permission` | `PermissionError` | 403 | No |
+| `timeout` | `TimeoutError` | 504 | Yes |
+| `rate_limit` | `RateLimitError` | 429 | Yes |
+| `network` | `NetworkError` | 502 | Yes |
+| `internal` | `InternalError` | 500 | No |
+| `auth` | `AuthError` | 401 | No |
+| `cancelled` | `CancelledError` | 499 | No |
 
-```typescript
-import { uuid, email, nonEmptyString, positiveInt } from '@ontrails/core';
-
-const id = uuid('550e8400-e29b-41d4-a716-446655440000');
-const addr = email('user@example.com');
-```
+The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every surface.
 
-### Collections and Guards
+### Other exports
 
-- **Collections** -- `chunk`, `dedupe`, `groupBy`, `sortBy`, `isNonEmptyArray`
-- **Guards** -- `isDefined`, `isNonEmptyString`, `isPlainObject`, `hasProperty`, `assertNever`
+- **Schema derivation** -- `deriveFields(schema)` extracts field metadata from Zod for prompts and forms
+- **Validation** -- `validateInput`, `formatZodIssues`, `zodToJsonSchema`
 - **Resilience** -- `retry`, `withTimeout`, `shouldRetry`, `getBackoffDelay`
-- **Serialization** -- `serializeError`, `deserializeError`, `Result.fromJson`, `Result.toJson`
-- **Path Security** -- `securePath`, `isPathSafe`, `resolveSafePath`
-- **Workspace** -- `findWorkspaceRoot`, `isInsideWorkspace`, `getRelativePath`
+- **Serialization** -- `serializeError`, `deserializeError`
+- **Branded types** -- `uuid`, `email`, `nonEmptyString`, `positiveInt`
+- **Layers** -- cross-cutting middleware via `composeLayers`
+- **Guards and collections** -- `isDefined`, `chunk`, `dedupe`, `groupBy`, `sortBy`
+- **Patterns** (`@ontrails/core/patterns`) -- reusable Zod schemas for pagination, bulk ops, timestamps, sorting
+- **Redaction** (`@ontrails/core/redaction`) -- strip sensitive data before logging
 
-### Layers
+See the [API Reference](../../docs/api-reference.md) for the full list.
 
-Cross-cutting concerns that wrap trail execution:
+## Installation
 
-```typescript
-const loggingLayer: Layer = {
-  name: 'logging',
-  wrap: (next, trail) => async (input, ctx) => {
-    ctx.logger.info(`Executing ${trail.id}`);
-    return next(input, ctx);
-  },
-};
+```bash
+bun add @ontrails/core zod
 ```
-
-## Subpath Exports
-
-| Export | Contents |
-| --- | --- |
-| `@ontrails/core` | trail, hike, event, topo, Result, errors, types, validation, guards, collections, layers |
-| `@ontrails/core/patterns` | Reusable Zod schema patterns |
-| `@ontrails/core/redaction` | Redactor, default patterns and keys |
-
-## Further Reading
-
-- [Getting Started](../../docs/getting-started.md)
-- [Architecture](../../docs/architecture.md)
-- [Vocabulary](../../docs/vocabulary.md)

package/dist/derive.d.ts

@@ -8,7 +8,7 @@ import type { z } from 'zod';
 /** A surface-agnostic field descriptor derived from a Zod schema. */
 export interface Field {
     readonly name: string;
-    readonly type: 'string' | 'number' | 'boolean' | 'enum' | 'multiselect';
+    readonly type: 'string' | 'number' | 'boolean' | 'enum' | 'multiselect' | 'string[]' | 'number[]';
     readonly label: string;
     readonly required: boolean;
     readonly default?: unknown | undefined;

package/dist/derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,aAAa,CAAC;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAmKD,eAAO,MAAM,YAAY,GACvB,QAAQ,CAAC,CAAC,OAAO,EACjB,YAAY,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACxC,KAAK,EAeP,CAAC"}
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,qEAAqE;AACrE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,aAAa,GACb,UAAU,GACV,UAAU,CAAC;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EACb,SAAS;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,EAAE,GACH,SAAS,CAAC;CACf;AAsKD,eAAO,MAAM,YAAY,GACvB,QAAQ,CAAC,CAAC,OAAO,EACjB,YAAY,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACxC,KAAK,EAeP,CAAC"}

package/dist/derive.js

@@ -60,7 +60,10 @@ const fieldTypeByDef = {
             const entries = element._zod.def['entries'];
             return { options: Object.values(entries), type: 'multiselect' };
         }
-        return { options: undefined, type: 'string' };
+        return {
+            options: undefined,
+            type: elementType === 'number' ? 'number[]' : 'string[]',
+        };
     },
     boolean: () => ({ options: undefined, type: 'boolean' }),
     enum: (s) => {

package/dist/derive.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkDH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CACvC,GAAG;KACA,UAAU,CAAC,iBAAiB,EAAE,OAAO,CAAC;KACtC,UAAU,CAAC,uBAAuB,EAAE,OAAO,CAAC;KAC5C,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAS7C,8DAA8D;AAC9D,MAAM,YAAY,GAAG,CAAC,OAAqB,EAAgB,EAAE,CAC3D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAiB,CAAC;AAEhD,4DAA4D;AAC5D,MAAM,oBAAoB,GAAG,CAC3B,KAAmB,EACnB,KAA0C,EACpC,EAAE;IACR,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACxC,CAAC;AACH,CAAC,CAAC;AAEF,yFAAyF;AACzF,MAAM,UAAU,GAAG,CACjB,OAAqB,EACrB,KAIC,EACoB,EAAE;IACvB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;IACnD,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,GAAG,CAAC,CAAe,EAAgB,EAAE;IAC/C,MAAM,KAAK,GAAG;QACZ,YAAY,EAAE,SAAoB;QAClC,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM;QACR,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC,CAAC;AAOF,MAAM,cAAc,GAA0D;IAC5E,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;QACX,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA4B,CAAC;QACjE,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;QACvD,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA2B,CAAC;YACtE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAClE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACxD,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE;QACV,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAA2B,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC3D,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACtD,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;CACvD,CAAC;AAEF,oEAAoE;AACpE,MAAM,eAAe,GAAG,CAAC,CAAe,EAAoB,EAAE;IAC5D,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAW,CAAC;IAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACrE,CAAC,CAAC;AAEF,gEAAgE;AAChE,MAAM,YAAY,GAAG,CACnB,UAAgC,EAChC,eAAqD,EACvB,EAAE;IAChC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1B,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,gDAAgD;AAChD,MAAM,WAAW,GAAG,CAClB,GAAW,EACX,KAAmB,EACnB,SAAyC,EAClC,EAAE;IACT,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACrE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,QAAQ,EAAE,KAAK,IAAI,WAAW,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC9E,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAAiB,EACjB,SAAyC,EAChC,EAAE;IACX,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,IAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAY,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAA6C,CAAC;IAC9E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACxD,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,CACnC,CAAC;IACF,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACjE,CAAC,CAAC"}
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { ExecuteTrailOptions } from './execute.js';
+import { Result } from './result.js';
+/** Options forwarded to `executeTrail` from `dispatch`. */
+export type DispatchOptions = ExecuteTrailOptions;
+/**
+ * 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;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAMrC,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAMlD;;;;;;;;;;;;;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;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,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/event.d.ts

@@ -5,7 +5,7 @@ import type { z } from 'zod';
 export interface EventSpec<T> {
     readonly payload: z.ZodType<T>;
     readonly description?: string | undefined;
-    readonly markers?: Readonly<Record<string, unknown>> | undefined;
+    readonly metadata?: Readonly<Record<string, unknown>> | undefined;
     /** Trail IDs that produce this event (e.g. the trails it originates from). */
     readonly from?: readonly string[] | undefined;
 }
@@ -14,7 +14,7 @@ export interface Event<T> {
     readonly kind: 'event';
     readonly payload: z.ZodType<T>;
     readonly description?: string | undefined;
-    readonly markers?: Readonly<Record<string, unknown>> | undefined;
+    readonly metadata?: Readonly<Record<string, unknown>> | undefined;
     /** Trail IDs that produce this event (e.g. the trails it originates from). */
     readonly from?: readonly string[] | undefined;
 }

package/dist/event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AACnE,wBAAgB,KAAK,CAAC,CAAC,EACrB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3C,KAAK,CAAC,CAAC,CAAC,CAAC;AAkBZ,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAClE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAClE,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AACnE,wBAAgB,KAAK,CAAC,CAAC,EACrB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3C,KAAK,CAAC,CAAC,CAAC,CAAC;AAkBZ,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC"}

package/dist/event.js

@@ -10,7 +10,7 @@ export function event(idOrSpec, maybeSpec) {
         from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
         id: resolvedId,
         kind: 'event',
-        markers: resolvedSpec.markers,
+        metadata: resolvedSpec.metadata,
         payload: resolvedSpec.payload,
     });
 }

package/dist/event.js.map

@@ -1 +1 @@
-{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwDH,MAAM,UAAU,KAAK,CACnB,QAA2D,EAC3D,SAAwB;IAExB,MAAM,UAAU,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzE,0GAA0G;IAC1G,MAAM,YAAY,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,YAAY,CAAC,WAAW;QACrC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,OAAgB;QACtB,OAAO,EAAE,YAAY,CAAC,OAAO;QAC7B,OAAO,EAAE,YAAY,CAAC,OAAO;KAC9B,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwDH,MAAM,UAAU,KAAK,CACnB,QAA2D,EAC3D,SAAwB;IAExB,MAAM,UAAU,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzE,0GAA0G;IAC1G,MAAM,YAAY,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,YAAY,CAAC,WAAW;QACrC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,OAAgB;QACtB,QAAQ,EAAE,YAAY,CAAC,QAAQ;QAC/B,OAAO,EAAE,YAAY,CAAC,OAAO;KAC9B,CAAC,CAAC;AACL,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;AAoCD;;;;;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"}