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

package/dist/types.d.ts

@@ -33,12 +33,19 @@ export interface Logger {
     fatal(message: string, data?: Record<string, unknown>): void;
     child(context: Record<string, unknown>): Logger;
 }
+/** Context extension key for the invoking surface name. */
+export declare const SURFACE_KEY: "__trails_surface";
+/** 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;
@@ -47,6 +54,16 @@ export interface TrailContext {
     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/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,2 +1,3 @@
-export {};
+/** Context extension key for the invoking surface name. */
+export const SURFACE_KEY = '__trails_surface';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAgDA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,kBAA2B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.12",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/__tests__/service-config.test.ts

@@ -0,0 +1,224 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { executeTrail } from '../execute.js';
+import { Result } from '../result.js';
+import { service } from '../service.js';
+import { trail } from '../trail.js';
+import type { ServiceContext } from '../service.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const nextId = (name: string): string =>
+  `test.svc-config.${name}.${Bun.randomUUIDv7()}`;
+
+const createSingletonConfigTrail = (id: string) => {
+  const captures = { createCalls: 0 };
+  const svc = service(id, {
+    config: z.object({ key: z.string() }),
+    create: (ctx: ServiceContext<{ key: string }>) => {
+      captures.createCalls += 1;
+      return Result.ok({
+        createCall: captures.createCalls,
+        key: ctx.config.key,
+      });
+    },
+  });
+
+  return {
+    captures,
+    trail: trail('svc-config.singleton', {
+      input: z.object({}),
+      output: z.object({ createCall: z.number(), key: z.string() }),
+      run: (_input, ctx) =>
+        Result.ok({
+          createCall: svc.from(ctx).createCall,
+          key: svc.from(ctx).key,
+        }),
+      services: [svc],
+    }),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ServiceContext.config', () => {
+  test('service with config schema receives validated config in svc.config', async () => {
+    const id = nextId('typed-config');
+    let capturedConfig: unknown;
+
+    const db = service(id, {
+      config: z.object({ poolSize: z.number(), url: z.string().url() }),
+      create: (svc: ServiceContext<{ url: string; poolSize: number }>) => {
+        capturedConfig = svc.config;
+        return Result.ok({ connected: true });
+      },
+    });
+
+    const dbTrail = trail('svc-config.typed', {
+      input: z.object({}),
+      output: z.object({ connected: z.boolean() }),
+      run: (_input, ctx) => Result.ok({ connected: db.from(ctx).connected }),
+      services: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { poolSize: 5, url: 'https://example.com' },
+        },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toEqual({ poolSize: 5, url: 'https://example.com' });
+  });
+
+  test('service without config still works — svc.config is undefined', async () => {
+    const id = nextId('no-config');
+    let capturedConfig: unknown = 'sentinel';
+
+    const counter = service(id, {
+      create: (svc) => {
+        capturedConfig = svc.config;
+        return Result.ok(42);
+      },
+    });
+
+    const counterTrail = trail('svc-config.no-config', {
+      input: z.object({}),
+      run: (_input, ctx) => Result.ok({ value: counter.from(ctx) }),
+      services: [counter],
+    });
+
+    const result = await executeTrail(counterTrail, {});
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toBeUndefined();
+  });
+
+  test('config validation failure returns Result.err at service creation time', async () => {
+    const id = nextId('invalid-config');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.invalid', {
+      input: z.object({}),
+      run: () => Result.ok(null),
+      services: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { url: 'not-a-url' },
+        },
+      }
+    );
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('missing configValues for a service with config schema returns Result.err', async () => {
+    const id = nextId('missing-config');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.missing', {
+      input: z.object({}),
+      run: () => Result.ok(null),
+      services: [db],
+    });
+
+    const result = await executeTrail(dbTrail, {});
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('service override bypasses config validation', async () => {
+    const id = nextId('override-bypass');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.override', {
+      input: z.object({}),
+      output: z.object({ value: z.number() }),
+      run: (_input, ctx) => Result.ok({ value: db.from(ctx) as number }),
+      services: [db],
+    });
+
+    // Provide the service via overrides without any configValues — should NOT fail
+    const result = await executeTrail(dbTrail, {}, { services: { [id]: 42 } });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ value: 42 });
+  });
+  test('config values passed through ExecuteTrailOptions.configValues', async () => {
+    const id = nextId('options-config');
+    const captures: unknown[] = [];
+
+    const svc = service(id, {
+      config: z.object({ key: z.string() }),
+      create: (ctx: ServiceContext<{ key: string }>) => {
+        captures.push(ctx.config);
+        return Result.ok({ key: ctx.config.key });
+      },
+    });
+
+    const svcTrail = trail('svc-config.options', {
+      input: z.object({}),
+      output: z.object({ key: z.string() }),
+      run: (_input, ctx) => Result.ok({ key: svc.from(ctx).key }),
+      services: [svc],
+    });
+
+    const result = await executeTrail(
+      svcTrail,
+      {},
+      {
+        configValues: { [id]: { key: 'hello' } },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ key: 'hello' });
+    expect(captures).toEqual([{ key: 'hello' }]);
+  });
+
+  test('config-aware singleton services reuse the cached instance', async () => {
+    const id = nextId('singleton-config');
+    const { captures, trail: singletonTrail } = createSingletonConfigTrail(id);
+    const options = {
+      configValues: { [id]: { key: 'hello' } },
+    };
+    const first = await executeTrail(singletonTrail, {}, options);
+    const second = await executeTrail(singletonTrail, {}, options);
+
+    expect(first.isOk()).toBe(true);
+    expect(second.isOk()).toBe(true);
+    expect(first.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(second.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(captures.createCalls).toBe(1);
+  });
+});

