@ontrails/core 1.0.0-beta.1 → 1.0.0-beta.11

package/src/service.ts

@@ -0,0 +1,139 @@
+import { NotFoundError } from './errors.js';
+import type { Result } from './result.js';
+import type { ServiceLookup, TrailContext } from './types.js';
+import type { z } from 'zod';
+
+/**
+ * Stable process-scoped fields available when constructing a service.
+ *
+ * Services are app-level singletons, so they intentionally do not receive the
+ * full per-request TrailContext.
+ */
+export type ServiceContext = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+>;
+
+/**
+ * Everything needed to describe a service before a factory is introduced.
+ */
+export interface ServiceSpec<T> {
+  /** Create the service instance from stable process-scoped context. */
+  readonly create: (
+    svc: ServiceContext
+  ) => Result<T, Error> | Promise<Result<T, Error>>;
+  /** Reserved config schema for follow-up config composition work. */
+  readonly config?: z.ZodType | undefined;
+  /** Optional cleanup performed when the hosting surface shuts down. */
+  readonly dispose?: ((service: T) => void | Promise<void>) | undefined;
+  /** Optional operational readiness probe for introspection tooling. */
+  readonly health?:
+    | ((service: T) => Result<unknown, Error> | Promise<Result<unknown, Error>>)
+    | undefined;
+  /** Optional test factory used by higher-level helpers. */
+  readonly mock?: (() => T | Promise<T>) | undefined;
+  /** Human-readable description. */
+  readonly description?: string | undefined;
+  /** Arbitrary metadata for tooling and filtering. */
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * A typed service definition.
+ *
+ * TRL-73 introduces the structural contract only. The `service()` factory and
+ * runtime helpers land in follow-up branches.
+ */
+export interface Service<T> extends ServiceSpec<T> {
+  readonly kind: 'service';
+  readonly id: string;
+  /** Read the resolved service instance from a trail context. */
+  from(ctx: TrailContext): T;
+}
+
+/**
+ * Existential type for heterogeneous service collections.
+ *
+ * `Service<T>` includes function parameters in `dispose`/`health`, so `unknown`
+ * is too narrow for mixed service arrays. `any` is the correct existential here.
+ */
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous service collections
+export type AnyService = Service<any>;
+
+/** Explicit runtime overrides keyed by service ID. */
+export type ServiceOverrideMap = Readonly<Record<string, unknown>>;
+
+const getServiceId = <T>(
+  serviceOrId: string | Pick<Service<T>, 'id'>
+): string => (typeof serviceOrId === 'string' ? serviceOrId : serviceOrId.id);
+
+const getServiceInstance = <T>(
+  ctx: Pick<TrailContext, 'extensions'>,
+  serviceOrId: string | Pick<Service<T>, 'id'>
+): T => {
+  const id = getServiceId(serviceOrId);
+  return ctx.extensions?.[id] as T;
+};
+
+const hasServiceInstance = (
+  ctx: Pick<TrailContext, 'extensions'>,
+  serviceOrId: string | Pick<AnyService, 'id'>
+): boolean => Object.hasOwn(ctx.extensions ?? {}, getServiceId(serviceOrId));
+
+/** Create a `ctx.service(...)` accessor bound to a concrete context snapshot. */
+export const createServiceLookup = (
+  getContext: () => Pick<TrailContext, 'extensions'>
+): ServiceLookup =>
+  ((serviceOrId: string | Pick<AnyService, 'id'>) => {
+    const id = getServiceId(serviceOrId);
+    const ctx = getContext();
+    if (!hasServiceInstance(ctx, id)) {
+      throw new NotFoundError(`Service "${id}" not found in trail context`);
+    }
+    return getServiceInstance(ctx, id);
+  }) as ServiceLookup;
+
+/**
+ * Create a typed service definition.
+ *
+ * The service object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export const service = <T>(id: string, spec: ServiceSpec<T>): Service<T> =>
+  Object.freeze({
+    ...spec,
+    from(ctx: TrailContext): T {
+      const lookup = ctx.service ?? createServiceLookup(() => ctx);
+      return lookup(this);
+    },
+    id,
+    kind: 'service' as const,
+  });
+
+/** Narrow unknown values to service definitions during topo discovery. */
+export const isService = (value: unknown): value is AnyService => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as { kind?: unknown; id?: unknown };
+  return v.kind === 'service' && typeof v.id === 'string';
+};
+
+/**
+ * Return the first duplicate service ID in a collection, if any.
+ *
+ * This supports later topo registration without each caller duplicating the
+ * same scan logic.
+ */
+export const findDuplicateServiceId = (
+  services: readonly Pick<AnyService, 'id'>[]
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const candidate of services) {
+    if (seen.has(candidate.id)) {
+      return candidate.id;
+    }
+    seen.add(candidate.id);
+  }
+  return undefined;
+};

