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

package/src/__tests__/service.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import {
+  Result,
+  createTrailContext,
+  findDuplicateServiceId,
+  isService,
+  service as defineService,
+} from '../index.js';
+import type {
+  Service,
+  ServiceContext,
+  ServiceSpec,
+  TrailContext,
+} from '../index.js';
+
+const serviceCtx: ServiceContext = {
+  cwd: '/tmp/trails',
+  env: { DATABASE_URL: 'file::memory:' },
+  workspaceRoot: '/tmp',
+};
+
+let disposedValue: number | undefined;
+
+const counterServiceSpec: ServiceSpec<number> = {
+  create: () => Result.ok(3),
+  description: 'Counter service',
+  dispose: (service) => {
+    disposedValue = service;
+  },
+  health: (service) => Result.ok({ healthy: service > 0 }),
+  metadata: { domain: 'data' },
+  mock: () => 1,
+};
+
+const resolvedServiceCtx = (id: string, instance: unknown): TrailContext =>
+  createTrailContext({
+    extensions: { [id]: instance },
+    requestId: `${id}-request`,
+    signal: new AbortController().signal,
+  });
+
+describe('service types', () => {
+  test('ServiceContext exposes the stable process-scoped fields', () => {
+    expect(serviceCtx.cwd).toBe('/tmp/trails');
+    expect(serviceCtx.env?.DATABASE_URL).toBe('file::memory:');
+    expect(serviceCtx.workspaceRoot).toBe('/tmp');
+  });
+
+  test('ServiceSpec stores description and metadata', () => {
+    expect(counterServiceSpec.description).toBe('Counter service');
+    expect(counterServiceSpec.metadata).toEqual({ domain: 'data' });
+  });
+
+  test('ServiceSpec can reserve a config schema for future composition', () => {
+    const config = z.object({ url: z.string().url() });
+    const spec: ServiceSpec<number> = {
+      config,
+      create: () => Result.ok(1),
+    };
+
+    expect(spec.config).toBe(config);
+  });
+
+  test('ServiceSpec create and health callbacks are callable', async () => {
+    const result = await counterServiceSpec.create(serviceCtx);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(3);
+
+    const health = await counterServiceSpec.health?.(result.unwrap());
+    expect(health?.isOk()).toBe(true);
+    expect(health?.unwrap()).toEqual({ healthy: true });
+  });
+
+  test('ServiceSpec mock and dispose callbacks are callable', async () => {
+    disposedValue = undefined;
+    const result = await counterServiceSpec.create(serviceCtx);
+    expect(result.isOk()).toBe(true);
+
+    const service = result.unwrap();
+    expect(await counterServiceSpec.mock?.()).toBe(1);
+
+    await counterServiceSpec.dispose?.(service);
+    expect(disposedValue).toBe(3);
+  });
+
+  test('ServiceSpec create can be async', async () => {
+    const spec: ServiceSpec<number> = {
+      create: async () => {
+        await Bun.sleep(0);
+        return Result.ok(7);
+      },
+    };
+
+    const result = await spec.create(serviceCtx);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(7);
+  });
+
+  test('Service carries identity alongside the shared spec fields', async () => {
+    const service: Service<number> = {
+      from(ctx) {
+        return ctx.service(this);
+      },
+      id: 'counter.main',
+      kind: 'service',
+      ...counterServiceSpec,
+    };
+
+    expect(service.kind).toBe('service');
+    expect(service.id).toBe('counter.main');
+
+    const created = await service.create(serviceCtx);
+    expect(created.isOk()).toBe(true);
+    expect(created.unwrap()).toBe(3);
+    expect(await service.mock?.()).toBe(1);
+  });
+});
+
+describe('service()', () => {
+  test('returns a frozen service object with kind and id', () => {
+    const counter = defineService('counter.main', counterServiceSpec);
+
+    expect(counter.kind).toBe('service');
+    expect(counter.id).toBe('counter.main');
+    expect(Object.isFrozen(counter)).toBe(true);
+  });
+
+  test('infers the service type through from(ctx)', () => {
+    const db = defineService('db.main', {
+      create: () =>
+        Result.ok({
+          query(sql: string) {
+            return sql.length;
+          },
+        }),
+      description: 'Typed database service',
+    });
+
+    const store = {
+      query(sql: string) {
+        return sql.length;
+      },
+    };
+    const ctx = resolvedServiceCtx('db.main', store);
+
+    const resolved = db.from(ctx);
+    expect(resolved.query('select 1')).toBe(8);
+  });
+
+  test('from(ctx) throws when the service is missing', () => {
+    const counter = defineService('counter.main', counterServiceSpec);
+    const ctx = createTrailContext({
+      requestId: 'missing-service',
+      signal: new AbortController().signal,
+    });
+
+    expect(() => counter.from(ctx)).toThrow(
+      'Service "counter.main" not found in trail context'
+    );
+  });
+
+  test('from(ctx) returns undefined when the service key exists with an undefined value', () => {
+    const optional = defineService<undefined>('optional.main', {
+      create: () => Result.ok<undefined>(),
+    });
+    const ctx = createTrailContext({
+      extensions: { [optional.id]: undefined },
+      requestId: 'undefined-service',
+      signal: new AbortController().signal,
+    });
+
+    expect(optional.from(ctx)).toBeUndefined();
+  });
+});
+
+describe('service helpers', () => {
+  test('isService identifies service definitions', () => {
+    const counter = defineService('counter.main', counterServiceSpec);
+
+    expect(isService(counter)).toBe(true);
+    expect(isService({ id: 'counter.main', kind: 'trail' })).toBe(false);
+    expect(isService(null)).toBe(false);
+  });
+
+  test('findDuplicateServiceId returns the first repeated ID', () => {
+    const first = defineService('counter.main', counterServiceSpec);
+    const duplicate = defineService('counter.main', counterServiceSpec);
+    const other = defineService('counter.secondary', counterServiceSpec);
+
+    expect(findDuplicateServiceId([first, other])).toBeUndefined();
+    expect(findDuplicateServiceId([first, other, duplicate])).toBe(
+      'counter.main'
+    );
+  });
+});

