@ontrails/core 1.0.0-beta.0

package/dist/result.js

@@ -0,0 +1,145 @@
+/**
+ * A type-safe Result monad for representing success/failure without exceptions.
+ */
+import { InternalError, ValidationError } from './errors.js';
+class Ok {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+    isOk() {
+        return true;
+    }
+    // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+    isErr() {
+        return false;
+    }
+    map(fn) {
+        return new Ok(fn(this.value));
+    }
+    flatMap(fn) {
+        return fn(this.value);
+    }
+    mapErr(_fn) {
+        return new Ok(this.value);
+    }
+    match(handlers) {
+        return handlers.ok(this.value);
+    }
+    unwrap() {
+        return this.value;
+    }
+    unwrapOr(_fallback) {
+        return this.value;
+    }
+}
+// oxlint-disable-next-line max-classes-per-file -- Result monad requires paired Ok/Err classes
+class Err {
+    error;
+    constructor(error) {
+        this.error = error;
+    }
+    // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+    isOk() {
+        return false;
+    }
+    // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+    isErr() {
+        return true;
+    }
+    map(_fn) {
+        return new Err(this.error);
+    }
+    flatMap(_fn) {
+        return new Err(this.error);
+    }
+    mapErr(fn) {
+        return new Err(fn(this.error));
+    }
+    match(handlers) {
+        return handlers.err(this.error);
+    }
+    unwrap() {
+        throw this.error instanceof Error
+            ? this.error
+            : new Error(String(this.error));
+    }
+    // oxlint-disable-next-line class-methods-use-this -- symmetric API with Ok.unwrapOr
+    unwrapOr(fallback) {
+        return fallback;
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export const Result = {
+    combine(results) {
+        const values = [];
+        for (const result of results) {
+            if (result.isErr()) {
+                return new Err(result.error);
+            }
+            values.push(result.value);
+        }
+        return new Ok(values);
+    },
+    err(error) {
+        return new Err(error);
+    },
+    /**
+     * Wrap a fetch call in a Result, mapping failures to TrailsError subclasses.
+     *
+     * Network errors become NetworkError. Abort signals become CancelledError.
+     * HTTP error status codes map to the appropriate error category.
+     */
+    async fromFetch(input, init) {
+        // Lazy import avoids a circular dependency (fetch.ts imports Result)
+        const { fromFetch: fetchImpl } = await import('./fetch.js');
+        return fetchImpl(input, init);
+    },
+    /**
+     * Parse a JSON string, returning a Result instead of throwing.
+     */
+    fromJson(json) {
+        try {
+            return new Ok(JSON.parse(json));
+        }
+        catch (error) {
+            return new Err(new ValidationError('Invalid JSON', {
+                cause: error instanceof Error ? error : new Error(String(error)),
+                context: { input: json.slice(0, 200) },
+            }));
+        }
+    },
+    ok(value) {
+        return new Ok(value);
+    },
+    /**
+     * Stringify a value to JSON, returning a Result. Handles circular references.
+     */
+    toJson(value) {
+        try {
+            const seen = new WeakSet();
+            const json = JSON.stringify(value, (_key, val) => {
+                if (typeof val === 'object' && val !== null) {
+                    if (seen.has(val)) {
+                        return '[Circular]';
+                    }
+                    seen.add(val);
+                }
+                return val;
+            });
+            if (json === undefined) {
+                return new Err(new InternalError('Value is not JSON-serializable', {
+                    context: { type: typeof value },
+                }));
+            }
+            return new Ok(json);
+        }
+        catch (error) {
+            return new Err(new InternalError('Failed to stringify value', {
+                cause: error instanceof Error ? error : new Error(String(error)),
+            }));
+        }
+    },
+};
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

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

package/dist/serialization.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Serialization utilities for @ontrails/core
+ *
+ * Safe JSON parsing/stringifying and error serialization/deserialization
+ * for transport across process boundaries.
+ */
+import type { ErrorCategory, TrailsError } from './errors.js';
+import { ValidationError, InternalError } from './errors.js';
+import { Result } from './result.js';
+export interface SerializedError {
+    readonly name: string;
+    readonly message: string;
+    readonly category?: ErrorCategory | undefined;
+    readonly retryable?: boolean | undefined;
+    readonly retryAfter?: number | undefined;
+    readonly context?: Record<string, unknown> | undefined;
+    readonly stack?: string | undefined;
+}
+/** Extract structured data from an Error for transport. */
+export declare const serializeError: (error: Error) => SerializedError;
+/** Reconstruct a TrailsError from serialized data. */
+export declare const deserializeError: (data: SerializedError) => TrailsError;
+/** Parse a JSON string, returning a Result instead of throwing. */
+export declare const safeParse: (json: string) => Result<unknown, ValidationError>;
+/** Stringify a value, returning a Result. Handles circular references. */
+export declare const safeStringify: (value: unknown) => Result<string, InternalError>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,eAAe,EAOf,aAAa,EAId,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAMrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AA4DD,2DAA2D;AAC3D,eAAO,MAAM,cAAc,GAAI,OAAO,KAAK,KAAG,eAmB7C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,GAAI,MAAM,eAAe,KAAG,WAcxD,CAAC;AAMF,mEAAmE;AACnE,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAAM,CAAC,OAAO,EAAE,eAAe,CAWvE,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,MAAM,CAAC,MAAM,EAAE,aAAa,CA2B9B,CAAC"}

package/dist/serialization.js

@@ -0,0 +1,115 @@
+/**
+ * Serialization utilities for @ontrails/core
+ *
+ * Safe JSON parsing/stringifying and error serialization/deserialization
+ * for transport across process boundaries.
+ */
+import { ValidationError, NotFoundError, ConflictError, PermissionError, TimeoutError, RateLimitError, NetworkError, InternalError, AuthError, CancelledError, isTrailsError, } from './errors.js';
+import { Result } from './result.js';
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before usage)
+// ---------------------------------------------------------------------------
+/** Build options object without including undefined context. */
+const buildOpts = (context) => {
+    if (context !== undefined) {
+        return { context };
+    }
+    return {};
+};
+const errorFactories = {
+    auth: (msg, opts) => new AuthError(msg, opts),
+    cancelled: (msg, opts) => new CancelledError(msg, opts),
+    conflict: (msg, opts) => new ConflictError(msg, opts),
+    internal: (msg, opts) => new InternalError(msg, opts),
+    network: (msg, opts) => new NetworkError(msg, opts),
+    not_found: (msg, opts) => new NotFoundError(msg, opts),
+    permission: (msg, opts) => new PermissionError(msg, opts),
+    rate_limit: (msg, opts, retryAfter) => {
+        const rlOpts = {
+            ...opts,
+        };
+        if (retryAfter !== undefined) {
+            rlOpts.retryAfter = retryAfter;
+        }
+        return new RateLimitError(msg, rlOpts);
+    },
+    timeout: (msg, opts) => new TimeoutError(msg, opts),
+    validation: (msg, opts) => new ValidationError(msg, opts),
+};
+const createErrorByCategory = (category, message, context, retryAfter) => {
+    const opts = buildOpts(context);
+    const factory = errorFactories[category] ?? errorFactories.internal;
+    return factory(message, opts, retryAfter);
+};
+// ---------------------------------------------------------------------------
+// Error serialization
+// ---------------------------------------------------------------------------
+/** Extract structured data from an Error for transport. */
+export const serializeError = (error) => {
+    const result = {
+        message: error.message,
+        name: error.name,
+        stack: error.stack,
+    };
+    if (isTrailsError(error)) {
+        return {
+            ...result,
+            category: error.category,
+            context: error.context,
+            retryAfter: error instanceof RateLimitError ? error.retryAfter : undefined,
+            retryable: error.retryable,
+        };
+    }
+    return result;
+};
+/** Reconstruct a TrailsError from serialized data. */
+export const deserializeError = (data) => {
+    const category = data.category ?? 'internal';
+    const error = createErrorByCategory(category, data.message, data.context, data.retryAfter);
+    if (data.stack) {
+        error.stack = data.stack;
+    }
+    return error;
+};
+// ---------------------------------------------------------------------------
+// Safe JSON
+// ---------------------------------------------------------------------------
+/** Parse a JSON string, returning a Result instead of throwing. */
+export const safeParse = (json) => {
+    try {
+        return Result.ok(JSON.parse(json));
+    }
+    catch (error) {
+        return Result.err(new ValidationError('Invalid JSON', {
+            cause: error instanceof Error ? error : new Error(String(error)),
+            context: { input: json.slice(0, 200) },
+        }));
+    }
+};
+/** Stringify a value, returning a Result. Handles circular references. */
+export const safeStringify = (value) => {
+    try {
+        const seen = new WeakSet();
+        const json = JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return '[Circular]';
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+        if (json === undefined) {
+            return Result.err(new InternalError('Value is not JSON-serializable', {
+                context: { type: typeof value },
+            }));
+        }
+        return Result.ok(json);
+    }
+    catch (error) {
+        return Result.err(new InternalError('Failed to stringify value', {
+            cause: error instanceof Error ? error : new Error(String(error)),
+        }));
+    }
+};
+//# sourceMappingURL=serialization.js.map

