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

package/src/topo.ts

@@ -3,9 +3,9 @@
  */
 
 import { ValidationError } from './errors.js';
-import type { AnyEvent } from './event.js';
-import type { AnyService } from './service.js';
-import { isService } from './service.js';
+import type { AnySignal } from './event.js';
+import type { AnyProvision } from './provision.js';
+import { isProvision } from './provision.js';
 import type { AnyTrail } from './trail.js';
 
 // ---------------------------------------------------------------------------
@@ -15,33 +15,33 @@ import type { AnyTrail } from './trail.js';
 export interface Topo {
   readonly name: string;
   readonly trails: ReadonlyMap<string, AnyTrail>;
-  readonly events: ReadonlyMap<string, AnyEvent>;
-  readonly services: ReadonlyMap<string, AnyService>;
+  readonly signals: ReadonlyMap<string, AnySignal>;
+  readonly provisions: ReadonlyMap<string, AnyProvision>;
   readonly count: number;
-  readonly serviceCount: number;
+  readonly provisionCount: number;
   get(id: string): AnyTrail | undefined;
-  getService(id: string): AnyService | undefined;
+  getProvision(id: string): AnyProvision | undefined;
   has(id: string): boolean;
-  hasService(id: string): boolean;
+  hasProvision(id: string): boolean;
   ids(): string[];
-  serviceIds(): string[];
+  provisionIds(): string[];
   list(): AnyTrail[];
-  listEvents(): AnyEvent[];
-  listServices(): AnyService[];
+  listSignals(): AnySignal[];
+  listProvisions(): AnyProvision[];
 }
 
 // ---------------------------------------------------------------------------
 // Kind discriminant check
 // ---------------------------------------------------------------------------
 
-type Registrable = AnyTrail | AnyEvent | AnyService;
+type Registrable = AnyTrail | AnySignal | AnyProvision;
 
 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 === 'event';
+  return kind === 'trail' || kind === 'signal';
 };
 
 // ---------------------------------------------------------------------------
