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

package/src/validate-topo.ts

@@ -1,13 +1,13 @@
 /**
  * Structural validation for a Topo graph.
  *
- * Checks trail follow references, example input validity, event origin
+ * Checks trail crossing 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 { AnySignal } from './event.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import type { AnyTrail } from './trail.js';
@@ -31,8 +31,8 @@ const WHITE = 0;
 const GRAY = 1;
 const BLACK = 2;
 
-/** Build an adjacency list and initial color map from trails with follow. */
-const buildFollowGraph = (
+/** Build an adjacency list and initial color map from trails with crossings. */
+const buildCrossGraph = (
   trails: ReadonlyMap<string, AnyTrail>
 ): {
   graph: Map<string, readonly string[]>;
@@ -40,8 +40,8 @@ const buildFollowGraph = (
 } => {
   const graph = new Map<string, readonly string[]>();
   for (const [id, t] of trails) {
-    if (t.follow.length > 0) {
-      graph.set(id, t.follow);
+    if (t.crosses.length > 0) {
+      graph.set(id, t.crosses);
     }
   }
   const color = new Map<string, number>();
@@ -51,12 +51,12 @@ const buildFollowGraph = (
   return { color, graph };
 };
 
-/** Detect multi-node cycles in the trail follow graph via DFS. */
-const detectFollowCycles = (
+/** Detect multi-node cycles in the trail crossing graph via DFS. */
+const detectCrossCycles = (
   trails: ReadonlyMap<string, AnyTrail>
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
-  const { color, graph } = buildFollowGraph(trails);
+  const { color, graph } = buildCrossGraph(trails);
 
   const dfs = (node: string, path: string[]): void => {
     color.set(node, GRAY);
@@ -69,7 +69,7 @@ const detectFollowCycles = (
         const cycle = [...path.slice(path.indexOf(next)), next];
         issues.push({
           message: `Cycle detected: ${cycle.join(' → ')}`,
-          rule: 'follow-cycle',
+          rule: 'cross-cycle',
           trailId: next,
         });
       } else if (c === WHITE) {
@@ -87,44 +87,44 @@ const detectFollowCycles = (
   return issues;
 };
 
-const checkFollows = (
+const checkCrosses = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
   for (const [id, trail] of trails) {
-    for (const followId of trail.follow) {
-      if (followId === id) {
+    for (const crossedId of trail.crosses) {
+      if (crossedId === id) {
         issues.push({
-          message: `Trail follows itself`,
-          rule: 'no-self-follow',
+          message: `Trail crosses itself`,
+          rule: 'no-self-cross',
           trailId: id,
         });
-      } else if (!topo.has(followId)) {
+      } else if (!topo.has(crossedId)) {
         issues.push({
-          message: `Follows "${followId}" which is not in the topo`,
-          rule: 'follow-exists',
+          message: `Crosses "${crossedId}" which is not in the topo`,
+          rule: 'cross-exists',
           trailId: id,
         });
       }
     }
   }
-  issues.push(...detectFollowCycles(trails));
+  issues.push(...detectCrossCycles(trails));
   return issues;
 };
 
-const checkServices = (
+const checkProvisions = (
   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)) {
+    for (const declaredProvision of trail.provisions) {
+      if (!topo.hasProvision(declaredProvision.id)) {
         issues.push({
-          message: `Service "${declaredService.id}" is not in the topo`,
-          rule: 'service-exists',
+          message: `Provision "${declaredProvision.id}" is not in the topo`,
+          rule: 'provision-exists',
           trailId: id,
         });
       }
@@ -177,20 +177,20 @@ const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
   return issues;
 };
 
-const checkEventOrigins = (
-  events: ReadonlyMap<string, AnyEvent>,
+const checkSignalOrigins = (
+  signals: ReadonlyMap<string, AnySignal>,
   topo: Topo
 ): TopoIssue[] => {
   const issues: TopoIssue[] = [];
-  for (const [id, evt] of events) {
+  for (const [id, evt] of signals) {
     if (!evt.from) {
       continue;
     }
     for (const originId of evt.from) {
       if (!topo.has(originId)) {
         issues.push({
-          message: `Event origin "${originId}" is not in the topo`,
-          rule: 'event-origin-exists',
+          message: `Signal origin "${originId}" is not in the topo`,
+          rule: 'signal-origin-exists',
           trailId: id,
         });
       }
@@ -206,16 +206,16 @@ const checkEventOrigins = (
 /**
  * Validate the structural integrity of a Topo graph.
  *
- * Checks follow references, example inputs, event origins, and output
+ * Checks crossing 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.trails, topo),
-    ...checkServices(topo.trails, topo),
+    ...checkCrosses(topo.trails, topo),
+    ...checkProvisions(topo.trails, topo),
     ...checkExamples(topo.trails),
-    ...checkEventOrigins(topo.events, topo),
+    ...checkSignalOrigins(topo.signals, topo),
   ];
 
   if (issues.length === 0) {

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-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"}
+{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/gate.ts","./src/guards.ts","./src/index.ts","./src/path-security.ts","./src/provision-config.ts","./src/provision.ts","./src/resilience.ts","./src/result.ts","./src/run.ts","./src/serialization.ts","./src/signal.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"}

package/src/service.ts

@@ -1,145 +0,0 @@
-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;
-};