@ontrails/core 1.0.0-beta.13 → 1.0.0-beta.15

package/src/__tests__/trail.test.ts

@@ -2,9 +2,12 @@ import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
+import { contour } from '../contour';
 import { createTrailContext } from '../context';
+import { ConflictError } from '../errors';
 import { Result } from '../result';
-import { provision } from '../provision';
+import { resource } from '../resource';
+import { signal } from '../signal';
 import { trail } from '../trail';
 import type { TrailContext } from '../types';
 
@@ -13,16 +16,25 @@ const stubCtx: TrailContext = createTrailContext({
   requestId: 'test-123',
 });
 
-const dbProvision = provision('db.main', {
+const dbResource = resource('db.main', {
   create: () =>
     Result.ok({
       query(sql: string) {
         return sql.length;
       },
     }),
-  description: 'Primary database provision',
+  description: 'Primary database resource',
 });
 
+const userContour = contour(
+  'user',
+  {
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  { identity: 'id' }
+);
+
 describe('trail()', () => {
   const inputSchema = z.object({ name: z.string() });
   const outputSchema = z.object({ greeting: z.string() });
@@ -92,19 +104,34 @@ describe('trail()', () => {
       expect(withMeta.meta).toEqual({ domain: 'billing', tier: 1 });
     });
 
+    test('pattern is stored when declared', () => {
+      const withPattern = trail('feature.enable', {
+        blaze: () => Result.ok({ enabled: true }),
+        input: z.object({ id: z.string() }),
+        pattern: 'toggle',
+      });
+
+      expect(withPattern.pattern).toBe('toggle');
+    });
+
     test('detours are stored', () => {
       const withDetours = trail('orchestrator', {
         blaze: () => Result.ok(),
-        detours: {
-          onFailure: ['alert'],
-          onSuccess: ['notify', 'audit'],
-        },
+        /* oxlint-disable-next-line require-await -- test stub */
+        detours: [{ on: ConflictError, recover: async () => Result.ok() }],
         input: z.object({}),
       });
-      expect(withDetours.detours).toEqual({
-        onFailure: ['alert'],
-        onSuccess: ['notify', 'audit'],
+      expect(withDetours.detours).toHaveLength(1);
+      expect(withDetours.detours[0]?.on).toBe(ConflictError);
+    });
+
+    test('detours default to empty frozen array when omitted', () => {
+      const noDetours = trail('bare', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
       });
+      expect(noDetours.detours).toEqual([]);
+      expect(Object.isFrozen(noDetours.detours)).toBe(true);
     });
   });
 
@@ -135,35 +162,109 @@ describe('trail()', () => {
       });
       expect(Object.isFrozen(withCrosses.crosses)).toBe(true);
     });
+
+    test('trail object in crosses is normalized to its id', () => {
+      const target = trail('target.trail', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+      });
+      const composed = trail('composed', {
+        blaze: () => Result.ok(),
+        crosses: [target],
+        input: z.object({}),
+      });
+      expect(composed.crosses).toEqual(['target.trail']);
+    });
+
+    test('mixed string and trail object in crosses normalizes correctly', () => {
+      const target = trail('target.trail', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+      });
+      const composed = trail('composed', {
+        blaze: () => Result.ok(),
+        crosses: ['string-id', target],
+        input: z.object({}),
+      });
+      expect(composed.crosses).toEqual(['string-id', 'target.trail']);
+    });
+
+    test('crossInput is stored on the trail', () => {
+      const crossInputSchema = z.object({ forkedFrom: z.string().optional() });
+      const t = trail('gist.create', {
+        blaze: () => Result.ok(),
+        crossInput: crossInputSchema,
+        input: z.object({ content: z.string() }),
+      });
+      expect(t.crossInput).toBe(crossInputSchema);
+    });
+
+    test('crossInput is undefined when omitted', () => {
+      const t = trail('bare', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(t.crossInput).toBeUndefined();
+    });
+  });
+
+  describe('contours', () => {
+    test('defaults to empty frozen array when omitted', () => {
+      const minimal = trail('bare', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(minimal.contours).toEqual([]);
+      expect(Object.isFrozen(minimal.contours)).toBe(true);
+    });
+
+    test('preserves declared contour objects', () => {
+      const withContours = trail('user.create', {
+        blaze: () => Result.ok(),
+        contours: [userContour],
+        input: z.object({}),
+      });
+      expect(withContours.contours).toEqual([userContour]);
+      expect(withContours.contours[0]).toBe(userContour);
+    });
+
+    test('contours array is frozen', () => {
+      const withContours = trail('user.create', {
+        blaze: () => Result.ok(),
+        contours: [userContour],
+        input: z.object({}),
+      });
+      expect(Object.isFrozen(withContours.contours)).toBe(true);
+    });
   });
 
-  describe('provisions', () => {
+  describe('resources', () => {
     test('defaults to empty frozen array when omitted', () => {
       const minimal = trail('bare', {
         blaze: () => Result.ok(),
         input: z.object({}),
       });
-      expect(minimal.provisions).toEqual([]);
-      expect(Object.isFrozen(minimal.provisions)).toBe(true);
+      expect(minimal.resources).toEqual([]);
+      expect(Object.isFrozen(minimal.resources)).toBe(true);
     });
 
-    test('preserves declared provision objects', () => {
-      const withProvisions = trail('search', {
+    test('preserves declared resource objects', () => {
+      const withResources = trail('search', {
         blaze: () => Result.ok(),
         input: z.object({}),
-        provisions: [dbProvision],
+        resources: [dbResource],
       });
-      expect(withProvisions.provisions).toEqual([dbProvision]);
-      expect(withProvisions.provisions[0]).toBe(dbProvision);
+      expect(withResources.resources).toEqual([dbResource]);
+      expect(withResources.resources[0]).toBe(dbResource);
     });
 
-    test('provisions array is frozen', () => {
-      const withProvisions = trail('search', {
+    test('resources array is frozen', () => {
+      const withResources = trail('search', {
         blaze: () => Result.ok(),
         input: z.object({}),
-        provisions: [dbProvision],
+        resources: [dbResource],
       });
-      expect(Object.isFrozen(withProvisions.provisions)).toBe(true);
+      expect(Object.isFrozen(withResources.resources)).toBe(true);
     });
   });
 
@@ -201,6 +302,23 @@ describe('trail()', () => {
       });
       expect(t.idempotent).toBe(true);
     });
+
+    test('visibility defaults to public', () => {
+      const minimal = trail('visible', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(minimal.visibility).toBe('public');
+    });
+
+    test('visibility is preserved when set', () => {
+      const t = trail('internal.helper', {
+        blaze: () => Result.ok(),
+        input: z.object({}),
+        visibility: 'internal',
+      });
+      expect(t.visibility).toBe('internal');
+    });
   });
 
   describe('single-object overload', () => {
@@ -225,12 +343,12 @@ describe('trail()', () => {
         input: inputSchema,
         intent: 'read',
         output: outputSchema,
-        provisions: [dbProvision],
+        resources: [dbResource],
       });
       expect(t.description).toBe('A full trail');
       expect(t.intent).toBe('read');
       expect(t.examples).toHaveLength(1);
-      expect(t.provisions).toEqual([dbProvision]);
+      expect(t.resources).toEqual([dbResource]);
     });
 
     test('implementation is callable', async () => {
@@ -259,3 +377,50 @@ describe('trail()', () => {
     });
   });
 });
+
+describe('trail() fires/on normalization', () => {
+  const orderPlaced = signal('order.placed', {
+    payload: z.object({ id: z.string() }),
+  });
+  const auditLogged = signal('audit.logged', {
+    payload: z.object({ actor: z.string() }),
+  });
+
+  test('Signal value in fires: is normalized to its id', () => {
+    const t = trail('checkout', {
+      blaze: () => Result.ok({}),
+      fires: [orderPlaced],
+      input: z.object({}),
+    });
+    expect(t.fires).toEqual(['order.placed']);
+  });
+
+  test('Signal value in on: is normalized to its id', () => {
+    const t = trail('notify', {
+      blaze: () => Result.ok({}),
+      input: z.object({}),
+      on: [orderPlaced],
+    });
+    expect(t.on).toEqual(['order.placed']);
+  });
+
+  test('mixed string + Signal value in fires: is normalized', () => {
+    const t = trail('checkout', {
+      blaze: () => Result.ok({}),
+      fires: ['metric.emitted', orderPlaced, auditLogged],
+      input: z.object({}),
+    });
+    expect(t.fires).toEqual(['metric.emitted', 'order.placed', 'audit.logged']);
+  });
+
+  test('defaults to empty frozen arrays when omitted', () => {
+    const minimal = trail('bare', {
+      blaze: () => Result.ok(),
+      input: z.object({}),
+    });
+    expect(minimal.fires).toEqual([]);
+    expect(Object.isFrozen(minimal.fires)).toBe(true);
+    expect(minimal.on).toEqual([]);
+    expect(Object.isFrozen(minimal.on)).toBe(true);
+  });
+});

package/src/__tests__/trails-db.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  ensureSubsystemSchema,
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  deriveTrailsDbPath,
+} from '../internal/trails-db.js';
+import {
+  createTopoSnapshot,
+  ensureTopoSnapshotSchema,
+  listTopoSnapshots,
+  pinTopoSnapshot,
+  pruneUnpinnedSnapshots,
+} from '../internal/topo-snapshots.js';
+
+describe('trails db foundation', () => {
+  let tmpRoot: string | undefined;
+
+  afterEach(() => {
+    if (tmpRoot) {
+      rmSync(tmpRoot, { force: true, recursive: true });
+      tmpRoot = undefined;
+    }
+  });
+
+  const makeRoot = (): string => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'trails-db-'));
+    return tmpRoot;
+  };
+
+  const expectWorkspaceLayout = (rootDir: string): void => {
+    expect(existsSync(join(rootDir, '.trails', '.gitignore'))).toBe(true);
+    expect(existsSync(join(rootDir, '.trails', 'config'))).toBe(true);
+    expect(existsSync(join(rootDir, '.trails', 'dev'))).toBe(true);
+    expect(existsSync(join(rootDir, '.trails', 'generated'))).toBe(true);
+  };
+
+  test('deriveTrailsDbPath places the database in .trails/trails.db', () => {
+    const rootDir = '/tmp/example-app';
+    expect(deriveTrailsDbPath({ rootDir })).toBe(
+      '/tmp/example-app/.trails/trails.db'
+    );
+  });
+
+  test('openWriteTrailsDb creates the database with WAL and NORMAL defaults', () => {
+    const rootDir = makeRoot();
+    const db = openWriteTrailsDb({ rootDir });
+
+    try {
+      expect(existsSync(deriveTrailsDbPath({ rootDir }))).toBe(true);
+      expectWorkspaceLayout(rootDir);
+
+      const journal = db
+        .query<{ journal_mode: string }, []>('PRAGMA journal_mode')
+        .get();
+      const synchronous = db
+        .query<{ synchronous: number }, []>('PRAGMA synchronous')
+        .get();
+
+      expect(journal?.journal_mode.toLowerCase()).toBe('wal');
+      expect(synchronous?.synchronous).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  test('openReadTrailsDb blocks writes at the SQLite connection level', () => {
+    const rootDir = makeRoot();
+    const writer = openWriteTrailsDb({ rootDir });
+    writer.close();
+
+    const reader = openReadTrailsDb({ rootDir });
+
+    try {
+      expect(() => reader.run('CREATE TABLE readonly_probe (id TEXT)')).toThrow(
+        /readonly|read-only/i
+      );
+    } finally {
+      reader.close();
+    }
+  });
+
+  test('ensureSubsystemSchema only migrates when the subsystem version changes', () => {
+    const rootDir = makeRoot();
+    const db = openWriteTrailsDb({ rootDir });
+    let calls = 0;
+
+    try {
+      ensureSubsystemSchema(db, {
+        migrate: () => {
+          calls += 1;
+          db.run(
+            'CREATE TABLE IF NOT EXISTS track_records (id TEXT PRIMARY KEY)'
+          );
+        },
+        subsystem: 'track',
+        version: 1,
+      });
+
+      ensureSubsystemSchema(db, {
+        migrate: () => {
+          calls += 1;
+        },
+        subsystem: 'track',
+        version: 1,
+      });
+
+      ensureSubsystemSchema(db, {
+        migrate: (currentVersion) => {
+          calls += 1;
+          expect(currentVersion).toBe(1);
+          db.run('ALTER TABLE track_records ADD COLUMN status TEXT');
+        },
+        subsystem: 'track',
+        version: 2,
+      });
+
+      expect(calls).toBe(2);
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe('topo snapshot primitives', () => {
+  let tmpRoot: string | undefined;
+
+  afterEach(() => {
+    if (tmpRoot) {
+      rmSync(tmpRoot, { force: true, recursive: true });
+      tmpRoot = undefined;
+    }
+  });
+
+  const makeRoot = (): string => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'topo-snapshots-'));
+    return tmpRoot;
+  };
+
+  const seedHistory = (db: ReturnType<typeof openWriteTrailsDb>) => {
+    ensureTopoSnapshotSchema(db);
+
+    const pinned = createTopoSnapshot(db, {
+      createdAt: '2026-04-01T00:00:00.000Z',
+      gitDirty: false,
+      gitSha: 'abc123',
+      resourceCount: 2,
+      signalCount: 1,
+      trailCount: 3,
+    });
+    const disposable = createTopoSnapshot(db, {
+      createdAt: '2026-04-02T00:00:00.000Z',
+      gitDirty: true,
+      gitSha: 'def456',
+      resourceCount: 3,
+      signalCount: 2,
+      trailCount: 4,
+    });
+
+    return {
+      disposable,
+      pinned,
+      pinnedSnapshot: pinTopoSnapshot(db, {
+        id: pinned.id,
+        name: 'before-auth',
+      }),
+    };
+  };
+
+  test('creates snapshots, pins them, and prunes only unpinned history', () => {
+    const rootDir = makeRoot();
+    const db = openWriteTrailsDb({ rootDir });
+
+    try {
+      const { disposable, pinned, pinnedSnapshot } = seedHistory(db);
+
+      expect(pinnedSnapshot?.pinnedAs).toBe('before-auth');
+      expect(
+        listTopoSnapshots(db, { pinned: true }).map((snapshot) => snapshot.id)
+      ).toEqual([pinned.id]);
+      expect(listTopoSnapshots(db).map((snapshot) => snapshot.id)).toEqual([
+        disposable.id,
+        pinned.id,
+      ]);
+
+      expect(pruneUnpinnedSnapshots(db, { keep: 0 })).toBe(1);
+      expect(listTopoSnapshots(db).map((snapshot) => snapshot.id)).toEqual([
+        pinned.id,
+      ]);
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/__tests__/transport-error-map.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  CancelledError,
+  NetworkError,
+  NotFoundError,
+  ValidationError,
+  errorCategories,
+  exitCodeMap,
+  jsonRpcCodeMap,
+  statusCodeMap,
+} from '../errors.js';
+import {
+  createTransportErrorMapper,
+  mapTransportError,
+  transportErrorMap,
+  transportErrorRegistry,
+  transportNames,
+} from '../transport-error-map.js';
+
+describe('transportErrorMap', () => {
+  test('covers every error category for every transport', () => {
+    for (const transport of transportNames) {
+      const mappings = transportErrorMap[transport];
+      for (const category of errorCategories) {
+        expect(category in mappings).toBe(true);
+      }
+    }
+  });
+
+  test('reuses the existing public transport maps', () => {
+    expect(transportErrorMap.cli).toBe(exitCodeMap);
+    expect(transportErrorMap.http).toBe(statusCodeMap);
+    expect(transportErrorMap.mcp).toBe(jsonRpcCodeMap);
+  });
+});
+
+describe('transportErrorRegistry', () => {
+  test('exposes a callable mapper for each transport', () => {
+    const notFound = new NotFoundError('missing');
+
+    expect(transportErrorRegistry.cli.map(notFound)).toBe(2);
+    expect(transportErrorRegistry.http.map(notFound)).toBe(404);
+    expect(transportErrorRegistry.mcp.map(notFound)).toBe(-32_601);
+  });
+});
+
+describe('mapTransportError', () => {
+  test('maps known error instances through each registered transport', () => {
+    const validation = new ValidationError('bad input');
+    const notFound = new NotFoundError('missing');
+    const network = new NetworkError('offline');
+    const cancelled = new CancelledError('cancelled');
+
+    expect(mapTransportError('cli', validation)).toBe(1);
+    expect(mapTransportError('http', notFound)).toBe(404);
+    expect(mapTransportError('mcp', notFound)).toBe(-32_601);
+    expect(mapTransportError('http', network)).toBe(502);
+    expect(mapTransportError('cli', cancelled)).toBe(130);
+  });
+});
+
+describe('createTransportErrorMapper', () => {
+  test('uses the error category to project into transport-specific values', () => {
+    const mapper = createTransportErrorMapper({
+      auth: 'auth',
+      cancelled: 'cancelled',
+      conflict: 'conflict',
+      internal: 'internal',
+      network: 'network',
+      not_found: 'not_found',
+      permission: 'permission',
+      rate_limit: 'rate_limit',
+      timeout: 'timeout',
+      validation: 'validation',
+    });
+
+    expect(mapper(new ValidationError('bad input'))).toBe('validation');
+    expect(mapper(new NetworkError('offline'))).toBe('network');
+    expect(mapper(new CancelledError('cancelled'))).toBe('cancelled');
+  });
+});

package/src/__tests__/type-utils.test.ts

@@ -4,7 +4,12 @@ import { z } from 'zod';
 
 import { Result } from '../result';
 import { trail } from '../trail';
-import type { TrailInput, TrailOutput, TrailResult } from '../type-utils';
+import type {
+  CrossInput,
+  TrailInput,
+  TrailOutput,
+  TrailResult,
+} from '../type-utils';
 import { inputOf, outputOf } from '../type-utils';
 
 const greetTrail = trail('greet', {
@@ -68,6 +73,29 @@ describe('type-utils', () => {
     });
   });
 
+  describe('CrossInput', () => {
+    test('returns base input when no crossInput defined', () => {
+      type Input = CrossInput<typeof greetTrail>;
+      const _input: Input = { name: 'test' };
+      expect(_input.name).toBe('test');
+    });
+
+    test('merges crossInput with base input when crossInput defined', () => {
+      const crossTrail = trail('cross.test', {
+        blaze: (input) => Result.ok({ name: input.name }),
+        crossInput: z.object({ forkedFrom: z.string() }),
+        input: z.object({ name: z.string() }),
+        output: z.object({ name: z.string() }),
+      });
+
+      type Input = CrossInput<typeof crossTrail>;
+      // If this compiles, the type correctly merges both schemas
+      const _input: Input = { forkedFrom: 'origin', name: 'test' };
+      expect(_input.name).toBe('test');
+      expect(_input.forkedFrom).toBe('origin');
+    });
+  });
+
   describe('TrailResult', () => {
     test('extracts Result<Output, Error> from a trail', () => {
       const t = trail('test.result', {