package/dist/serialization.js.map

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

package/dist/topo.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Application entry point — scans module exports to build a topology graph.
+ */
+import type { AnyEvent } from './event.js';
+import type { AnyHike } from './hike.js';
+import type { AnyTrail } from './trail.js';
+export interface Topo {
+    readonly name: string;
+    readonly trails: ReadonlyMap<string, AnyTrail>;
+    readonly hikes: ReadonlyMap<string, AnyHike>;
+    readonly events: ReadonlyMap<string, AnyEvent>;
+    get(id: string): AnyTrail | AnyHike | undefined;
+    has(id: string): boolean;
+    list(): (AnyTrail | AnyHike)[];
+    listEvents(): AnyEvent[];
+}
+export declare const topo: (name: string, ...modules: Record<string, unknown>[]) => Topo;
+//# sourceMappingURL=topo.d.ts.map

package/dist/topo.d.ts.map

@@ -0,0 +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,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,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,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,IAAI,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,EAAE,CAAC;IAC/B,UAAU,IAAI,QAAQ,EAAE,CAAC;CAC1B;AAmFD,eAAO,MAAM,IAAI,GACf,MAAM,MAAM,EACZ,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KACpC,IAcF,CAAC"}

package/dist/topo.js

@@ -0,0 +1,74 @@
+/**
+ * Application entry point — scans module exports to build a topology graph.
+ */
+import { ValidationError } from './errors.js';
+const isRegistrable = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { kind } = value;
+    return kind === 'trail' || kind === 'hike' || kind === 'event';
+};
+// ---------------------------------------------------------------------------
+// Topo implementation
+// ---------------------------------------------------------------------------
+const createTopo = (name, trails, hikes, events) => ({
+    events,
+    get(id) {
+        return trails.get(id) ?? hikes.get(id);
+    },
+    has(id) {
+        return trails.has(id) || hikes.has(id);
+    },
+    hikes,
+    list() {
+        return [...trails.values(), ...hikes.values()];
+    },
+    listEvents() {
+        return [...events.values()];
+    },
+    name,
+    trails,
+});
+// ---------------------------------------------------------------------------
+// topo()
+// ---------------------------------------------------------------------------
+/** Register a single registrable value into the appropriate map. */
+const register = (value, trails, hikes, events) => {
+    const { id } = value;
+    const registrars = {
+        event: () => {
+            if (events.has(id)) {
+                throw new ValidationError(`Duplicate event ID: "${id}"`);
+            }
+            events.set(id, value);
+        },
+        hike: () => {
+            if (hikes.has(id)) {
+                throw new ValidationError(`Duplicate hike ID: "${id}"`);
+            }
+            hikes.set(id, value);
+        },
+        trail: () => {
+            if (trails.has(id)) {
+                throw new ValidationError(`Duplicate trail ID: "${id}"`);
+            }
+            trails.set(id, value);
+        },
+    };
+    registrars[value.kind]?.();
+};
+export const topo = (name, ...modules) => {
+    const trails = new Map();
+    const hikes = new Map();
+    const events = new Map();
+    for (const mod of modules) {
+        for (const value of Object.values(mod)) {
+            if (isRegistrable(value)) {
+                register(value, trails, hikes, events);
+            }
+        }
+    }
+    return createTopo(name, trails, hikes, events);
+};
+//# sourceMappingURL=topo.js.map

