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

package/src/__tests__/resource.test.ts

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

package/src/__tests__/run.test.ts

@@ -5,9 +5,9 @@ import { z } from 'zod';
 
 import { run } from '../run';
 import { InternalError, NotFoundError, ValidationError } from '../errors';
-import type { Gate } from '../gate';
+import type { Layer } from '../layer';
 import { Result } from '../result';
-import { provision } from '../provision';
+import { resource } from '../resource';
 import { topo } from '../topo';
 import { trail } from '../trail';
 import type { TrailContext, TrailContextInit } from '../types';
@@ -44,25 +44,25 @@ describe('run', () => {
       expect(result.unwrap()).toEqual({ value: 'hello' });
     });
 
-    test('passes provision overrides through to executeTrail', async () => {
-      const id = `run.provision.${Bun.randomUUIDv7()}`;
-      const db = provision(id, {
+    test('passes resource overrides through to executeTrail', async () => {
+      const id = `run.resource.${Bun.randomUUIDv7()}`;
+      const db = resource(id, {
         create: () => Result.ok({ source: 'factory' }),
       });
       const searchTrail = trail('search', {
         blaze: (_input, ctx) => Result.ok({ source: db.from(ctx).source }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        provisions: [db],
+        resources: [db],
       });
-      const searchTopo = topo('provision-test', { searchTrail });
+      const searchTopo = topo('resource-test', { searchTrail });
 
       const result = await run(
         searchTopo,
         'search',
         {},
         {
-          provisions: { [id]: { source: 'override' } },
+          resources: { [id]: { source: 'override' } },
         }
       );
 
@@ -91,11 +91,11 @@ describe('run', () => {
     });
   });
 
-  describe('gates', () => {
-    test('gate composition works through run', async () => {
+  describe('layers', () => {
+    test('layer composition works through run', async () => {
       const log: string[] = [];
-      const gate: Gate = {
-        name: 'test-gate',
+      const layer: Layer = {
+        name: 'test-layer',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             log.push('before');
@@ -110,7 +110,7 @@ describe('run', () => {
         testTopo,
         'echo',
         { value: 'x' },
-        { gates: [gate] }
+        { layers: [layer] }
       );
 
       expect(result.isOk()).toBe(true);

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

@@ -5,9 +5,9 @@ import { z } from 'zod';
 
 import { executeTrail } from '../execute.js';
 import { Result } from '../result.js';
-import { provision } from '../provision.js';
+import { resource } from '../resource.js';
 import { trail } from '../trail.js';
-import type { ProvisionContext } from '../provision.js';
+import type { ResourceContext } from '../resource.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -18,9 +18,9 @@ const nextId = (name: string): string =>
 
 const createSingletonConfigTrail = (id: string) => {
   const captures = { createCalls: 0 };
-  const svc = provision(id, {
+  const svc = resource(id, {
     config: z.object({ key: z.string() }),
-    create: (ctx: ProvisionContext<{ key: string }>) => {
+    create: (ctx: ResourceContext<{ key: string }>) => {
       captures.createCalls += 1;
       return Result.ok({
         createCall: captures.createCalls,
@@ -39,7 +39,7 @@ const createSingletonConfigTrail = (id: string) => {
         }),
       input: z.object({}),
       output: z.object({ createCall: z.number(), key: z.string() }),
-      provisions: [svc],
+      resources: [svc],
     }),
   };
 };
@@ -48,14 +48,14 @@ const createSingletonConfigTrail = (id: string) => {
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('ProvisionContext.config', () => {
-  test('provision with config schema receives validated config in svc.config', async () => {
+describe('ResourceContext.config', () => {
+  test('resource with config schema receives validated config in svc.config', async () => {
     const id = nextId('typed-config');
     let capturedConfig: unknown;
 
-    const db = provision(id, {
+    const db = resource(id, {
       config: z.object({ poolSize: z.number(), url: z.string().url() }),
-      create: (svc: ProvisionContext<{ url: string; poolSize: number }>) => {
+      create: (svc: ResourceContext<{ url: string; poolSize: number }>) => {
         capturedConfig = svc.config;
         return Result.ok({ connected: true });
       },
@@ -65,7 +65,7 @@ describe('ProvisionContext.config', () => {
       blaze: (_input, ctx) => Result.ok({ connected: db.from(ctx).connected }),
       input: z.object({}),
       output: z.object({ connected: z.boolean() }),
-      provisions: [db],
+      resources: [db],
     });
 
     const result = await executeTrail(
@@ -82,11 +82,11 @@ describe('ProvisionContext.config', () => {
     expect(capturedConfig).toEqual({ poolSize: 5, url: 'https://example.com' });
   });
 
-  test('provision without config still works — svc.config is undefined', async () => {
+  test('resource without config still works — svc.config is undefined', async () => {
     const id = nextId('no-config');
     let capturedConfig: unknown = 'sentinel';
 
-    const counter = provision(id, {
+    const counter = resource(id, {
       create: (svc) => {
         capturedConfig = svc.config;
         return Result.ok(42);
@@ -96,7 +96,7 @@ describe('ProvisionContext.config', () => {
     const counterTrail = trail('svc-config.no-config', {
       blaze: (_input, ctx) => Result.ok({ value: counter.from(ctx) }),
       input: z.object({}),
-      provisions: [counter],
+      resources: [counter],
     });
 
     const result = await executeTrail(counterTrail, {});
@@ -105,10 +105,10 @@ describe('ProvisionContext.config', () => {
     expect(capturedConfig).toBeUndefined();
   });
 
-  test('config validation failure returns Result.err at provision creation time', async () => {
+  test('config validation failure returns Result.err at resource creation time', async () => {
     const id = nextId('invalid-config');
 
-    const db = provision(id, {
+    const db = resource(id, {
       config: z.object({ url: z.string().url() }),
       create: () => Result.ok({ connected: true }),
     });
@@ -116,7 +116,7 @@ describe('ProvisionContext.config', () => {
     const dbTrail = trail('svc-config.invalid', {
       blaze: () => Result.ok(null),
       input: z.object({}),
-      provisions: [db],
+      resources: [db],
     });
 
     const result = await executeTrail(
@@ -133,10 +133,10 @@ describe('ProvisionContext.config', () => {
     expect(result.error.message).toContain(id);
   });
 
-  test('missing configValues for a provision with config schema returns Result.err', async () => {
+  test('missing configValues for a resource with config schema returns Result.err', async () => {
     const id = nextId('missing-config');
 
-    const db = provision(id, {
+    const db = resource(id, {
       config: z.object({ url: z.string().url() }),
       create: () => Result.ok({ connected: true }),
     });
@@ -144,7 +144,7 @@ describe('ProvisionContext.config', () => {
     const dbTrail = trail('svc-config.missing', {
       blaze: () => Result.ok(null),
       input: z.object({}),
-      provisions: [db],
+      resources: [db],
     });
 
     const result = await executeTrail(dbTrail, {});
@@ -153,10 +153,10 @@ describe('ProvisionContext.config', () => {
     expect(result.error.message).toContain(id);
   });
 
-  test('provision override bypasses config validation', async () => {
+  test('resource override bypasses config validation', async () => {
     const id = nextId('override-bypass');
 
-    const db = provision(id, {
+    const db = resource(id, {
       config: z.object({ url: z.string().url() }),
       create: () => Result.ok({ connected: true }),
     });
@@ -165,15 +165,11 @@ describe('ProvisionContext.config', () => {
       blaze: (_input, ctx) => Result.ok({ value: db.from(ctx) as number }),
       input: z.object({}),
       output: z.object({ value: z.number() }),
-      provisions: [db],
+      resources: [db],
     });
 
-    // Provide the provision via overrides without any configValues — should NOT fail
-    const result = await executeTrail(
-      dbTrail,
-      {},
-      { provisions: { [id]: 42 } }
-    );
+    // Provide the resource via overrides without any configValues — should NOT fail
+    const result = await executeTrail(dbTrail, {}, { resources: { [id]: 42 } });
 
     expect(result.isOk()).toBe(true);
     expect(result.unwrap()).toEqual({ value: 42 });
@@ -182,9 +178,9 @@ describe('ProvisionContext.config', () => {
     const id = nextId('options-config');
     const captures: unknown[] = [];
 
-    const svc = provision(id, {
+    const svc = resource(id, {
       config: z.object({ key: z.string() }),
-      create: (ctx: ProvisionContext<{ key: string }>) => {
+      create: (ctx: ResourceContext<{ key: string }>) => {
         captures.push(ctx.config);
         return Result.ok({ key: ctx.config.key });
       },
@@ -194,7 +190,7 @@ describe('ProvisionContext.config', () => {
       blaze: (_input, ctx) => Result.ok({ key: svc.from(ctx).key }),
       input: z.object({}),
       output: z.object({ key: z.string() }),
-      provisions: [svc],
+      resources: [svc],
     });
 
     const result = await executeTrail(
@@ -210,7 +206,7 @@ describe('ProvisionContext.config', () => {
     expect(captures).toEqual([{ key: 'hello' }]);
   });
 
-  test('config-aware singleton provisions reuse the cached instance', async () => {
+  test('config-aware singleton resources reuse the cached instance', async () => {
     const id = nextId('singleton-config');
     const { captures, trail: singletonTrail } = createSingletonConfigTrail(id);
     const options = {

package/src/__tests__/surface-filter.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result.js';
+import { filterSurfaceTrails, matchesTrailPattern } from '../surface-filter.js';
+import { signal } from '../signal.js';
+import { trail } from '../trail.js';
+
+const orderPlaced = signal('order.placed', {
+  payload: z.object({ orderId: z.string() }),
+});
+
+const publicTrail = trail('entity.show', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'read',
+});
+
+const nestedTrail = trail('entity.admin.audit', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+});
+
+const internalTrail = trail('entity.secret.rotate', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  visibility: 'internal',
+});
+
+const legacyInternalTrail = trail('entity.legacy.rotate', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  meta: { internal: true },
+});
+
+const bareEntityTrail = trail('entity', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+});
+
+const otherTrail = trail('other', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+});
+
+const consumerTrail = trail('notify.email', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  on: [orderPlaced],
+});
+
+describe('matchesTrailPattern', () => {
+  test('exact trail IDs match directly', () => {
+    expect(matchesTrailPattern('entity.show', 'entity.show')).toBe(true);
+  });
+
+  test('* matches a single dotted segment', () => {
+    expect(matchesTrailPattern('entity.show', 'entity.*')).toBe(true);
+    expect(matchesTrailPattern('entity.admin.show', 'entity.*')).toBe(false);
+  });
+
+  test('** matches any remaining dotted depth', () => {
+    expect(matchesTrailPattern('entity.admin.show', 'entity.**')).toBe(true);
+    expect(matchesTrailPattern('entity.show', 'entity.**')).toBe(true);
+  });
+
+  test('** terminal segment matches entity and all descendants', () => {
+    // Zero-remaining-segments case: bare parent matches entity.**.
+    expect(matchesTrailPattern('entity', 'entity.**')).toBe(true);
+    // One-remaining-segment case for completeness.
+    expect(matchesTrailPattern('entity.read', 'entity.**')).toBe(true);
+    // Sibling namespace must not match entity.**.
+    expect(matchesTrailPattern('other', 'entity.**')).toBe(false);
+  });
+});
+
+describe('filterSurfaceTrails', () => {
+  describe('visibility defaults', () => {
+    test('includes public trails by default', () => {
+      expect(filterSurfaceTrails([publicTrail])).toEqual([publicTrail]);
+    });
+
+    test('excludes internal trails by default', () => {
+      expect(filterSurfaceTrails([internalTrail])).toEqual([]);
+    });
+
+    test('does not expose internal trails for wildcard includes', () => {
+      expect(
+        filterSurfaceTrails([internalTrail], { include: ['entity.**'] })
+      ).toEqual([]);
+    });
+
+    test('allows exact include to expose an internal trail', () => {
+      expect(
+        filterSurfaceTrails([internalTrail], {
+          include: ['entity.secret.rotate'],
+        })
+      ).toEqual([internalTrail]);
+    });
+
+    test('legacy meta.internal is treated as internal visibility', () => {
+      // Default filter: legacy internal trails must not leak out.
+      expect(filterSurfaceTrails([legacyInternalTrail])).toEqual([]);
+
+      // Wildcard include must also refuse to expose the legacy internal trail.
+      expect(
+        filterSurfaceTrails([legacyInternalTrail], { include: ['entity.**'] })
+      ).toEqual([]);
+
+      // Explicit exact-id include is the documented escape hatch.
+      expect(
+        filterSurfaceTrails([legacyInternalTrail], {
+          include: ['entity.legacy.rotate'],
+        })
+      ).toEqual([legacyInternalTrail]);
+    });
+  });
+
+  describe('include and exclude patterns', () => {
+    test('exclude patterns remove matches before include narrowing', () => {
+      expect(
+        filterSurfaceTrails([publicTrail], {
+          exclude: ['entity.*'],
+          include: ['entity.show'],
+        })
+      ).toEqual([]);
+    });
+
+    test('include patterns narrow the visible trail set', () => {
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          include: ['entity.**'],
+        })
+      ).toEqual([publicTrail, nestedTrail]);
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          include: ['entity.*'],
+        })
+      ).toEqual([publicTrail]);
+    });
+
+    test('entity.** include matches bare entity and descendants', () => {
+      // Regression guard for the ** terminal-segment zero-depth case.
+      expect(
+        filterSurfaceTrails([bareEntityTrail, publicTrail, otherTrail], {
+          include: ['entity.**'],
+        })
+      ).toEqual([bareEntityTrail, publicTrail]);
+    });
+  });
+
+  describe('intent filtering', () => {
+    test('intent filtering narrows visible trails by behavior class', () => {
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          intent: ['read'],
+        })
+      ).toEqual([publicTrail]);
+
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          intent: ['destroy'],
+        })
+      ).toEqual([nestedTrail]);
+    });
+
+    test('intent filtering composes with glob include patterns using AND logic', () => {
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          include: ['entity.**'],
+          intent: ['read'],
+        })
+      ).toEqual([publicTrail]);
+    });
+
+    test('empty intent filters behave like no filter', () => {
+      expect(
+        filterSurfaceTrails([publicTrail, nestedTrail], {
+          intent: [],
+        })
+      ).toEqual([publicTrail, nestedTrail]);
+    });
+  });
+
+  describe('consumer trails', () => {
+    test('consumer trails are never exposed on trailheads', () => {
+      expect(
+        filterSurfaceTrails([consumerTrail], {
+          include: ['notify.email'],
+        })
+      ).toEqual([]);
+    });
+  });
+});