package/src/__tests__/trail-permit.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { PermitRequirement } from '../types';
+
+describe('PermitRequirement type', () => {
+  test('accepts a scopes object', () => {
+    const req: PermitRequirement = { scopes: ['user:write', 'user:read'] };
+    expect(req).toEqual({ scopes: ['user:write', 'user:read'] });
+  });
+
+  test('accepts public literal', () => {
+    const req: PermitRequirement = 'public';
+    expect(req).toBe('public');
+  });
+});
+
+describe('trail() with permit field', () => {
+  test('accepts permit with scopes', () => {
+    const t = trail('user.delete', {
+      input: z.object({ id: z.string() }),
+      intent: 'destroy',
+      permit: { scopes: ['user:write'] },
+      run: (input) => Result.ok({ deleted: input.id }),
+    });
+    expect(t.permit).toEqual({ scopes: ['user:write'] });
+  });
+
+  test('accepts permit: public', () => {
+    const t = trail('health.check', {
+      input: z.object({}),
+      intent: 'read',
+      permit: 'public',
+      run: () => Result.ok({ status: 'ok' }),
+    });
+    expect(t.permit).toBe('public');
+  });
+
+  test('permit is undefined when omitted (backward compatible)', () => {
+    const t = trail('legacy.trail', {
+      input: z.object({}),
+      run: () => Result.ok(),
+    });
+    expect(t.permit).toBeUndefined();
+  });
+
+  test('preserves permit on the frozen Trail object', () => {
+    const t = trail('user.list', {
+      input: z.object({}),
+      intent: 'read',
+      permit: { scopes: ['user:read'] },
+      run: () => Result.ok([]),
+    });
+    expect(Object.isFrozen(t)).toBe(true);
+    expect(t.permit).toEqual({ scopes: ['user:read'] });
+  });
+});

package/src/execute.ts

@@ -8,11 +8,7 @@
 
 import type { AnyTrail } from './trail.js';
 import type { Layer } from './layer.js';
-import type {
-  AnyService,
-  ServiceContext,
-  ServiceOverrideMap,
-} from './service.js';
+import type { ServiceOverrideMap } from './service.js';
 import type { TrailContext, TrailContextInit } from './types.js';
 
 import { composeLayers } from './layer.js';
@@ -20,6 +16,7 @@ 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 = {
@@ -44,6 +41,10 @@ export interface ExecuteTrailOptions {
     | 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -87,213 +88,17 @@ const resolveContext = async (
   return resolved as TrailContext;
 };
 
-const singletonServices = new WeakMap<AnyService, Map<string, unknown>>();
-
-/** In-flight service creation promises, keyed by service × context. */
-const pendingCreations = new WeakMap<
-  AnyService,
-  Map<string, Promise<Result<unknown, Error>>>
->();
-
-const hasOwnServiceOverride = (
-  overrides: ServiceOverrideMap | undefined,
-  id: string
-): overrides is ServiceOverrideMap =>
-  overrides !== undefined && Object.hasOwn(overrides, id);
-
-const toServiceContext = (ctx: TrailContext): ServiceContext => ({
-  cwd: ctx.cwd,
-  env: ctx.env,
-  workspaceRoot: ctx.workspaceRoot,
-});
-
-const toServiceContextKey = (ctx: ServiceContext): string =>
-  JSON.stringify({
-    cwd: ctx.cwd,
-    env: Object.entries(ctx.env ?? {}).toSorted(([left], [right]) =>
-      left.localeCompare(right)
-    ),
-    workspaceRoot: ctx.workspaceRoot,
-  });
-
-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 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 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 × 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);
-  }
-};
-
-const resolveServiceInstance = async (
-  declaredService: AnyService,
-  ctx: TrailContext,
-  serviceContext: ServiceContext,
-  overrides?: ServiceOverrideMap
-): Promise<Result<unknown, Error>> =>
-  getProvidedService(ctx, overrides, declaredService, serviceContext) ??
-  (await createServiceInstance(declaredService, serviceContext));
-
-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;
-};
-
-const resolveServices = async (
-  trail: AnyTrail,
-  ctx: TrailContext,
-  overrides?: ServiceOverrideMap
-): Promise<Result<TrailContext, Error>> => {
-  if (trail.services.length === 0) {
-    return Result.ok(ctx);
-  }
-
-  const resolvedServices: Record<string, unknown> = {};
-  const serviceContext = toServiceContext(ctx);
-
-  for (const declaredService of trail.services) {
-    const resolved = await resolveServiceInstance(
-      declaredService,
-      ctx,
-      serviceContext,
-      overrides
-    );
-    if (resolved.isErr()) {
-      return resolved;
-    }
-
-    resolvedServices[declaredService.id] = resolved.unwrap();
-  }
-
-  return Result.ok(withResolvedServices(ctx, resolvedServices));
-};
-
 const prepareContext = async (
   trail: AnyTrail,
   options?: ExecuteTrailOptions
 ): Promise<Result<TrailContext, Error>> => {
   const baseCtx = await resolveContext(options);
-  return await resolveServices(trail, baseCtx, options?.services);
+  return await resolveServices(
+    trail,
+    baseCtx,
+    options?.services,
+    options?.configValues
+  );
 };
 
 const runTrail = async (

package/src/index.ts

@@ -32,11 +32,14 @@ export type {
   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';