package/dist/topo.js.map

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

package/dist/trail.d.ts

@@ -0,0 +1,83 @@
+import type { z } from 'zod';
+import type { FieldOverride } from './derive.js';
+import type { Result } from './result.js';
+import type { Implementation, TrailContext } from './types.js';
+/**
+ * A named example for documentation and testing.
+ *
+ * The `input` field accepts `Partial<I>` so that fields with schema defaults
+ * (e.g. `z.number().default(20)`) can be omitted from examples. The schema
+ * fills in defaults at validation time.
+ */
+export interface TrailExample<I, O> {
+    /** Human-readable name */
+    readonly name: string;
+    /** Optional description of what this example demonstrates */
+    readonly description?: string | undefined;
+    /** The input value — fields with schema defaults may be omitted */
+    readonly input: Partial<I>;
+    /** Expected output for success-path examples */
+    readonly expected?: O | undefined;
+    /** Error class name for error-path examples */
+    readonly error?: string | undefined;
+}
+/** Everything needed to define a trail (minus the id) */
+export interface TrailSpec<I, O> {
+    /** Zod schema for validating input */
+    readonly input: z.ZodType<I>;
+    /** Zod schema for validating output (optional — some trails are fire-and-forget) */
+    readonly output?: z.ZodType<O> | undefined;
+    /** The pure function that does the work (sync or async authoring) */
+    readonly implementation: Implementation<I, O>;
+    /** Human-readable description */
+    readonly description?: string | undefined;
+    /** Named examples for docs and testing */
+    readonly examples?: readonly TrailExample<I, O>[] | undefined;
+    /** Trail is read-only (no side effects) */
+    readonly readOnly?: boolean | undefined;
+    /** Trail is destructive (deletes or overwrites data) */
+    readonly destructive?: boolean | undefined;
+    /** Trail is idempotent (safe to retry) */
+    readonly idempotent?: boolean | undefined;
+    /** Arbitrary metadata for tooling and filtering */
+    readonly markers?: Readonly<Record<string, unknown>> | undefined;
+    /** Named sets of downstream trail IDs that may be invoked */
+    readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
+    /** Per-field overrides for deriveFields() (labels, hints, options) */
+    readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
+}
+/** A fully-defined trail — the unit of work in the Trails system */
+export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
+    readonly kind: 'trail';
+    readonly id: string;
+    readonly implementation: Implementation<I, O>;
+}
+/**
+ * Create a trail definition.
+ *
+ * Returns a frozen object with `kind: "trail"` and all spec fields.
+ * The trail is inert until handed to a runner.
+ *
+ * @example
+ * ```typescript
+ * // ID as first argument (recommended for human authoring)
+ * const show = trail("entity.show", {
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ *
+ * // Full spec object (for programmatic generation)
+ * const show = trail({
+ *   id: "entity.show",
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ * ```
+ */
+export declare function trail<I, O>(id: string, spec: TrailSpec<I, O>): Trail<I, O>;
+export declare function trail<I, O>(spec: TrailSpec<I, O> & {
+    readonly id: string;
+}): Trail<I, O>;
+export type AnyTrail = Trail<any, any>;
+export type { Implementation, TrailContext, Result };
+//# sourceMappingURL=trail.d.ts.map