package/src/topo.ts

@@ -4,7 +4,8 @@
 
 import { ValidationError } from './errors.js';
 import type { AnyEvent } from './event.js';
-import type { AnyHike } from './hike.js';
+import type { AnyService } from './service.js';
+import { isService } from './service.js';
 import type { AnyTrail } from './trail.js';
 
 // ---------------------------------------------------------------------------
@@ -14,26 +15,33 @@ 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;
+  readonly services: ReadonlyMap<string, AnyService>;
+  readonly count: number;
+  readonly serviceCount: number;
+  get(id: string): AnyTrail | undefined;
+  getService(id: string): AnyService | undefined;
   has(id: string): boolean;
-  list(): (AnyTrail | AnyHike)[];
+  hasService(id: string): boolean;
+  ids(): string[];
+  serviceIds(): string[];
+  list(): AnyTrail[];
   listEvents(): AnyEvent[];
+  listServices(): AnyService[];
 }
 
 // ---------------------------------------------------------------------------
 // Kind discriminant check
 // ---------------------------------------------------------------------------
 
-type Registrable = AnyTrail | AnyHike | AnyEvent;
+type Registrable = AnyTrail | AnyEvent | AnyService;
 
 const isRegistrable = (value: unknown): value is Registrable => {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
   const { kind } = value as Record<string, unknown>;
-  return kind === 'trail' || kind === 'hike' || kind === 'event';
+  return kind === 'trail' || kind === 'event';
 };
 
 // ---------------------------------------------------------------------------
