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

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

@@ -7,23 +7,29 @@ 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.
+ * full per-request TrailContext. When a service declares a `config` schema,
+ * the validated config is passed as `svc.config`.
  */
-export type ServiceContext = Pick<
+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> {
+export interface ServiceSpec<T, C = unknown> {
   /** Create the service instance from stable process-scoped context. */
   readonly create: (
-    svc: ServiceContext
+    svc: ServiceContext<C>
   ) => Result<T, Error> | Promise<Result<T, Error>>;
-  /** Reserved config schema for follow-up config composition work. */
-  readonly config?: z.ZodType | undefined;
+  /** 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. */

package/src/trail.ts

@@ -3,7 +3,11 @@ 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';
+import type {
+  Implementation,
+  PermitRequirement,
+  TrailContext,
+} from './types.js';
 
 // ---------------------------------------------------------------------------
 // Trail example
@@ -59,6 +63,8 @@ export interface TrailSpec<I, O> {
   readonly follow?: readonly string[] | undefined;
   /** Services this trail may access via service.from(ctx) */
   readonly services?: readonly AnyService[] | undefined;
+  /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
+  readonly permit?: PermitRequirement | undefined;
 }
 
 // ---------------------------------------------------------------------------

package/src/types.ts

@@ -46,12 +46,21 @@ export interface Logger {
   child(context: Record<string, unknown>): Logger;
 }
 
+/** Context extension key for the invoking surface name. */
+export const SURFACE_KEY = '__trails_surface' as const;
+
+/** Minimal permit shape available on TrailContext. Permits extends this. */
+export interface BasePermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
 /** 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 permit?: BasePermit;
   readonly workspaceRoot?: string | undefined;
   readonly logger?: Logger | undefined;
   readonly progress?: ProgressCallback | undefined;
@@ -61,6 +70,17 @@ export interface TrailContext {
   readonly service?: ServiceLookup | undefined;
 }
 
+/**
+ * Permit requirement declared on a trail spec.
+ *
+ * A scopes object means the trail requires a permit with those scopes.
+ * `'public'` means the trail has explicitly opted out of auth.
+ * Omitting the field entirely means the trail hasn't declared an auth posture.
+ */
+export type PermitRequirement =
+  | { readonly scopes: readonly string[] }
+  | 'public';
+
 /** Input shape used to seed a runtime TrailContext before resolution. */
 export type TrailContextInit = Omit<TrailContext, 'service'> & {
   readonly service?: ServiceLookup | undefined;

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/dispatch.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/guards.ts","./src/index.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/service.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}
+{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/dispatch.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/guards.ts","./src/index.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/service-config.ts","./src/service.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}