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

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

@@ -0,0 +1,191 @@
+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,
+  resolveTrailsDbPath,
+} from '../internal/trails-db.js';
+import {
+  createTopoSave,
+  ensureTopoHistorySchema,
+  listTopoPins,
+  listTopoSaves,
+  pinTopoSave,
+  pruneUnpinnedTopoSaves,
+} from '../internal/topo-saves.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('resolveTrailsDbPath places the database in .trails/trails.db', () => {
+    const rootDir = '/tmp/example-app';
+    expect(resolveTrailsDbPath({ 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(resolveTrailsDbPath({ 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 save primitives', () => {
+  let tmpRoot: string | undefined;
+
+  afterEach(() => {
+    if (tmpRoot) {
+      rmSync(tmpRoot, { force: true, recursive: true });
+      tmpRoot = undefined;
+    }
+  });
+
+  const makeRoot = (): string => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'topo-saves-'));
+    return tmpRoot;
+  };
+
+  const seedHistory = (db: ReturnType<typeof openWriteTrailsDb>) => {
+    ensureTopoHistorySchema(db);
+
+    const pinned = createTopoSave(db, {
+      createdAt: '2026-04-01T00:00:00.000Z',
+      gitDirty: false,
+      gitSha: 'abc123',
+      provisionCount: 2,
+      signalCount: 1,
+      trailCount: 3,
+    });
+    const disposable = createTopoSave(db, {
+      createdAt: '2026-04-02T00:00:00.000Z',
+      gitDirty: true,
+      gitSha: 'def456',
+      provisionCount: 3,
+      signalCount: 2,
+      trailCount: 4,
+    });
+
+    return {
+      disposable,
+      pin: pinTopoSave(db, { name: 'before-auth', saveId: pinned.id }),
+      pinned,
+    };
+  };
+
+  test('creates saves, pins them, and prunes only unpinned history', () => {
+    const rootDir = makeRoot();
+    const db = openWriteTrailsDb({ rootDir });
+
+    try {
+      const { disposable, pin, pinned } = seedHistory(db);
+
+      expect(listTopoPins(db)).toEqual([pin]);
+      expect(listTopoSaves(db).map((save) => save.id)).toEqual([
+        disposable.id,
+        pinned.id,
+      ]);
+
+      expect(pruneUnpinnedTopoSaves(db, { keep: 0 })).toBe(1);
+      expect(listTopoSaves(db).map((save) => save.id)).toEqual([pinned.id]);
+    } finally {
+      db.close();
+    }
+  });
+});

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

@@ -8,14 +8,14 @@ import type { TrailInput, TrailOutput, TrailResult } from '../type-utils';
 import { inputOf, outputOf } from '../type-utils';
 
 const greetTrail = trail('greet', {
+  blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
   input: z.object({ name: z.string() }),
   output: z.object({ message: z.string() }),
-  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
 const noOutputTrail = trail('ping', {
+  blaze: () => Result.ok(),
   input: z.object({}),
-  run: () => Result.ok(),
 });
 
 describe('type-utils', () => {
@@ -71,9 +71,9 @@ describe('type-utils', () => {
   describe('TrailResult', () => {
     test('extracts Result<Output, Error> from a trail', () => {
       const t = trail('test.result', {
+        blaze: (input) => Result.ok({ answer: input.q }),
         input: z.object({ q: z.string() }),
         output: z.object({ answer: z.string() }),
-        run: (input) => Result.ok({ answer: input.q }),
       });
 
       type Expected = Result<{ answer: string }, Error>;

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

@@ -2,8 +2,10 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
+import { analyzeDraftState, isDraftId } from '../draft.js';
+import { validateEstablishedTopo } from '../validate-established-topo.js';
+import { provision } from '../provision.js';
 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';
@@ -18,7 +20,7 @@ const noop = async () => Result.ok();
 const mockTrail = (
   id: string,
   overrides?: {
-    follow?: readonly string[];
+    crosses?: readonly string[];
     examples?: readonly {
       name: string;
       input: unknown;
@@ -26,27 +28,27 @@ const mockTrail = (
       error?: string;
     }[];
     output?: z.ZodType;
-    services?: readonly ReturnType<typeof service>[];
+    provisions?: readonly ReturnType<typeof provision>[];
   }
 ) => ({
-  follow: Object.freeze([...(overrides?.follow ?? [])]),
+  blaze: noop,
+  crosses: Object.freeze([...(overrides?.crosses ?? [])]),
   id,
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
-  run: noop,
-  services: Object.freeze([...(overrides?.services ?? [])]),
+  provisions: Object.freeze([...(overrides?.provisions ?? [])]),
   ...overrides,
 });
 
-const mockService = (id: string) =>
-  service(id, {
+const mockProvision = (id: string) =>
+  provision(id, {
     create: () => Result.ok({ id }),
   });
 
 const mockEvent = (id: string, from?: readonly string[]) => ({
   from,
   id,
-  kind: 'event' as const,
+  kind: 'signal' as const,
   payload: z.object({ data: z.string() }),
 });
 
@@ -68,7 +70,7 @@ describe('validateTopo', () => {
     const app = topo('app', {
       add: mockTrail('entity.add'),
       onboard: mockTrail('entity.onboard', {
-        follow: ['entity.add'],
+        crosses: ['entity.add'],
       }),
       updated: mockEvent('entity.updated', ['entity.add']),
     });
@@ -77,11 +79,22 @@ describe('validateTopo', () => {
     expect(result.isOk()).toBe(true);
   });
 
-  describe('trail follow', () => {
-    test('trail following non-existent trail fails', () => {
+  describe('trail crossing', () => {
+    test('draft crossings are allowed in the authored graph', () => {
+      const app = topo('app', {
+        exportTrail: mockTrail('entity.export', {
+          crosses: ['_draft.entity.prepare'],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('trail crossing a non-existent trail fails', () => {
       const app = topo('app', {
         onboard: mockTrail('entity.onboard', {
-          follow: ['entity.missing'],
+          crosses: ['entity.missing'],
         }),
       });
 
@@ -90,57 +103,57 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('follow-exists');
+      expect(issues[0]?.rule).toBe('cross-exists');
       expect(issues[0]?.message).toContain('entity.missing');
     });
 
-    test('trail following itself fails', () => {
+    test('trail crossing itself fails', () => {
       const app = topo('app', {
-        loop: mockTrail('entity.loop', { follow: ['entity.loop'] }),
+        loop: mockTrail('entity.loop', { crosses: ['entity.loop'] }),
       });
 
       const result = validateTopo(app);
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      expect(issues.some((i) => i.rule === 'no-self-follow')).toBe(true);
+      expect(issues.some((i) => i.rule === 'no-self-cross')).toBe(true);
     });
 
     test('two-node cycle (a→b→a) is detected', () => {
       const app = topo('app', {
-        a: mockTrail('a', { follow: ['b'] }),
-        b: mockTrail('b', { follow: ['a'] }),
+        a: mockTrail('a', { crosses: ['b'] }),
+        b: mockTrail('b', { crosses: ['a'] }),
       });
 
       const result = validateTopo(app);
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      const cycleIssues = issues.filter((i) => i.rule === 'cross-cycle');
       expect(cycleIssues.length).toBeGreaterThanOrEqual(1);
       expect(cycleIssues[0]?.message).toContain('Cycle detected');
     });
 
     test('three-node cycle (a→b→c→a) is detected', () => {
       const app = topo('app', {
-        a: mockTrail('a', { follow: ['b'] }),
-        b: mockTrail('b', { follow: ['c'] }),
-        c: mockTrail('c', { follow: ['a'] }),
+        a: mockTrail('a', { crosses: ['b'] }),
+        b: mockTrail('b', { crosses: ['c'] }),
+        c: mockTrail('c', { crosses: ['a'] }),
       });
 
       const result = validateTopo(app);
       expect(result.isErr()).toBe(true);
 
       const issues = extractIssues(result);
-      const cycleIssues = issues.filter((i) => i.rule === 'follow-cycle');
+      const cycleIssues = issues.filter((i) => i.rule === 'cross-cycle');
       expect(cycleIssues.length).toBeGreaterThanOrEqual(1);
       expect(cycleIssues[0]?.message).toContain('Cycle detected');
     });
 
     test('valid DAG with shared targets is not flagged', () => {
       const app = topo('app', {
-        a: mockTrail('a', { follow: ['c'] }),
-        b: mockTrail('b', { follow: ['c'] }),
+        a: mockTrail('a', { crosses: ['c'] }),
+        b: mockTrail('b', { crosses: ['c'] }),
         c: mockTrail('c'),
       });
 
@@ -149,13 +162,25 @@ describe('validateTopo', () => {
     });
   });
 
-  describe('service declarations', () => {
-    test('trail declaring a registered service passes', () => {
-      const db = mockService('db.main');
+  describe('provision declarations', () => {
+    test('draft provision references are allowed in the authored graph', () => {
+      const db = mockProvision('_draft.db.main');
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          provisions: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('trail declaring a registered provision passes', () => {
+      const db = mockProvision('db.main');
       const app = topo('app', {
         db,
         show: mockTrail('entity.show', {
-          services: [db],
+          provisions: [db],
         }),
       });
 
@@ -163,11 +188,11 @@ describe('validateTopo', () => {
       expect(result.isOk()).toBe(true);
     });
 
-    test('trail declaring a missing service fails', () => {
-      const db = mockService('db.main');
+    test('trail declaring a missing provision fails', () => {
+      const db = mockProvision('db.main');
       const app = topo('app', {
         show: mockTrail('entity.show', {
-          services: [db],
+          provisions: [db],
         }),
       });
 
@@ -176,7 +201,7 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('service-exists');
+      expect(issues[0]?.rule).toBe('provision-exists');
       expect(issues[0]?.message).toContain('db.main');
     });
   });
@@ -286,7 +311,7 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('event-origin-exists');
+      expect(issues[0]?.rule).toBe('signal-origin-exists');
       expect(issues[0]?.message).toContain('entity.ghost');
     });
 
@@ -301,11 +326,11 @@ describe('validateTopo', () => {
   });
 
   test('collects multiple issues', () => {
-    const db = mockService('db.main');
+    const db = mockProvision('db.main');
     const app = topo('app', {
-      broken: mockTrail('entity.broken', { follow: ['entity.missing'] }),
+      broken: mockTrail('entity.broken', { crosses: ['entity.missing'] }),
       missingService: mockTrail('entity.missing-service', {
-        services: [db],
+        provisions: [db],
       }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],
@@ -319,4 +344,146 @@ describe('validateTopo', () => {
     const issues = extractIssues(result);
     expect(issues).toHaveLength(4);
   });
+
+  describe('signal origins', () => {
+    test('draft signal origins are allowed in the authored graph', () => {
+      const app = topo('app', {
+        updated: mockEvent('entity.updated', ['_draft.entity.prepare']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+});
+
+describe('draft state analysis', () => {
+  test('detects declared draft ids', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const analysis = analyzeDraftState(app);
+
+    expect(analysis.declaredDraftIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.findings.map((finding) => finding.rule)).toContain(
+      'draft-id'
+    );
+  });
+
+  test('propagates contamination through dependencies', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.prepare'],
+      }),
+      prepareTrail: mockTrail('entity.prepare', {
+        crosses: ['_draft.entity.store'],
+      }),
+    });
+
+    const analysis = analyzeDraftState(app);
+    const exportFinding = analysis.findings.find(
+      (finding) => finding.id === 'entity.export'
+    );
+
+    expect(analysis.contaminatedIds.has('entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('entity.export')).toBe(true);
+    expect(exportFinding).toBeDefined();
+    expect(exportFinding?.rule).toBe('draft-contamination');
+  });
+});
+
+describe('validateEstablishedTopo', () => {
+  test('passes for an established topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+
+  test('fails when draft declarations remain', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-id');
+  });
+
+  test('fails when established trails depend on draft state', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['_draft.entity.prepare'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-contamination');
+    expect(issues[0]?.message).toContain('entity.export');
+  });
+
+  test('fails when authored structural validation still fails', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.missing'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('cross-exists');
+  });
+
+  test('fails when provision declarations are not established in the topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        provisions: [mockProvision('db.main')],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('provision-exists');
+  });
+
+  test('allows authoring-only example issues outside projection checks', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        examples: [
+          {
+            expected: { ok: true },
+            input: { name: 'test' },
+            name: 'Has expected',
+          },
+        ],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+});
+
+describe('isDraftId', () => {
+  test('recognizes the reserved draft prefix', () => {
+    expect(isDraftId('_draft.entity.show')).toBe(true);
+    expect(isDraftId('entity.show')).toBe(false);
+  });
 });

package/src/context.ts

@@ -1,4 +1,4 @@
-import { createServiceLookup } from './service.js';
+import { createProvisionLookup } from './provision.js';
 import type { TrailContext, TrailContextInit } from './types.js';
 
 type MutableTrailContext = {
@@ -9,19 +9,20 @@ type MutableTrailContext = {
  * Create a TrailContext with sensible defaults.
  *
  * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
- * - `signal` defaults to a fresh, non-aborted `AbortSignal`
+ * - `abortSignal` defaults to a fresh, non-aborted `AbortSignal`
  * - All other fields come from `overrides`
  */
 export const createTrailContext = (
   overrides?: Partial<TrailContextInit>
 ): TrailContext => {
   const ctx = {
+    abortSignal: new AbortController().signal,
     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);
+  const lookup = overrides?.provision ?? createProvisionLookup(() => ctx);
+  ctx.provision = lookup;
   return ctx;
 };