package/src/__tests__/topo.test.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 
 import { ValidationError } from '../errors.js';
 import { Result } from '../result.js';
+import { service } from '../service.js';
 import { topo } from '../topo.js';
 
 // ---------------------------------------------------------------------------
@@ -28,6 +29,12 @@ const mockEvent = (id: string) => ({
   payload: z.object({ payload: z.string() }),
 });
 
+const mockService = (id: string) =>
+  service(id, {
+    create: () => Result.ok({ id }),
+    description: `${id} service`,
+  });
+
 // ---------------------------------------------------------------------------
 // topo()
 // ---------------------------------------------------------------------------
@@ -50,6 +57,7 @@ describe('topo', () => {
     test('auto-scans exports by kind discriminant', () => {
       const mod = {
         event1: mockEvent('e1'),
+        service1: mockService('s1'),
         trail1: mockTrail('t1'),
         trail2: mockTrail('t2', ['t1']),
       };
@@ -57,6 +65,7 @@ describe('topo', () => {
 
       expect(t.trails.size).toBe(2);
       expect(t.events.size).toBe(1);
+      expect(t.services.size).toBe(1);
     });
 
     test('collects from multiple modules', () => {
@@ -81,6 +90,7 @@ describe('topo', () => {
 
       expect(t.trails.size).toBe(1);
       expect(t.events.size).toBe(0);
+      expect(t.services.size).toBe(0);
     });
 
     test('trail with follow registers correctly', () => {
@@ -91,6 +101,14 @@ describe('topo', () => {
       const registered = t.trails.get('trail-1');
       expect(registered?.follow).toEqual(['trail-2']);
     });
+
+    test('collects services from modules', () => {
+      const mod = { db: mockService('db.main') };
+      const t = topo('app', mod);
+
+      expect(t.services.size).toBe(1);
+      expect(t.services.get('db.main')).toBe(mod.db);
+    });
   });
 
   describe('duplicate rejection', () => {
@@ -113,6 +131,16 @@ describe('topo', () => {
         'Duplicate event ID: "dup"'
       );
     });
+
+    test('rejects duplicate service IDs', () => {
+      const mod1 = { a: mockService('dup') };
+      const mod2 = { b: mockService('dup') };
+
+      expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+      expect(() => topo('app', mod1, mod2)).toThrow(
+        'Duplicate service ID: "dup"'
+      );
+    });
   });
 });
 
@@ -134,10 +162,26 @@ describe('topo accessors', () => {
     expect(app.count).toBe(1);
   });
 
+  test('serviceCount returns number of services', () => {
+    const db = mockService('db.main');
+    const cache = mockService('cache.main');
+    const app = topo('test', { cache, db });
+    expect(app.serviceCount).toBe(2);
+  });
+
   test('empty topo has zero count and empty ids', () => {
     const app = topo('empty');
     expect(app.count).toBe(0);
     expect(app.ids()).toEqual([]);
+    expect(app.serviceCount).toBe(0);
+    expect(app.serviceIds()).toEqual([]);
+  });
+
+  test('serviceIds() returns all service IDs', () => {
+    const db = mockService('db.main');
+    const cache = mockService('cache.main');
+    const app = topo('test', { cache, db });
+    expect(app.serviceIds().toSorted()).toEqual(['cache.main', 'db.main']);
   });
 });
 
@@ -148,6 +192,7 @@ describe('topo accessors', () => {
 describe('Topo', () => {
   const mod = {
     e1: mockEvent('event-1'),
+    s1: mockService('service-1'),
     t1: mockTrail('trail-1'),
     t2: mockTrail('trail-2'),
     t3: mockTrail('trail-3', ['trail-1']),
@@ -188,6 +233,26 @@ describe('Topo', () => {
     });
   });
 
+  describe('getService()', () => {
+    test('retrieves service by ID', () => {
+      expect(app.getService('service-1')).toBe(mod.s1);
+    });
+
+    test('returns undefined for unknown service ID', () => {
+      expect(app.getService('missing-service')).toBeUndefined();
+    });
+  });
+
+  describe('hasService()', () => {
+    test('returns true for known service', () => {
+      expect(app.hasService('service-1')).toBe(true);
+    });
+
+    test('returns false for unknown service', () => {
+      expect(app.hasService('missing-service')).toBe(false);
+    });
+  });
+
   describe('listing', () => {
     test('list() returns all trails (with and without follow)', () => {
       const items = app.list();
@@ -202,5 +267,11 @@ describe('Topo', () => {
       expect(items).toHaveLength(1);
       expect(items).toContain(mod.e1);
     });
+
+    test('listServices() returns all services', () => {
+      const items = app.listServices();
+      expect(items).toHaveLength(1);
+      expect(items).toContain(mod.s1);
+    });
   });
 });

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/__tests__/trail.test.ts

@@ -2,14 +2,26 @@ import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
+import { createTrailContext } from '../context';
 import { Result } from '../result';
+import { service } from '../service';
 import { trail } from '../trail';
 import type { TrailContext } from '../types';
 
-const stubCtx: TrailContext = {
+const stubCtx: TrailContext = createTrailContext({
   requestId: 'test-123',
   signal: AbortSignal.timeout(5000),
-};
+});
+
+const dbService = service('db.main', {
+  create: () =>
+    Result.ok({
+      query(sql: string) {
+        return sql.length;
+      },
+    }),
+  description: 'Primary database service',
+});
 
 describe('trail()', () => {
   const inputSchema = z.object({ name: z.string() });
@@ -125,6 +137,36 @@ describe('trail()', () => {
     });
   });
 
+  describe('services', () => {
+    test('defaults to empty frozen array when omitted', () => {
+      const minimal = trail('bare', {
+        input: z.object({}),
+        run: () => Result.ok(),
+      });
+      expect(minimal.services).toEqual([]);
+      expect(Object.isFrozen(minimal.services)).toBe(true);
+    });
+
+    test('preserves declared service objects', () => {
+      const withServices = trail('search', {
+        input: z.object({}),
+        run: () => Result.ok(),
+        services: [dbService],
+      });
+      expect(withServices.services).toEqual([dbService]);
+      expect(withServices.services[0]).toBe(dbService);
+    });
+
+    test('services array is frozen', () => {
+      const withServices = trail('search', {
+        input: z.object({}),
+        run: () => Result.ok(),
+        services: [dbService],
+      });
+      expect(Object.isFrozen(withServices.services)).toBe(true);
+    });
+  });
+
   describe('intent and idempotent', () => {
     test('intent defaults to write', () => {
       const minimal = trail('bare', {
@@ -183,10 +225,12 @@ describe('trail()', () => {
         output: outputSchema,
         run: (input: { name: string }, _ctx: TrailContext) =>
           Result.ok({ greeting: `Hi, ${input.name}` }),
+        services: [dbService],
       });
       expect(t.description).toBe('A full trail');
       expect(t.intent).toBe('read');
       expect(t.examples).toHaveLength(1);
+      expect(t.services).toEqual([dbService]);
     });
 
     test('implementation is callable', async () => {

package/src/__tests__/validate-topo.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { Result } from '../result.js';
+import { service } from '../service.js';
 import { topo } from '../topo.js';
 import type { TopoIssue } from '../validate-topo.js';
 import { validateTopo } from '../validate-topo.js';
@@ -25,6 +26,7 @@ const mockTrail = (
       error?: string;
     }[];
     output?: z.ZodType;
+    services?: readonly ReturnType<typeof service>[];
   }
 ) => ({
   follow: Object.freeze([...(overrides?.follow ?? [])]),
@@ -32,9 +34,15 @@ const mockTrail = (
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
   run: noop,
+  services: Object.freeze([...(overrides?.services ?? [])]),
   ...overrides,
 });
 
+const mockService = (id: string) =>
+  service(id, {
+    create: () => Result.ok({ id }),
+  });
+
 const mockEvent = (id: string, from?: readonly string[]) => ({
   from,
   id,
@@ -141,6 +149,38 @@ describe('validateTopo', () => {
     });
   });
 
+  describe('service declarations', () => {
+    test('trail declaring a registered service passes', () => {
+      const db = mockService('db.main');
+      const app = topo('app', {
+        db,
+        show: mockTrail('entity.show', {
+          services: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('trail declaring a missing service fails', () => {
+      const db = mockService('db.main');
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          services: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('service-exists');
+      expect(issues[0]?.message).toContain('db.main');
+    });
+  });
+
   describe('example validation', () => {
     test('example with invalid input fails', () => {
       const app = topo('app', {
@@ -261,8 +301,12 @@ describe('validateTopo', () => {
   });
 
   test('collects multiple issues', () => {
+    const db = mockService('db.main');
     const app = topo('app', {
       broken: mockTrail('entity.broken', { follow: ['entity.missing'] }),
+      missingService: mockTrail('entity.missing-service', {
+        services: [db],
+      }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],
       }),
@@ -273,6 +317,6 @@ describe('validateTopo', () => {
     expect(result.isErr()).toBe(true);
 
     const issues = extractIssues(result);
-    expect(issues).toHaveLength(3);
+    expect(issues).toHaveLength(4);
   });
 });

package/src/__tests__/validation.test.ts

@@ -280,4 +280,57 @@ describe('zodToJsonSchema', () => {
       expect(zodToJsonSchema(z.any())).toEqual({});
     });
   });
+
+  describe('default values', () => {
+    test('preserves static defaults as-is', () => {
+      const schema = z.string().default('hello');
+      expect(zodToJsonSchema(schema)).toEqual({
+        default: 'hello',
+        type: 'string',
+      });
+    });
+
+    test('omits dynamic defaults that produce different values', () => {
+      let counter = 0;
+      const schema = z.string().default(() => {
+        counter += 1;
+        return `id-${counter}`;
+      });
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({ type: 'string' });
+      expect(result['default']).toBeUndefined();
+    });
+
+    test('preserves stable functional defaults that return constant values', () => {
+      const schema = z.string().default(() => 'constant');
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({ default: 'constant', type: 'string' });
+    });
+
+    test('preserves stable functional defaults that return equivalent objects', () => {
+      const schema = z
+        .object({ key: z.string() })
+        .default(() => ({ key: 'val' }));
+      const result = zodToJsonSchema(schema);
+      expect(result['default']).toEqual({ key: 'val' });
+    });
+
+    test('preserves stable functional defaults that return equivalent arrays', () => {
+      const schema = z.array(z.string()).default(() => ['a', 'b']);
+      const result = zodToJsonSchema(schema);
+      expect(result['default']).toEqual(['a', 'b']);
+    });
+
+    test('produces identical output across repeated calls', () => {
+      let counter = 0;
+      const schema = z.string().default(() => {
+        counter += 1;
+        return `id-${counter}`;
+      });
+      const first = zodToJsonSchema(schema);
+      const second = zodToJsonSchema(schema);
+      // Key invariant: repeated calls always produce the same schema
+      expect(first).toEqual(second);
+    });
+  });
 });

package/src/context.ts

@@ -1,4 +1,9 @@
-import type { TrailContext } from './types.js';
+import { createServiceLookup } from './service.js';
+import type { TrailContext, TrailContextInit } from './types.js';
+
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
 
 /**
  * Create a TrailContext with sensible defaults.
@@ -8,11 +13,15 @@ import type { TrailContext } from './types.js';
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
-  overrides?: Partial<TrailContext>
-): TrailContext => ({
-  cwd: process.cwd(),
-  env: process.env as Record<string, string | undefined>,
-  requestId: Bun.randomUUIDv7(),
-  signal: new AbortController().signal,
-  ...overrides,
-});
+  overrides?: Partial<TrailContextInit>
+): TrailContext => {
+  const ctx = {
+    cwd: process.cwd(),
+    env: process.env as Record<string, string | undefined>,
+    requestId: Bun.randomUUIDv7(),
+    signal: new AbortController().signal,
+    ...overrides,
+  } as MutableTrailContext;
+  ctx.service = overrides?.service ?? createServiceLookup(() => ctx);
+  return ctx;
+};