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

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.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;
+};