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

package/src/execute.ts

@@ -8,14 +8,21 @@
 
 import type { AnyTrail } from './trail.js';
 import type { Layer } from './layer.js';
-import type { TrailContext } from './types.js';
+import type { 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 { resolveServices } from './service-config.js';
 import { validateInput } from './validation.js';
 
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
@@ -23,14 +30,20 @@ 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;
+  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  readonly configValues?:
+    | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
 }
 
@@ -49,9 +62,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 +73,42 @@ 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 prepareContext = async (
+  trail: AnyTrail,
+  options?: ExecuteTrailOptions
+): Promise<Result<TrailContext, Error>> => {
+  const baseCtx = await resolveContext(options);
+  return await resolveServices(
+    trail,
+    baseCtx,
+    options?.services,
+    options?.configValues
+  );
+};
+
+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 +132,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,35 @@ export type { ErrorCategory } from './errors.js';
 export type {
   Implementation,
   TrailContext,
+  TrailContextInit,
   FollowFn,
+  BasePermit,
+  PermitRequirement,
   ProgressCallback,
   ProgressEvent,
   Logger,
+  ServiceLookup,
 } from './types.js';
+export { SURFACE_KEY } 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-config.ts

@@ -0,0 +1,354 @@
+/**
+ * Service resolution pipeline.
+ *
+ * Extracted from execute.ts to keep both modules under the 400 LOC ceiling.
+ * Handles config validation, singleton caching, concurrent-creation dedup,
+ * and the full resolve-or-create flow for declared services.
+ */
+
+import type {
+  AnyService,
+  ServiceContext,
+  ServiceOverrideMap,
+} from './service.js';
+import type { AnyTrail } from './trail.js';
+import type { TrailContext } from './types.js';
+
+import { InternalError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+import { createServiceLookup } from './service.js';
+
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
+type ConfigValues = Readonly<Record<string, Record<string, unknown>>>;
+
+// ---------------------------------------------------------------------------
+// Singleton caches
+// ---------------------------------------------------------------------------
+
+const singletonServices = new WeakMap<AnyService, Map<string, unknown>>();
+
+/** In-flight service creation promises, keyed by service x context. */
+const pendingCreations = new WeakMap<
+  AnyService,
+  Map<string, Promise<Result<unknown, Error>>>
+>();
+
+// ---------------------------------------------------------------------------
+// Context helpers
+// ---------------------------------------------------------------------------
+
+const toServiceContext = (
+  ctx: TrailContext,
+  config?: unknown
+): ServiceContext => ({
+  config,
+  cwd: ctx.cwd,
+  env: ctx.env,
+  workspaceRoot: ctx.workspaceRoot,
+});
+
+const toServiceContextKey = (ctx: ServiceContext): string =>
+  JSON.stringify({
+    config: ctx.config,
+    cwd: ctx.cwd,
+    env: Object.entries(ctx.env ?? {}).toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    ),
+    workspaceRoot: ctx.workspaceRoot,
+  });
+
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+
+/** Validate and resolve a service's config from the provided configValues map. */
+const resolveServiceConfig = (
+  declaredService: AnyService,
+  configValues?: ConfigValues
+): Result<unknown, Error> => {
+  if (declaredService.config === undefined) {
+    return Result.ok();
+  }
+  const raw = configValues?.[declaredService.id];
+  if (raw === undefined) {
+    return Result.err(
+      new ValidationError(
+        `Service "${declaredService.id}" declares a config schema but no config was provided`
+      )
+    );
+  }
+  const parsed = declaredService.config.safeParse(raw);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError(
+        `Service "${declaredService.id}" config validation failed: ${parsed.error.message}`
+      )
+    );
+  }
+  return Result.ok(parsed.data);
+};
+
+// ---------------------------------------------------------------------------
+// Override / cache lookups
+// ---------------------------------------------------------------------------
+
+const hasOwnServiceOverride = (
+  overrides: ServiceOverrideMap | undefined,
+  id: string
+): overrides is ServiceOverrideMap =>
+  overrides !== undefined && Object.hasOwn(overrides, 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 getOverrideOrExtension = (
+  ctx: TrailContext,
+  overrides: ServiceOverrideMap | undefined,
+  declaredService: AnyService
+): Result<unknown, Error> | undefined =>
+  getProvidedService(ctx, overrides, declaredService, toServiceContext(ctx));
+
+type ConfigAwareResolution =
+  | Result<{ readonly kind: 'provided'; readonly value: unknown }, Error>
+  | Result<
+      { readonly kind: 'context'; readonly serviceContext: ServiceContext },
+      Error
+    >;
+
+const resolveConfigAwareProvidedService = (
+  ctx: TrailContext,
+  declaredService: AnyService,
+  configValues: ConfigValues | undefined
+): ConfigAwareResolution => {
+  const configResult = resolveServiceConfig(declaredService, configValues);
+  if (configResult.isErr()) {
+    return configResult;
+  }
+
+  const serviceContext = toServiceContext(ctx, configResult.value);
+  const provided = getProvidedService(
+    ctx,
+    undefined,
+    declaredService,
+    serviceContext
+  );
+
+  return provided
+    ? Result.ok({ kind: 'provided', value: provided.unwrap() })
+    : Result.ok({ kind: 'context', serviceContext });
+};
+
+// ---------------------------------------------------------------------------
+// Instance creation
+// ---------------------------------------------------------------------------
+
+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 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 x 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);
+  }
+};
+
+/** Validate config and resolve a single declared service. */
+const resolveDeclaredService = async (
+  declaredService: AnyService,
+  ctx: TrailContext,
+  overrides: ServiceOverrideMap | undefined,
+  configValues: ConfigValues | undefined
+): Promise<Result<unknown, Error>> => {
+  // Check overrides/extensions first — skip config validation entirely when
+  // a service instance is already provided.
+  const overrideOrExtension = getOverrideOrExtension(
+    ctx,
+    overrides,
+    declaredService
+  );
+  if (overrideOrExtension !== undefined) {
+    return overrideOrExtension;
+  }
+
+  // Resolve config before consulting the singleton cache so config-aware
+  // services use the same canonical context for cache reads and writes.
+  const configAwareService = resolveConfigAwareProvidedService(
+    ctx,
+    declaredService,
+    configValues
+  );
+  if (configAwareService.isErr()) {
+    return configAwareService;
+  }
+
+  // No provided instance — create via factory.
+  const resolved = configAwareService.unwrap();
+  if (resolved.kind === 'provided') {
+    return Result.ok(resolved.value);
+  }
+
+  return await createServiceInstance(declaredService, resolved.serviceContext);
+};
+
+// ---------------------------------------------------------------------------
+// Full trail service resolution
+// ---------------------------------------------------------------------------
+
+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;
+};
+
+/**
+ * Resolve all declared services for a trail.
+ *
+ * Validates per-service config, checks overrides and caches, and creates
+ * new instances as needed. Returns an enriched context with all service
+ * instances injected into extensions.
+ */
+export const resolveServices = async (
+  trail: AnyTrail,
+  ctx: TrailContext,
+  overrides?: ServiceOverrideMap,
+  configValues?: ConfigValues
+): Promise<Result<TrailContext, Error>> => {
+  if (trail.services.length === 0) {
+    return Result.ok(ctx);
+  }
+
+  const resolvedServices: Record<string, unknown> = {};
+
+  for (const declaredService of trail.services) {
+    const resolved = await resolveDeclaredService(
+      declaredService,
+      ctx,
+      overrides,
+      configValues
+    );
+    if (resolved.isErr()) {
+      return resolved;
+    }
+    resolvedServices[declaredService.id] = resolved.unwrap();
+  }
+
+  return Result.ok(withResolvedServices(ctx, resolvedServices));
+};

package/src/service.ts

@@ -0,0 +1,145 @@
+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. When a service declares a `config` schema,
+ * the validated config is passed as `svc.config`.
+ */
+export type ServiceContext<C = unknown> = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+> & {
+  readonly config: C;
+};
+
+/**
+ * Everything needed to describe a service before a factory is introduced.
+ *
+ * When `config` is a Zod schema, the `create` callback receives
+ * `ServiceContext<C>` with the validated config value.
+ */
+export interface ServiceSpec<T, C = unknown> {
+  /** Create the service instance from stable process-scoped context. */
+  readonly create: (
+    svc: ServiceContext<C>
+  ) => Result<T, Error> | Promise<Result<T, Error>>;
+  /** Config schema — when present, config is validated and passed to `create`. */
+  readonly config?: z.ZodType<C> | 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;
+};