@@ -43,28 +51,46 @@ const isRegistrable = (value: unknown): value is Registrable => {
 const createTopo = (
   name: string,
   trails: ReadonlyMap<string, AnyTrail>,
-  hikes: ReadonlyMap<string, AnyHike>,
-  events: ReadonlyMap<string, AnyEvent>
+  events: ReadonlyMap<string, AnyEvent>,
+  services: ReadonlyMap<string, AnyService>
 ): Topo => ({
+  count: trails.size,
   events,
-  get(id: string): AnyTrail | AnyHike | undefined {
-    return trails.get(id) ?? hikes.get(id);
+  get(id: string): AnyTrail | undefined {
+    return trails.get(id);
+  },
+  getService(id: string): AnyService | undefined {
+    return services.get(id);
   },
   has(id: string): boolean {
-    return trails.has(id) || hikes.has(id);
+    return trails.has(id);
+  },
+  hasService(id: string): boolean {
+    return services.has(id);
+  },
+
+  ids(): string[] {
+    return [...trails.keys()];
   },
-  hikes,
 
-  list(): (AnyTrail | AnyHike)[] {
-    return [...trails.values(), ...hikes.values()];
+  list(): AnyTrail[] {
+    return [...trails.values()];
   },
 
   listEvents(): AnyEvent[] {
     return [...events.values()];
   },
+  listServices(): AnyService[] {
+    return [...services.values()];
+  },
 
   name,
+  serviceCount: services.size,
+  serviceIds(): string[] {
+    return [...services.keys()];
+  },
 
+  services,
   trails,
 });
 
@@ -76,8 +102,8 @@ const createTopo = (
 const register = (
   value: Registrable,
   trails: Map<string, AnyTrail>,
-  hikes: Map<string, AnyHike>,
-  events: Map<string, AnyEvent>
+  events: Map<string, AnyEvent>,
+  services: Map<string, AnyService>
 ): void => {
   const { id } = value as { id: string };
   const registrars: Record<string, () => void> = {
@@ -87,11 +113,11 @@ const register = (
       }
       events.set(id, value as AnyEvent);
     },
-    hike: () => {
-      if (hikes.has(id)) {
-        throw new ValidationError(`Duplicate hike ID: "${id}"`);
+    service: () => {
+      if (services.has(id)) {
+        throw new ValidationError(`Duplicate service ID: "${id}"`);
       }
-      hikes.set(id, value as AnyHike);
+      services.set(id, value as AnyService);
     },
     trail: () => {
       if (trails.has(id)) {
@@ -103,21 +129,34 @@ const register = (
   registrars[value.kind]?.();
 };
 
+const registerModuleValues = (
+  mod: Record<string, unknown>,
+  trails: Map<string, AnyTrail>,
+  events: Map<string, AnyEvent>,
+  services: Map<string, AnyService>
+): void => {
+  for (const value of Object.values(mod)) {
+    if (isService(value)) {
+      register(value, trails, events, services);
+      continue;
+    }
+    if (isRegistrable(value)) {
+      register(value, trails, events, services);
+    }
+  }
+};
+
 export const topo = (
   name: string,
   ...modules: Record<string, unknown>[]
 ): Topo => {
   const trails = new Map<string, AnyTrail>();
-  const hikes = new Map<string, AnyHike>();
   const events = new Map<string, AnyEvent>();
+  const services = new Map<string, AnyService>();
 
   for (const mod of modules) {
-    for (const value of Object.values(mod)) {
-      if (isRegistrable(value)) {
-        register(value, trails, hikes, events);
-      }
-    }
+    registerModuleValues(mod, trails, events, services);
   }
 
-  return createTopo(name, trails, hikes, events);
+  return createTopo(name, trails, events, services);
 };

package/src/trail.ts

@@ -2,6 +2,7 @@ import type { z } from 'zod';
 
 import type { FieldOverride } from './derive.js';
 import type { Result } from './result.js';
+import type { AnyService } from './service.js';
 import type { Implementation, TrailContext } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -39,34 +40,48 @@ export interface TrailSpec<I, O> {
   /** 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>;
+  readonly run: 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;
+  /** What this trail does to the world: read, write (default), or destroy */
+  readonly intent?: 'read' | 'write' | 'destroy' | undefined;
   /** Trail is idempotent (safe to retry) */
   readonly idempotent?: boolean | undefined;
   /** Arbitrary metadata for tooling and filtering */
-  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  readonly metadata?: 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;
+  /** IDs of downstream trails this trail may invoke via ctx.follow() */
+  readonly follow?: readonly string[] | undefined;
+  /** Services this trail may access via service.from(ctx) */
+  readonly services?: readonly AnyService[] | undefined;
 }
 
 // ---------------------------------------------------------------------------
 // Trail (the frozen runtime object)
 // ---------------------------------------------------------------------------
 
+/** Intent describes what a trail does to the world */
+export type Intent = 'read' | 'write' | 'destroy';
+
 /** A fully-defined trail — the unit of work in the Trails system */
-export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
+export interface Trail<I, O> extends Omit<
+  TrailSpec<I, O>,
+  'run' | 'follow' | 'intent' | 'services'
+> {
   readonly kind: 'trail';
   readonly id: string;
-  readonly implementation: Implementation<I, O>;
+  readonly run: Implementation<I, O>;
+  /** IDs of downstream trails this trail may invoke via ctx.follow() (always present, default []) */
+  readonly follow: readonly string[];
+  /** Services this trail may access via service.from(ctx) (always present, default []) */
+  readonly services: readonly AnyService[];
+  /** What this trail does to the world (always present, default 'write') */
+  readonly intent: Intent;
 }
 
 // ---------------------------------------------------------------------------
@@ -84,14 +99,14 @@ export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
  * // ID as first argument (recommended for human authoring)
  * const show = trail("entity.show", {
  *   input: z.object({ name: z.string() }),
- *   implementation: (input) => Result.ok(entity),
+ *   run: (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),
+ *   run: (input) => Result.ok(entity),
  * });
  * ```
  */
@@ -112,14 +127,22 @@ export function trail<I, O>(
     throw new TypeError('trail() requires a spec when an id is provided');
   }
 
-  const { implementation, ...spec } = resolved.spec;
+  const {
+    run,
+    follow: rawFollow,
+    intent: rawIntent,
+    services: rawServices,
+    ...spec
+  } = resolved.spec;
 
   return Object.freeze({
     ...spec,
+    follow: Object.freeze([...(rawFollow ?? [])]),
     id: resolved.id,
-    implementation: async (input: I, ctx: TrailContext) =>
-      await implementation(input, ctx),
+    intent: rawIntent ?? 'write',
     kind: 'trail' as const,
+    run: async (input: I, ctx: TrailContext) => await run(input, ctx),
+    services: Object.freeze([...(rawServices ?? [])]),
   });
 }
 

package/src/type-utils.ts

@@ -0,0 +1,45 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+
+import type { Result } from './result.js';
+import type { AnyTrail, Trail } from './trail.js';
+
+// ---------------------------------------------------------------------------
+// Utility types
+// ---------------------------------------------------------------------------
+
+/* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
+
+/** 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>;
+
+/* oxlint-enable no-explicit-any */
+
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+
+/** Get the input Zod schema from a trail, preserving the specific schema type. */
+export const inputOf = <T extends AnyTrail>(trail: T): T['input'] =>
+  trail.input;
+
+/** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */
+export const outputOf = <T extends AnyTrail>(trail: T): T['output'] =>
+  trail.output;

package/src/types.ts

@@ -17,6 +17,11 @@ export type FollowFn = <O>(
   input: unknown
 ) => Promise<Result<O, Error>>;
 
+/** Resolve a service instance from the current trail context. */
+export type ServiceLookup = <T = unknown>(
+  serviceOrId: { readonly id: string } | string
+) => T;
+
 /** Callback for reporting progress from long-running trails */
 export type ProgressCallback = (event: ProgressEvent) => void;
 
@@ -52,7 +57,11 @@ export interface TrailContext {
   readonly progress?: ProgressCallback | undefined;
   readonly cwd?: string | undefined;
   readonly env?: Record<string, string | undefined> | undefined;
-  readonly [key: string]: unknown;
+  readonly extensions?: Readonly<Record<string, unknown>> | undefined;
+  readonly service?: ServiceLookup | undefined;
 }
 
-export type Surface = 'cli' | 'mcp' | 'http' | 'ws';
+/** Input shape used to seed a runtime TrailContext before resolution. */
+export type TrailContextInit = Omit<TrailContext, 'service'> & {
+  readonly service?: ServiceLookup | undefined;
+};

package/src/validate-topo.ts

@@ -1,14 +1,13 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks hike follows references, example input validity, event origin
+ * Checks trail follow 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 type { AnyEvent } from './event.js';
-import type { AnyHike } from './hike.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
@@ -28,28 +27,110 @@ export interface TopoIssue {
 // Validators
 // ---------------------------------------------------------------------------
 
+const WHITE = 0;
+const GRAY = 1;
+const BLACK = 2;
+
+/** Build an adjacency list and initial color map from trails with follow. */
+const buildFollowGraph = (
+  trails: ReadonlyMap<string, AnyTrail>
+): {
+  graph: Map<string, readonly string[]>;
+  color: Map<string, number>;
+} => {
+  const graph = new Map<string, readonly string[]>();
+  for (const [id, t] of trails) {
+    if (t.follow.length > 0) {
+      graph.set(id, t.follow);
+    }
+  }
+  const color = new Map<string, number>();
+  for (const id of graph.keys()) {
+    color.set(id, WHITE);
+  }
+  return { color, graph };
+};
+
+/** Detect multi-node cycles in the trail follow graph via DFS. */
+const detectFollowCycles = (
+  trails: ReadonlyMap<string, AnyTrail>
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  const { color, graph } = buildFollowGraph(trails);
+
+  const dfs = (node: string, path: string[]): void => {
+    color.set(node, GRAY);
+    for (const next of graph.get(node) ?? []) {
+      if (!graph.has(next)) {
+        continue;
+      }
+      const c = color.get(next) ?? WHITE;
+      if (c === GRAY) {
+        const cycle = [...path.slice(path.indexOf(next)), next];
+        issues.push({
+          message: `Cycle detected: ${cycle.join(' → ')}`,
+          rule: 'follow-cycle',
+          trailId: next,
+        });
+      } else if (c === WHITE) {
+        dfs(next, [...path, next]);
+      }
+    }
+    color.set(node, BLACK);
+  };
+
+  for (const id of graph.keys()) {
+    if (color.get(id) === WHITE) {
+      dfs(id, [id]);
+    }
+  }
+  return issues;
+};
+
 const checkFollows = (
-  hikes: ReadonlyMap<string, AnyHike>,
+  trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
-  for (const [id, hike] of hikes) {
-    for (const followId of hike.follows) {
+  for (const [id, trail] of trails) {
+    for (const followId of trail.follow) {
       if (followId === id) {
         issues.push({
-          message: `Hike follows itself`,
+          message: `Trail follows itself`,
           rule: 'no-self-follow',
           trailId: id,
         });
       } else if (!topo.has(followId)) {
         issues.push({
           message: `Follows "${followId}" which is not in the topo`,
-          rule: 'follows-exist',
+          rule: 'follow-exists',
+          trailId: id,
+        });
+      }
+    }
+  }
+  issues.push(...detectFollowCycles(trails));
+  return issues;
+};
+
+const checkServices = (
+  trails: ReadonlyMap<string, AnyTrail>,
+  topo: Topo
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+
+  for (const [id, trail] of trails) {
+    for (const declaredService of trail.services) {
+      if (!topo.hasService(declaredService.id)) {
+        issues.push({
+          message: `Service "${declaredService.id}" is not in the topo`,
+          rule: 'service-exists',
           trailId: id,
         });
       }
     }
   }
+
   return issues;
 };
 
@@ -66,7 +147,7 @@ const checkOneExample = (
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   const result = validateInput(inputSchema as AnyTrail['input'], example.input);
-  if (result.isErr() && example.error === undefined) {
+  if (result.isErr() && example.error !== 'ValidationError') {
     issues.push({
       message: `Example "${example.name}" input does not parse against schema`,
       rule: 'example-input-valid',
@@ -125,13 +206,14 @@ const checkEventOrigins = (
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follows references, example inputs, event origins, and output
+ * Checks follow 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 const validateTopo = (topo: Topo): Result<void, ValidationError> => {
   const issues = [
-    ...checkFollows(topo.hikes, topo),
+    ...checkFollows(topo.trails, topo),
+    ...checkServices(topo.trails, topo),
     ...checkExamples(topo.trails),
     ...checkEventOrigins(topo.events, topo),
   ];