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

package/src/execute.ts

@@ -8,14 +8,24 @@
 
 import type { AnyTrail } from './trail.js';
 import type { Layer } from './layer.js';
-import type { TrailContext } from './types.js';
+import type {
+  AnyService,
+  ServiceContext,
+  ServiceOverrideMap,
+} from './service.js';
+import type { TrailContext, TrailContextInit } from './types.js';
 
 import { composeLayers } from './layer.js';
 import { createTrailContext } from './context.js';
 import { InternalError } from './errors.js';
 import { Result } from './result.js';
+import { createServiceLookup } from './service.js';
 import { validateInput } from './validation.js';
 
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
@@ -23,15 +33,17 @@ import { validateInput } from './validation.js';
 /** Options for executeTrail. */
 export interface ExecuteTrailOptions {
   /** Partial context overrides merged on top of the base context. */
-  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly ctx?: Partial<TrailContextInit> | 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>)
+    | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
+  /** Explicit service instance overrides keyed by service ID. */
+  readonly services?: ServiceOverrideMap | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -49,9 +61,10 @@ export interface ExecuteTrailOptions {
 const resolveContext = async (
   options?: ExecuteTrailOptions
 ): Promise<TrailContext> => {
-  const base = options?.createContext
+  const seed = options?.createContext
     ? await options.createContext()
     : createTrailContext();
+  const base = seed.service ? seed : createTrailContext(seed);
   const withOverrides = options?.ctx
     ? {
         ...base,
@@ -59,9 +72,238 @@ const resolveContext = async (
         extensions: { ...base.extensions, ...options.ctx.extensions },
       }
     : base;
-  return options?.signal
+  const resolved = options?.signal
     ? { ...withOverrides, signal: options.signal }
     : withOverrides;
+  if (
+    options?.ctx?.extensions !== undefined ||
+    resolved.service === undefined
+  ) {
+    const bound = { ...resolved } as MutableTrailContext;
+    bound.service = createServiceLookup(() => bound);
+    return bound;
+  }
+
+  return resolved as TrailContext;
+};
+
+const singletonServices = new WeakMap<AnyService, Map<string, unknown>>();
+
+/** In-flight service creation promises, keyed by service × context. */
+const pendingCreations = new WeakMap<
+  AnyService,
+  Map<string, Promise<Result<unknown, Error>>>
+>();
+
+const hasOwnServiceOverride = (
+  overrides: ServiceOverrideMap | undefined,
+  id: string
+): overrides is ServiceOverrideMap =>
+  overrides !== undefined && Object.hasOwn(overrides, id);
+
+const toServiceContext = (ctx: TrailContext): ServiceContext => ({
+  cwd: ctx.cwd,
+  env: ctx.env,
+  workspaceRoot: ctx.workspaceRoot,
+});
+
+const toServiceContextKey = (ctx: ServiceContext): string =>
+  JSON.stringify({
+    cwd: ctx.cwd,
+    env: Object.entries(ctx.env ?? {}).toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    ),
+    workspaceRoot: ctx.workspaceRoot,
+  });
+
+const toInternalServiceError = (id: string, error: unknown): InternalError => {
+  const cause = error instanceof Error ? error : undefined;
+  const message = cause?.message ?? String(error);
+  return new InternalError(`Service "${id}" failed to resolve: ${message}`, {
+    ...(cause ? { cause } : {}),
+    context: { serviceId: id },
+  });
+};
+
+const getCachedSingletonService = (
+  declaredService: AnyService,
+  serviceContext: ServiceContext
+): { readonly found: boolean; readonly value: unknown } => {
+  const scopedCache = singletonServices.get(declaredService);
+  if (scopedCache === undefined) {
+    return { found: false, value: undefined };
+  }
+
+  const key = toServiceContextKey(serviceContext);
+  if (!scopedCache.has(key)) {
+    return { found: false, value: undefined };
+  }
+
+  return {
+    found: true,
+    value: scopedCache.get(key),
+  };
+};
+
+const getProvidedService = (
+  ctx: TrailContext,
+  overrides: ServiceOverrideMap | undefined,
+  declaredService: AnyService,
+  serviceContext: ServiceContext
+): Result<unknown, Error> | undefined => {
+  const { id } = declaredService;
+  if (hasOwnServiceOverride(overrides, id)) {
+    return Result.ok(overrides[id]);
+  }
+
+  if (Object.hasOwn(ctx.extensions ?? {}, id)) {
+    return Result.ok(ctx.extensions?.[id]);
+  }
+
+  const cached = getCachedSingletonService(declaredService, serviceContext);
+  if (cached.found) {
+    return Result.ok(cached.value);
+  }
+
+  return undefined;
+};
+
+const getSingletonServiceCache = (
+  declaredService: AnyService
+): Map<string, unknown> => {
+  const existing = singletonServices.get(declaredService);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = new Map<string, unknown>();
+  singletonServices.set(declaredService, created);
+  return created;
+};
+
+const doCreateServiceInstance = async (
+  declaredService: AnyService,
+  serviceContext: ServiceContext
+): Promise<Result<unknown, Error>> => {
+  try {
+    const created = await declaredService.create(serviceContext);
+    if (created.isErr()) {
+      return Result.err(created.error);
+    }
+
+    const instance = created.unwrap();
+    getSingletonServiceCache(declaredService).set(
+      toServiceContextKey(serviceContext),
+      instance
+    );
+    return Result.ok(instance);
+  } catch (error: unknown) {
+    return Result.err(toInternalServiceError(declaredService.id, error));
+  }
+};
+
+const trackPendingCreation = (
+  declaredService: AnyService,
+  key: string,
+  promise: Promise<Result<unknown, Error>>
+): void => {
+  const pending = pendingCreations.get(declaredService);
+  if (pending) {
+    pending.set(key, promise);
+  } else {
+    pendingCreations.set(declaredService, new Map([[key, promise]]));
+  }
+};
+
+/**
+ * Deduplicates concurrent creation of the same service singleton.
+ * If a creation is already in flight for this service × context key,
+ * returns the existing promise instead of spawning a second factory call.
+ */
+const createServiceInstance = async (
+  declaredService: AnyService,
+  serviceContext: ServiceContext
+): Promise<Result<unknown, Error>> => {
+  const key = toServiceContextKey(serviceContext);
+  const inflight = pendingCreations.get(declaredService)?.get(key);
+  if (inflight) {
+    return inflight;
+  }
+
+  const promise = doCreateServiceInstance(declaredService, serviceContext);
+  trackPendingCreation(declaredService, key, promise);
+
+  try {
+    return await promise;
+  } finally {
+    pendingCreations.get(declaredService)?.delete(key);
+  }
+};
+
+const resolveServiceInstance = async (
+  declaredService: AnyService,
+  ctx: TrailContext,
+  serviceContext: ServiceContext,
+  overrides?: ServiceOverrideMap
+): Promise<Result<unknown, Error>> =>
+  getProvidedService(ctx, overrides, declaredService, serviceContext) ??
+  (await createServiceInstance(declaredService, serviceContext));
+
+const withResolvedServices = (
+  ctx: TrailContext,
+  resolvedServices: Record<string, unknown>
+): TrailContext => {
+  const extensions = { ...ctx.extensions, ...resolvedServices };
+  const resolvedCtx = { ...ctx, extensions } as MutableTrailContext;
+  resolvedCtx.service = createServiceLookup(() => resolvedCtx);
+  return resolvedCtx;
+};
+
+const resolveServices = async (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  overrides?: ServiceOverrideMap
+): Promise<Result<TrailContext, Error>> => {
+  if (trail.services.length === 0) {
+    return Result.ok(ctx);
+  }
+
+  const resolvedServices: Record<string, unknown> = {};
+  const serviceContext = toServiceContext(ctx);
+
+  for (const declaredService of trail.services) {
+    const resolved = await resolveServiceInstance(
+      declaredService,
+      ctx,
+      serviceContext,
+      overrides
+    );
+    if (resolved.isErr()) {
+      return resolved;
+    }
+
+    resolvedServices[declaredService.id] = resolved.unwrap();
+  }
+
+  return Result.ok(withResolvedServices(ctx, resolvedServices));
+};
+
+const prepareContext = async (
+  trail: AnyTrail,
+  options?: ExecuteTrailOptions
+): Promise<Result<TrailContext, Error>> => {
+  const baseCtx = await resolveContext(options);
+  return await resolveServices(trail, baseCtx, options?.services);
+};
+
+const runTrail = async (
+  trail: AnyTrail,
+  input: unknown,
+  ctx: TrailContext,
+  layers: readonly Layer[]
+): Promise<Result<unknown, Error>> => {
+  const impl = composeLayers([...layers], trail, trail.run);
+  return await impl(input, ctx);
 };
 
 // ---------------------------------------------------------------------------
@@ -85,10 +327,17 @@ export const executeTrail = async (
       return validated;
     }
 
-    const ctx = await resolveContext(options);
-    const layers = options?.layers ?? [];
-    const impl = composeLayers([...layers], trail, trail.run);
-    return await impl(validated.value, ctx);
+    const resolvedCtx = await prepareContext(trail, options);
+    if (resolvedCtx.isErr()) {
+      return resolvedCtx;
+    }
+
+    return await runTrail(
+      trail,
+      validated.value,
+      resolvedCtx.value,
+      options?.layers ?? []
+    );
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     return Result.err(new InternalError(message));

package/src/index.ts

@@ -30,15 +30,32 @@ export type { ErrorCategory } from './errors.js';
 export type {
   Implementation,
   TrailContext,
+  TrailContextInit,
   FollowFn,
   ProgressCallback,
   ProgressEvent,
   Logger,
+  ServiceLookup,
 } from './types.js';
 
 // Context factory
 export { createTrailContext } from './context.js';
 
+// Service
+export {
+  createServiceLookup,
+  findDuplicateServiceId,
+  isService,
+  service,
+} from './service.js';
+export type {
+  AnyService,
+  Service,
+  ServiceContext,
+  ServiceOverrideMap,
+  ServiceSpec,
+} from './service.js';
+
 // Trail
 export { trail } from './trail.js';
 export type {

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,6 +4,8 @@
 
 import { ValidationError } from './errors.js';
 import type { AnyEvent } from './event.js';
+import type { AnyService } from './service.js';
+import { isService } from './service.js';
 import type { AnyTrail } from './trail.js';
 
 // ---------------------------------------------------------------------------
@@ -14,19 +16,25 @@ export interface Topo {
   readonly name: string;
   readonly trails: ReadonlyMap<string, AnyTrail>;
   readonly events: ReadonlyMap<string, AnyEvent>;
+  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;
+  hasService(id: string): boolean;
   ids(): string[];
+  serviceIds(): string[];
   list(): AnyTrail[];
   listEvents(): AnyEvent[];
+  listServices(): AnyService[];
 }
 
 // ---------------------------------------------------------------------------
 // Kind discriminant check
 // ---------------------------------------------------------------------------
 
-type Registrable = AnyTrail | AnyEvent;
+type Registrable = AnyTrail | AnyEvent | AnyService;
 
 const isRegistrable = (value: unknown): value is Registrable => {
   if (typeof value !== 'object' || value === null) {
@@ -43,16 +51,23 @@ const isRegistrable = (value: unknown): value is Registrable => {
 const createTopo = (
   name: string,
   trails: ReadonlyMap<string, AnyTrail>,
-  events: ReadonlyMap<string, AnyEvent>
+  events: ReadonlyMap<string, AnyEvent>,
+  services: ReadonlyMap<string, AnyService>
 ): Topo => ({
   count: trails.size,
   events,
   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);
   },
+  hasService(id: string): boolean {
+    return services.has(id);
+  },
 
   ids(): string[] {
     return [...trails.keys()];
@@ -65,9 +80,17 @@ const createTopo = (
   listEvents(): AnyEvent[] {
     return [...events.values()];
   },
+  listServices(): AnyService[] {
+    return [...services.values()];
+  },
 
   name,
+  serviceCount: services.size,
+  serviceIds(): string[] {
+    return [...services.keys()];
+  },
 
+  services,
   trails,
 });
 
@@ -79,7 +102,8 @@ const createTopo = (
 const register = (
   value: Registrable,
   trails: Map<string, AnyTrail>,
-  events: Map<string, AnyEvent>
+  events: Map<string, AnyEvent>,
+  services: Map<string, AnyService>
 ): void => {
   const { id } = value as { id: string };
   const registrars: Record<string, () => void> = {
@@ -89,6 +113,12 @@ const register = (
       }
       events.set(id, value as AnyEvent);
     },
+    service: () => {
+      if (services.has(id)) {
+        throw new ValidationError(`Duplicate service ID: "${id}"`);
+      }
+      services.set(id, value as AnyService);
+    },
     trail: () => {
       if (trails.has(id)) {
         throw new ValidationError(`Duplicate trail ID: "${id}"`);
@@ -99,20 +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 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, events);
-      }
-    }
+    registerModuleValues(mod, trails, events, services);
   }
 
-  return createTopo(name, trails, 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';
 
 // ---------------------------------------------------------------------------
@@ -56,6 +57,8 @@ export interface TrailSpec<I, O> {
   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;
 }
 
 // ---------------------------------------------------------------------------
@@ -68,13 +71,15 @@ 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>,
-  'run' | 'follow' | 'intent'
+  'run' | 'follow' | 'intent' | 'services'
 > {
   readonly kind: 'trail';
   readonly id: string;
   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;
 }
@@ -122,7 +127,13 @@ export function trail<I, O>(
     throw new TypeError('trail() requires a spec when an id is provided');
   }
 
-  const { run, follow: rawFollow, intent: rawIntent, ...spec } = resolved.spec;
+  const {
+    run,
+    follow: rawFollow,
+    intent: rawIntent,
+    services: rawServices,
+    ...spec
+  } = resolved.spec;
 
   return Object.freeze({
     ...spec,
@@ -131,6 +142,7 @@ export function trail<I, O>(
     intent: rawIntent ?? 'write',
     kind: 'trail' as const,
     run: async (input: I, ctx: TrailContext) => await run(input, ctx),
+    services: Object.freeze([...(rawServices ?? [])]),
   });
 }