package/dist/trail.d.ts.map

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

package/dist/trail.js

@@ -0,0 +1,16 @@
+export function trail(idOrSpec, maybeSpec) {
+    const resolved = typeof idOrSpec === 'string'
+        ? { id: idOrSpec, spec: maybeSpec }
+        : { id: idOrSpec.id, spec: idOrSpec };
+    if (!resolved.spec) {
+        throw new TypeError('trail() requires a spec when an id is provided');
+    }
+    const { implementation, ...spec } = resolved.spec;
+    return Object.freeze({
+        ...spec,
+        id: resolved.id,
+        implementation: async (input, ctx) => await implementation(input, ctx),
+        kind: 'trail',
+    });
+}
+//# sourceMappingURL=trail.js.map

package/dist/trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../src/trail.ts"],"names":[],"mappings":"AAqGA,MAAM,UAAU,KAAK,CACnB,QAA8D,EAC9D,SAA2B;IAE3B,MAAM,QAAQ,GACZ,OAAO,QAAQ,KAAK,QAAQ;QAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;QACnC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAE1C,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IAElD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,cAAc,EAAE,KAAK,EAAE,KAAQ,EAAE,GAAiB,EAAE,EAAE,CACpD,MAAM,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC;QAClC,IAAI,EAAE,OAAgB;KACvB,CAAC,CAAC;AACL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { Result } from './result.js';
+/**
+ * Trail implementation — sync or async.
+ *
+ * Authors can return `Result` directly or wrap it in a `Promise`. The framework
+ * normalizes with `await` at every call site, so both forms work transparently.
+ */
+export type Implementation<I, O> = (input: I, ctx: TrailContext) => Result<O, Error> | Promise<Result<O, Error>>;
+/** Invoke another trail by id — used for trail composition */
+export type FollowFn = <O>(id: string, input: unknown) => Promise<Result<O, Error>>;
+/** Callback for reporting progress from long-running trails */
+export type ProgressCallback = (event: ProgressEvent) => void;
+/** Structured progress event emitted during trail execution */
+export interface ProgressEvent {
+    readonly type: 'start' | 'progress' | 'complete' | 'error';
+    readonly current?: number | undefined;
+    readonly total?: number | undefined;
+    readonly message?: string | undefined;
+    readonly ts: string;
+}
+/** Minimal logger interface — implementations can bridge to any logging library */
+export interface Logger {
+    readonly name?: string | undefined;
+    trace(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    fatal(message: string, data?: Record<string, unknown>): void;
+    child(context: Record<string, unknown>): Logger;
+}
+/** Runtime context threaded through every trail execution */
+export interface TrailContext {
+    readonly requestId: string;
+    readonly signal: AbortSignal;
+    readonly follow?: FollowFn | undefined;
+    readonly permit?: unknown | undefined;
+    readonly workspaceRoot?: string | undefined;
+    readonly logger?: Logger | undefined;
+    readonly progress?: ProgressCallback | undefined;
+    readonly cwd?: string | undefined;
+    readonly env?: Record<string, string | undefined> | undefined;
+    readonly [key: string]: unknown;
+}
+export type Surface = 'cli' | 'mcp' | 'http' | 'ws';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate-topo.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structural validation for a Topo graph.
+ *
+ * Checks hike follows references, example input validity, event origin
+ * references, and output schema completeness. Returns a Result with all
+ * issues collected into a single ValidationError.
+ */
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+export interface TopoIssue {
+    readonly trailId: string;
+    readonly rule: string;
+    readonly message: string;
+}
+/**
+ * Validate the structural integrity of a Topo graph.
+ *
+ * Checks follows references, example inputs, event origins, and output
+ * schema presence. Returns `Result.ok()` when no issues are found, or
+ * `Result.err(ValidationError)` with all issues in the error context.
+ */
+export declare const validateTopo: (topo: Topo) => Result<void, ValidationError>;
+//# sourceMappingURL=validate-topo.d.ts.map

package/dist/validate-topo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-topo.d.ts","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAoGD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,MAAM,CAAC,IAAI,EAAE,eAAe,CAmBrE,CAAC"}