@@ -51,24 +51,22 @@ const isRegistrable = (value: unknown): value is Registrable => {
 const createTopo = (
   name: string,
   trails: ReadonlyMap<string, AnyTrail>,
-  events: ReadonlyMap<string, AnyEvent>,
-  services: ReadonlyMap<string, AnyService>
+  signals: ReadonlyMap<string, AnySignal>,
+  provisions: ReadonlyMap<string, AnyProvision>
 ): Topo => ({
   count: trails.size,
-  events,
   get(id: string): AnyTrail | undefined {
     return trails.get(id);
   },
-  getService(id: string): AnyService | undefined {
-    return services.get(id);
+  getProvision(id: string): AnyProvision | undefined {
+    return provisions.get(id);
   },
   has(id: string): boolean {
     return trails.has(id);
   },
-  hasService(id: string): boolean {
-    return services.has(id);
+  hasProvision(id: string): boolean {
+    return provisions.has(id);
   },
-
   ids(): string[] {
     return [...trails.keys()];
   },
@@ -76,21 +74,22 @@ const createTopo = (
   list(): AnyTrail[] {
     return [...trails.values()];
   },
-
-  listEvents(): AnyEvent[] {
-    return [...events.values()];
+  listProvisions(): AnyProvision[] {
+    return [...provisions.values()];
   },
-  listServices(): AnyService[] {
-    return [...services.values()];
+
+  listSignals(): AnySignal[] {
+    return [...signals.values()];
   },
 
   name,
-  serviceCount: services.size,
-  serviceIds(): string[] {
-    return [...services.keys()];
-  },
+  provisionCount: provisions.size,
 
-  services,
+  provisionIds(): string[] {
+    return [...provisions.keys()];
+  },
+  provisions,
+  signals,
   trails,
 });
 
@@ -102,22 +101,22 @@ const createTopo = (
 const register = (
   value: Registrable,
   trails: Map<string, AnyTrail>,
-  events: Map<string, AnyEvent>,
-  services: Map<string, AnyService>
+  signals: Map<string, AnySignal>,
+  provisions: Map<string, AnyProvision>
 ): void => {
   const { id } = value as { id: string };
   const registrars: Record<string, () => void> = {
-    event: () => {
-      if (events.has(id)) {
-        throw new ValidationError(`Duplicate event ID: "${id}"`);
+    provision: () => {
+      if (provisions.has(id)) {
+        throw new ValidationError(`Duplicate provision ID: "${id}"`);
       }
-      events.set(id, value as AnyEvent);
+      provisions.set(id, value as AnyProvision);
     },
-    service: () => {
-      if (services.has(id)) {
-        throw new ValidationError(`Duplicate service ID: "${id}"`);
+    signal: () => {
+      if (signals.has(id)) {
+        throw new ValidationError(`Duplicate signal ID: "${id}"`);
       }
-      services.set(id, value as AnyService);
+      signals.set(id, value as AnySignal);
     },
     trail: () => {
       if (trails.has(id)) {
@@ -129,20 +128,43 @@ const register = (
   registrars[value.kind]?.();
 };
 
+const markUniqueObject = (
+  value: unknown,
+  seenValues: WeakSet<object>
+): boolean => {
+  if (typeof value !== 'object' || value === null) {
+    return true;
+  }
+  if (seenValues.has(value)) {
+    return false;
+  }
+  seenValues.add(value);
+  return true;
+};
+
+const registerModuleValue = (
+  value: unknown,
+  trails: Map<string, AnyTrail>,
+  signals: Map<string, AnySignal>,
+  provisions: Map<string, AnyProvision>
+): void => {
+  if (isProvision(value) || isRegistrable(value)) {
+    register(value, trails, signals, provisions);
+  }
+};
+
 const registerModuleValues = (
   mod: Record<string, unknown>,
   trails: Map<string, AnyTrail>,
-  events: Map<string, AnyEvent>,
-  services: Map<string, AnyService>
+  signals: Map<string, AnySignal>,
+  provisions: Map<string, AnyProvision>
 ): void => {
+  const seenValues = new WeakSet<object>();
   for (const value of Object.values(mod)) {
-    if (isService(value)) {
-      register(value, trails, events, services);
+    if (!markUniqueObject(value, seenValues)) {
       continue;
     }
-    if (isRegistrable(value)) {
-      register(value, trails, events, services);
-    }
+    registerModuleValue(value, trails, signals, provisions);
   }
 };
 
@@ -151,12 +173,12 @@ export const topo = (
   ...modules: Record<string, unknown>[]
 ): Topo => {
   const trails = new Map<string, AnyTrail>();
-  const events = new Map<string, AnyEvent>();
-  const services = new Map<string, AnyService>();
+  const signals = new Map<string, AnySignal>();
+  const provisions = new Map<string, AnyProvision>();
 
   for (const mod of modules) {
-    registerModuleValues(mod, trails, events, services);
+    registerModuleValues(mod, trails, signals, provisions);
   }
 
-  return createTopo(name, trails, events, services);
+  return createTopo(name, trails, signals, provisions);
 };

package/src/trail.ts

@@ -2,7 +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 { AnyProvision } from './provision.js';
 import type {
   Implementation,
   PermitRequirement,
@@ -44,7 +44,7 @@ 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 run: Implementation<I, O>;
+  readonly blaze: Implementation<I, O>;
   /** Human-readable description */
   readonly description?: string | undefined;
   /** Named examples for docs and testing */
@@ -53,16 +53,16 @@ export interface TrailSpec<I, O> {
   readonly intent?: 'read' | 'write' | 'destroy' | undefined;
   /** Trail is idempotent (safe to retry) */
   readonly idempotent?: boolean | undefined;
-  /** Arbitrary metadata for tooling and filtering */
-  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+  /** Arbitrary meta for tooling and filtering */
+  readonly meta?: 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;
+  /** IDs of downstream trails this trail may invoke via ctx.cross() */
+  readonly crosses?: readonly string[] | undefined;
+  /** Provisions this trail may access via provision.from(ctx) */
+  readonly provisions?: readonly AnyProvision[] | undefined;
   /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
   readonly permit?: PermitRequirement | undefined;
 }
@@ -77,15 +77,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' | 'services'
+  'blaze' | 'crosses' | 'intent' | 'provisions'
 > {
   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[];
+  readonly blaze: Implementation<I, O>;
+  /** IDs of downstream trails this trail may invoke via ctx.cross() (always present, default []) */
+  readonly crosses: readonly string[];
+  /** Provisions this trail may access via provision.from(ctx) (always present, default []) */
+  readonly provisions: readonly AnyProvision[];
   /** What this trail does to the world (always present, default 'write') */
   readonly intent: Intent;
 }
@@ -105,14 +105,14 @@ export interface Trail<I, O> extends Omit<
  * // ID as first argument (recommended for human authoring)
  * const show = trail("entity.show", {
  *   input: z.object({ name: z.string() }),
- *   run: (input) => Result.ok(entity),
+ *   blaze: (input) => Result.ok(entity),
  * });
  *
  * // Full spec object (for programmatic generation)
  * const show = trail({
  *   id: "entity.show",
  *   input: z.object({ name: z.string() }),
- *   run: (input) => Result.ok(entity),
+ *   blaze: (input) => Result.ok(entity),
  * });
  * ```
  */
@@ -134,21 +134,22 @@ export function trail<I, O>(
   }
 
   const {
-    run,
-    follow: rawFollow,
+    blaze,
+    crosses: rawCrosses,
     intent: rawIntent,
-    services: rawServices,
+    provisions: rawProvisions,
     ...spec
   } = resolved.spec;
+  const provisions = Object.freeze([...(rawProvisions ?? [])]);
 
   return Object.freeze({
     ...spec,
-    follow: Object.freeze([...(rawFollow ?? [])]),
+    blaze: async (input: I, ctx: TrailContext) => await blaze(input, ctx),
+    crosses: Object.freeze([...(rawCrosses ?? [])]),
     id: resolved.id,
     intent: rawIntent ?? 'write',
     kind: 'trail' as const,
-    run: async (input: I, ctx: TrailContext) => await run(input, ctx),
-    services: Object.freeze([...(rawServices ?? [])]),
+    provisions,
   });
 }
 

package/src/types.ts

@@ -12,14 +12,14 @@ export type Implementation<I, O> = (
 ) => Result<O, Error> | Promise<Result<O, Error>>;
 
 /** Invoke another trail by id — used for trail composition */
-export type FollowFn = <O>(
+export type CrossFn = <O>(
   id: string,
   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
+/** Resolve a provision instance from the current trail context. */
+export type ProvisionLookup = <T = unknown>(
+  provisionOrId: { readonly id: string } | string
 ) => T;
 
 /** Callback for reporting progress from long-running trails */
@@ -46,8 +46,8 @@ 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;
+/** Context extension key for the invoking trailhead name. */
+export const TRAILHEAD_KEY = '__trails_trailhead' as const;
 
 /** Minimal permit shape available on TrailContext. Permits extends this. */
 export interface BasePermit {
@@ -58,8 +58,8 @@ export interface BasePermit {
 /** Runtime context threaded through every trail execution */
 export interface TrailContext {
   readonly requestId: string;
-  readonly signal: AbortSignal;
-  readonly follow?: FollowFn | undefined;
+  readonly abortSignal: AbortSignal;
+  readonly cross?: CrossFn | undefined;
   readonly permit?: BasePermit;
   readonly workspaceRoot?: string | undefined;
   readonly logger?: Logger | undefined;
@@ -67,7 +67,7 @@ export interface TrailContext {
   readonly cwd?: string | undefined;
   readonly env?: Record<string, string | undefined> | undefined;
   readonly extensions?: Readonly<Record<string, unknown>> | undefined;
-  readonly service?: ServiceLookup | undefined;
+  readonly provision?: ProvisionLookup | undefined;
 }
 
 /**
@@ -82,6 +82,6 @@ export type PermitRequirement =
   | 'public';
 
 /** Input shape used to seed a runtime TrailContext before resolution. */
-export type TrailContextInit = Omit<TrailContext, 'service'> & {
-  readonly service?: ServiceLookup | undefined;
+export type TrailContextInit = Omit<TrailContext, 'provision'> & {
+  readonly provision?: ProvisionLookup | undefined;
 };

package/src/validate-established-topo.ts

@@ -0,0 +1,63 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import { validateEstablishedTopo as validateDraftFreeTopo } from './draft.js';
+import type { TopoIssue } from './validate-topo.js';
+import { validateTopo } from './validate-topo.js';
+
+const PROJECTION_BLOCKING_RULES = new Set([
+  'cross-cycle',
+  'cross-exists',
+  'no-self-cross',
+  'provision-exists',
+  'signal-origin-exists',
+]);
+
+const keepProjectionBlockingIssues = (
+  result: ReturnType<typeof validateTopo>
+) => {
+  if (result.isOk()) {
+    return result;
+  }
+
+  const issues = (
+    result.error.context as { issues?: readonly TopoIssue[] } | undefined
+  )?.issues;
+  const remainingIssues = issues?.filter((issue) =>
+    PROJECTION_BLOCKING_RULES.has(issue.rule)
+  );
+
+  if (remainingIssues === undefined || remainingIssues.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Topo validation failed with ${remainingIssues.length} issue(s)`,
+      {
+        cause: result.error,
+        context: { issues: remainingIssues },
+      }
+    )
+  );
+};
+
+/**
+ * Validate that a topo is ready for established outputs.
+ *
+ * Established surfaces still require the authored graph to be structurally
+ * valid, and they must also reject any remaining draft state.
+ */
+export const validateEstablishedTopo = (topo: Topo) => {
+  const structural = keepProjectionBlockingIssues(validateTopo(topo));
+  if (structural.isErr()) {
+    return structural;
+  }
+
+  const established = validateDraftFreeTopo(topo);
+  if (established.isErr()) {
+    return established;
+  }
+
+  return Result.ok();
+};

package/src/validate-topo.ts

@@ -1,13 +1,14 @@
 /**
  * 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 { isDraftId } from './draft.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 +32,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 +41,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 +52,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 +70,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 +88,47 @@ 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) && !isDraftId(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) &&
+        !isDraftId(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 +181,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)) {
+      if (!topo.has(originId) && !isDraftId(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 +210,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/draft.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-store.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-established-topo.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/internal/topo-saves.ts","./src/internal/topo-store-read.ts","./src/internal/topo-store.ts","./src/internal/trails-db.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"}