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

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,7 +2,12 @@ import type { z } from 'zod';
 
 import type { FieldOverride } from './derive.js';
 import type { Result } from './result.js';
-import type { Implementation, TrailContext } from './types.js';
+import type { AnyService } from './service.js';
+import type {
+  Implementation,
+  PermitRequirement,
+  TrailContext,
+} from './types.js';
 
 // ---------------------------------------------------------------------------
 // Trail example
@@ -56,6 +61,10 @@ 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;
+  /** Auth requirement: scopes object, 'public', or omitted (undeclared) */
+  readonly permit?: PermitRequirement | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -68,13 +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'
+  '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 +133,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 +148,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 ?? [])]),
   });
 }
 

package/src/types.ts

@@ -17,6 +17,11 @@ export type FollowFn = <O>(
   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
+) => T;
+
 /** Callback for reporting progress from long-running trails */
 export type ProgressCallback = (event: ProgressEvent) => void;
 
@@ -41,16 +46,42 @@ 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;
   readonly cwd?: string | undefined;
   readonly env?: Record<string, string | undefined> | undefined;
   readonly extensions?: Readonly<Record<string, unknown>> | undefined;
+  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/src/validate-topo.ts

@@ -113,6 +113,27 @@ const checkFollows = (
   return issues;
 };
 
+const checkServices = (
+  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)) {
+        issues.push({
+          message: `Service "${declaredService.id}" is not in the topo`,
+          rule: 'service-exists',
+          trailId: id,
+        });
+      }
+    }
+  }
+
+  return issues;
+};
+
 const checkOneExample = (
   id: string,
   example: {
@@ -192,6 +213,7 @@ const checkEventOrigins = (
 export const validateTopo = (topo: Topo): Result<void, ValidationError> => {
   const issues = [
     ...checkFollows(topo.trails, topo),
+    ...checkServices(topo.trails, topo),
     ...checkExamples(topo.trails),
     ...checkEventOrigins(topo.events, topo),
   ];

package/src/validation.ts

@@ -94,6 +94,34 @@ export const validateOutput = <T>(
 // Zod → JSON Schema (public API)
 // ---------------------------------------------------------------------------
 
+/**
+ * Sentinel indicating a dynamic default that should be omitted from schema
+ * exports. Zod v4 wraps all defaults in getters; dynamic ones (functions)
+ * produce new values on each access. We detect this by reading the getter
+ * twice and comparing with `Object.is`. If values differ, the default is
+ * dynamic and we cache this sentinel to skip it in future calls.
+ */
+const DYNAMIC_DEFAULT = Symbol('DYNAMIC_DEFAULT');
+const defaultValueCache = new WeakMap<object, unknown>();
+
+/** Read a Zod v4 default getter twice and decide if it's stable.
+ *  Uses Object.is for primitives and JSON.stringify for objects/arrays. */
+const resolveDefault = (def: Record<string, unknown>): unknown => {
+  try {
+    const a = def['defaultValue'];
+    const b = def['defaultValue'];
+    if (Object.is(a, b)) {
+      return a;
+    }
+    // Object/array defaults produce new references each call but may
+    // still be structurally identical (e.g. `() => ({ key: 'val' })`).
+    return JSON.stringify(a) === JSON.stringify(b) ? a : DYNAMIC_DEFAULT;
+  } catch {
+    // BigInt, circular refs, or other non-serializable defaults
+    return DYNAMIC_DEFAULT;
+  }
+};
+
 /**
  * Convert common Zod types to a JSON Schema object.
  *
@@ -142,9 +170,13 @@ export const zodToJsonSchema: JsonSchemaConverter = (
     default: (value) => {
       const inner = value._zod.def['innerType'] as unknown as z.ZodType;
       const innerSchema = zodToJsonSchema(inner);
-      const rawDefault = value._zod.def['defaultValue'];
-      innerSchema['default'] =
-        typeof rawDefault === 'function' ? rawDefault() : rawDefault;
+      if (!defaultValueCache.has(value._zod.def)) {
+        defaultValueCache.set(value._zod.def, resolveDefault(value._zod.def));
+      }
+      const cached = defaultValueCache.get(value._zod.def);
+      if (cached !== DYNAMIC_DEFAULT) {
+        innerSchema['default'] = cached;
+      }
       return innerSchema;
     },
     enum: (value) => {

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/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"}