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

package/src/__tests__/build.test.ts

@@ -5,15 +5,16 @@ import {
   NotFoundError,
   Result,
   TRAILHEAD_KEY,
-  provision,
+  resource,
+  signal,
   ValidationError,
   trail,
   topo,
 } from '@ontrails/core';
-import type { Gate } from '@ontrails/core';
+import type { Layer, TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
-import { buildHttpRoutes } from '../build.js';
+import { deriveHttpRoutes } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Test trails
@@ -54,29 +55,40 @@ const internalTrail = trail('crash', {
   input: z.object({}),
 });
 
-const internalMetaTrail = trail('secret', {
+const internalVisibilityTrail = trail('secret', {
   blaze: () => Result.ok({ ok: true }),
   description: 'Internal trail that should be skipped',
   input: z.object({}),
-  meta: { internal: true },
+  visibility: 'internal',
 });
 
-const dbProvision = provision('db.main', {
+const dbResource = resource('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
     }),
 });
 
+const orderPlaced = signal('order.placed', {
+  payload: z.object({ orderId: z.string() }),
+});
+
+const requireFire = (fire: TrailContext['fire']) => {
+  if (!fire) {
+    throw new Error('Expected ctx.fire to be bound');
+  }
+  return fire;
+};
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('buildHttpRoutes', () => {
+describe('deriveHttpRoutes', () => {
   describe('method derivation', () => {
     test('intent: read maps to GET', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       const routes = result.value;
@@ -86,7 +98,7 @@ describe('buildHttpRoutes', () => {
 
     test('intent: destroy maps to DELETE', () => {
       const app = topo('testapp', { deleteTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       const routes = result.value;
@@ -96,7 +108,7 @@ describe('buildHttpRoutes', () => {
 
     test('default intent (write) maps to POST', () => {
       const app = topo('testapp', { createTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       const routes = result.value;
@@ -108,7 +120,7 @@ describe('buildHttpRoutes', () => {
   describe('path derivation', () => {
     test('dotted ID becomes slashed path', () => {
       const app = topo('testapp', { createTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.path).toBe('/item/create');
@@ -116,7 +128,7 @@ describe('buildHttpRoutes', () => {
 
     test('simple ID becomes /id', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.path).toBe('/echo');
@@ -124,7 +136,7 @@ describe('buildHttpRoutes', () => {
 
     test('basePath is prepended', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app, { basePath: '/api/v1' });
+      const result = deriveHttpRoutes(app, { basePath: '/api/v1' });
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.path).toBe('/api/v1/echo');
@@ -132,7 +144,7 @@ describe('buildHttpRoutes', () => {
 
     test('basePath trailing slash is normalized', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app, { basePath: '/api/v1/' });
+      const result = deriveHttpRoutes(app, { basePath: '/api/v1/' });
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.path).toBe('/api/v1/echo');
@@ -142,7 +154,7 @@ describe('buildHttpRoutes', () => {
   describe('input source derivation', () => {
     test('GET routes use query input source', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.inputSource).toBe('query');
@@ -150,7 +162,7 @@ describe('buildHttpRoutes', () => {
 
     test('POST routes use body input source', () => {
       const app = topo('testapp', { createTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.inputSource).toBe('body');
@@ -158,7 +170,7 @@ describe('buildHttpRoutes', () => {
 
     test('DELETE routes use body input source', () => {
       const app = topo('testapp', { deleteTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.inputSource).toBe('body');
@@ -167,8 +179,77 @@ describe('buildHttpRoutes', () => {
 
   describe('filtering', () => {
     test('internal trails are skipped', () => {
-      const app = topo('testapp', { echoTrail, internalMetaTrail });
-      const result = buildHttpRoutes(app);
+      const app = topo('testapp', { echoTrail, internalVisibilityTrail });
+      const result = deriveHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.trailId).toBe('echo');
+    });
+
+    test('exact include can expose an internal trail', () => {
+      const app = topo('testapp', { echoTrail, internalVisibilityTrail });
+      const result = deriveHttpRoutes(app, { include: ['secret'] });
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.trailId).toBe('secret');
+    });
+
+    test('wildcard include does not expose internal trails', () => {
+      const app = topo('testapp', { echoTrail, internalVisibilityTrail });
+      const result = deriveHttpRoutes(app, { include: ['**'] });
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.trailId).toBe('echo');
+    });
+
+    test('exclude patterns win before include narrowing', () => {
+      const app = topo('testapp', { deleteTrail, echoTrail });
+      const result = deriveHttpRoutes(app, {
+        exclude: ['item.**'],
+        include: ['echo', 'item.delete'],
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value.map((route) => route.trailId)).toEqual(['echo']);
+    });
+
+    test('intent filters narrow the route table', () => {
+      const app = topo('testapp', { deleteTrail, echoTrail });
+      const result = deriveHttpRoutes(app, { intent: ['read'] });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value.map((route) => route.trailId)).toEqual(['echo']);
+    });
+
+    test('intent filters compose with include patterns using AND logic', () => {
+      const app = topo('testapp', { deleteTrail, echoTrail });
+      const result = deriveHttpRoutes(app, {
+        include: ['item.*', 'echo'],
+        intent: ['destroy'],
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value.map((route) => route.trailId)).toEqual([
+        'item.delete',
+      ]);
+    });
+
+    test('consumer trails (on: [...]) are skipped', () => {
+      const consumerTrail = trail('notify.email', {
+        blaze: (input: { orderId: string }) =>
+          Result.ok({ delivered: true, orderId: input.orderId }),
+        description: 'Send email on order placed',
+        input: z.object({ orderId: z.string() }),
+        on: ['order.placed'],
+      });
+      const app = topo('testapp', { consumerTrail, echoTrail, orderPlaced });
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       const routes = result.value;
@@ -180,7 +261,7 @@ describe('buildHttpRoutes', () => {
   describe('route definition shape', () => {
     test('includes trail reference', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value[0]?.trail).toBe(echoTrail);
@@ -188,7 +269,7 @@ describe('buildHttpRoutes', () => {
 
     test('execute is a function', () => {
       const app = topo('testapp', { echoTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(typeof result.value[0]?.execute).toBe('function');
@@ -198,7 +279,7 @@ describe('buildHttpRoutes', () => {
   describe('execute', () => {
     test('returns ok Result on valid input', async () => {
       const app = topo('testapp', { echoTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -210,7 +291,7 @@ describe('buildHttpRoutes', () => {
 
     test('returns err Result on invalid input', async () => {
       const app = topo('testapp', { echoTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -221,7 +302,7 @@ describe('buildHttpRoutes', () => {
 
     test('returns err Result from trail error', async () => {
       const app = topo('testapp', { notFoundTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -233,7 +314,7 @@ describe('buildHttpRoutes', () => {
 
     test('returns err Result from internal error', async () => {
       const app = topo('testapp', { internalTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -251,7 +332,7 @@ describe('buildHttpRoutes', () => {
         input: z.object({}),
       });
       const app = topo('testapp', { throwingTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -264,7 +345,7 @@ describe('buildHttpRoutes', () => {
 
     test('returns err Result when createContext throws', async () => {
       const app = topo('testapp', { echoTrail });
-      const buildResult = buildHttpRoutes(app, {
+      const buildResult = deriveHttpRoutes(app, {
         createContext: () => {
           throw new Error('context creation failed');
         },
@@ -279,6 +360,41 @@ describe('buildHttpRoutes', () => {
       expect(result?.error?.message).toBe('context creation failed');
     });
 
+    test('passes topo to executeTrail so HTTP-invoked producers can fan out', async () => {
+      const captured: string[] = [];
+      const consumer = trail('notify.email', {
+        blaze: (input: { orderId: string }) => {
+          captured.push(input.orderId);
+          return Result.ok({ delivered: true });
+        },
+        input: z.object({ orderId: z.string() }),
+        on: ['order.placed'],
+      });
+      const producer = trail('order.create', {
+        blaze: async (input: { orderId: string }, ctx) => {
+          const fired = await requireFire(ctx.fire)('order.placed', {
+            orderId: input.orderId,
+          });
+          return fired.match({
+            err: (error) => Result.err(error),
+            ok: () => Result.ok({ ok: true }),
+          });
+        },
+        fires: ['order.placed'],
+        input: z.object({ orderId: z.string() }),
+      });
+      const app = topo('signal-http', { consumer, orderPlaced, producer });
+      const buildResult = deriveHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({ orderId: 'o-http' });
+
+      expect(result?.isOk()).toBe(true);
+      expect(captured).toEqual(['o-http']);
+    });
+
     test('passes requestId to context', async () => {
       let capturedRequestId: string | undefined;
 
@@ -292,7 +408,7 @@ describe('buildHttpRoutes', () => {
       });
 
       const app = topo('testapp', { ctxTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -314,7 +430,7 @@ describe('buildHttpRoutes', () => {
       });
 
       const app = topo('testapp', { ctxTrail });
-      const buildResult = buildHttpRoutes(app);
+      const buildResult = deriveHttpRoutes(app);
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -324,18 +440,18 @@ describe('buildHttpRoutes', () => {
       expect(capturedRequestId).not.toBe('');
     });
 
-    test('forwards provision overrides into executeTrail', async () => {
-      const provisionTrail = trail('provision.check', {
+    test('forwards resource overrides into executeTrail', async () => {
+      const resourceTrail = trail('resource.check', {
         blaze: (_input, ctx) =>
-          Result.ok({ source: dbProvision.from(ctx).source as string }),
+          Result.ok({ source: dbResource.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        provisions: [dbProvision],
+        resources: [dbResource],
       });
 
-      const app = topo('testapp', { provisionTrail });
-      const buildResult = buildHttpRoutes(app, {
-        provisions: { 'db.main': { source: 'override' } },
+      const app = topo('testapp', { dbResource, resourceTrail });
+      const buildResult = deriveHttpRoutes(app, {
+        resources: { 'db.main': { source: 'override' } },
       });
 
       expect(buildResult.isOk()).toBe(true);
@@ -347,12 +463,12 @@ describe('buildHttpRoutes', () => {
     });
   });
 
-  describe('gates', () => {
-    test('gates compose around trail execution', async () => {
+  describe('layers', () => {
+    test('layers compose around trail execution', async () => {
       const calls: string[] = [];
 
-      const testGate: Gate = {
-        name: 'test-gate',
+      const testGate: Layer = {
+        name: 'test-layer',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             calls.push('before');
@@ -364,7 +480,7 @@ describe('buildHttpRoutes', () => {
       };
 
       const app = topo('testapp', { echoTrail });
-      const buildResult = buildHttpRoutes(app, { gates: [testGate] });
+      const buildResult = deriveHttpRoutes(app, { layers: [testGate] });
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -391,7 +507,7 @@ describe('buildHttpRoutes', () => {
       });
 
       const app = topo('testapp', { ctxTrail });
-      const buildResult = buildHttpRoutes(app, {
+      const buildResult = deriveHttpRoutes(app, {
         createContext: () => ({
           abortSignal: new AbortController().signal,
           extensions: { custom: true },
@@ -427,7 +543,7 @@ describe('buildHttpRoutes', () => {
         intent: 'read',
       });
       const app = topo('testapp', { dotTrail, slashTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isErr()).toBe(true);
       expect(result.error).toBeInstanceOf(ValidationError);
@@ -450,7 +566,7 @@ describe('buildHttpRoutes', () => {
         input: z.object({ name: z.string() }),
       });
       const app = topo('testapp', { createItem, getItem });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isOk()).toBe(true);
       expect(result.value).toHaveLength(2);
@@ -470,10 +586,25 @@ describe('buildHttpRoutes', () => {
         intent: 'read',
       });
       const app = topo('testapp', { dotTrail, slashTrail });
-      const result = buildHttpRoutes(app);
+      const result = deriveHttpRoutes(app);
 
       expect(result.isErr()).toBe(true);
       expect(result.error?.message).toContain('entity');
     });
   });
+
+  describe('established graph enforcement', () => {
+    test('returns err when draft contamination remains', () => {
+      const draftTrail = trail('entity.export', {
+        blaze: () => Result.ok({ ok: true }),
+        crosses: ['_draft.entity.prepare'],
+        input: z.object({}),
+      });
+
+      const result = deriveHttpRoutes(topo('testapp', { draftTrail }));
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/draft/i);
+    });
+  });
 });

package/src/__tests__/derive.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { deriveHttpRoutes } from '../build.js';
+
+const unwrapOk = <T>(result: Result<T, Error>): T =>
+  result.match({
+    err: (error) => {
+      throw error;
+    },
+    ok: (value) => value,
+  });
+
+describe('deriveHttpRoutes', () => {
+  test('aliases the HTTP projection API', () => {
+    const graph = topo('testapp', {
+      echo: trail('echo', {
+        blaze: (input: { message: string }) =>
+          Result.ok({ reply: input.message }),
+        input: z.object({ message: z.string() }),
+        intent: 'read',
+        output: z.object({ reply: z.string() }),
+      }),
+    });
+
+    const routes = unwrapOk(deriveHttpRoutes(graph));
+    expect(routes[0]?.path).toBe('/echo');
+  });
+});

package/src/build.ts

@@ -2,7 +2,7 @@
  * Build framework-agnostic HTTP route definitions from a Trails topo.
  *
  * Each route definition describes the path, method, input source, and an
- * `execute` function that validates input, composes gates, and runs the
+ * `execute` function that validates input, composes layers, and runs the
  * implementation -- all without referencing any HTTP framework types.
  */
 
@@ -11,10 +11,13 @@ import {
   TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
+  filterSurfaceTrails,
+  validateEstablishedTopo,
 } from '@ontrails/core';
 import type {
-  Gate,
-  ProvisionOverrideMap,
+  Intent,
+  Layer,
+  ResourceOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -24,17 +27,22 @@ import type {
 // Public types
 // ---------------------------------------------------------------------------
 
-export interface BuildHttpRoutesOptions {
+export interface DeriveHttpRoutesOptions {
   readonly basePath?: string | undefined;
-  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+  /** Config values for resources that declare a `config` schema, keyed by resource ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  readonly gates?: readonly Gate[] | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly include?: readonly string[] | undefined;
+  readonly intent?: readonly Intent[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  /** Set to `false` to skip topo validation while building routes. */
+  readonly validate?: boolean | undefined;
 }
 
 export type HttpMethod = 'GET' | 'POST' | 'DELETE';
@@ -47,9 +55,9 @@ export interface HttpRouteDefinition {
   readonly path: string;
   readonly trailId: string;
   readonly inputSource: InputSource;
-  readonly trail: Trail<unknown, unknown>;
+  readonly trail: Trail<unknown, unknown, unknown>;
   /**
-   * Validate input, compose gates, and execute the trail implementation.
+   * Validate input, compose layers, and execute the trail implementation.
    *
    * The caller is responsible for parsing raw input from the request and
    * mapping the Result to an HTTP response. This function is framework-agnostic.
@@ -77,7 +85,7 @@ const intentToMethod: Record<string, HttpMethod> = {
 };
 
 /** Derive HTTP method from trail intent. */
-const deriveMethod = (trail: Trail<unknown, unknown>): HttpMethod =>
+const deriveMethod = (trail: Trail<unknown, unknown, unknown>): HttpMethod =>
   intentToMethod[trail.intent] ?? 'POST';
 
 /** Derive HTTP path from trail ID: `entity.show` -> `/entity/show`. */
@@ -91,10 +99,6 @@ const derivePath = (basePath: string, trailId: string): string => {
 const deriveInputSource = (method: HttpMethod): InputSource =>
   method === 'GET' ? 'query' : 'body';
 
-/** Check if a trail should be included (skip internal trails). */
-const shouldInclude = (trail: Trail<unknown, unknown>): boolean =>
-  trail.meta?.['internal'] !== true;
-
 /** Build per-request context overrides with the HTTP trailhead marker. */
 const withHttpTrailhead = (
   requestId: string | undefined
@@ -117,9 +121,10 @@ const withHttpTrailhead = (
  */
 const createExecute =
   (
-    t: Trail<unknown, unknown>,
-    gates: readonly Gate[],
-    options: BuildHttpRoutesOptions
+    graph: Topo,
+    t: Trail<unknown, unknown, unknown>,
+    layers: readonly Layer[],
+    options: DeriveHttpRoutesOptions
   ): HttpRouteDefinition['execute'] =>
   (input, requestId, abortSignal) =>
     executeTrail(t, input, {
@@ -127,8 +132,9 @@ const createExecute =
       configValues: options.configValues,
       createContext: options.createContext,
       ctx: withHttpTrailhead(requestId),
-      gates,
-      provisions: options.provisions,
+      layers,
+      resources: options.resources,
+      topo: graph,
     });
 
 // ---------------------------------------------------------------------------
@@ -136,20 +142,28 @@ const createExecute =
 // ---------------------------------------------------------------------------
 
 /** Filter topo items to eligible trails. */
-const eligibleTrails = (app: Topo): Trail<unknown, unknown>[] =>
-  app.list().filter((trail) => shouldInclude(trail));
+const eligibleTrails = (
+  graph: Topo,
+  options: DeriveHttpRoutesOptions
+): Trail<unknown, unknown, unknown>[] =>
+  filterSurfaceTrails(graph.list(), {
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+  });
 
 /** Build a single route definition from a trail. */
 const buildRoute = (
-  trail: Trail<unknown, unknown>,
+  graph: Topo,
+  trail: Trail<unknown, unknown, unknown>,
   basePath: string,
-  gates: readonly Gate[],
-  options: BuildHttpRoutesOptions
+  layers: readonly Layer[],
+  options: DeriveHttpRoutesOptions
 ): HttpRouteDefinition => {
   const method = deriveMethod(trail);
   const path = derivePath(basePath, trail.id);
   return {
-    execute: createExecute(trail, gates, options),
+    execute: createExecute(graph, trail, layers, options),
     inputSource: deriveInputSource(method),
     method,
     path,
@@ -188,16 +202,17 @@ const registerRoute = (
 
 /** Accumulate route definitions, returning early on the first collision. */
 const accumulateRoutes = (
-  trails: Trail<unknown, unknown>[],
+  graph: Topo,
+  trails: Trail<unknown, unknown, unknown>[],
   basePath: string,
-  gates: readonly Gate[],
-  options: BuildHttpRoutesOptions
+  layers: readonly Layer[],
+  options: DeriveHttpRoutesOptions
 ): Result<HttpRouteDefinition[], Error> => {
   const routes: HttpRouteDefinition[] = [];
   const seenRoutes = new Map<string, string>();
 
   for (const trail of trails) {
-    const route = buildRoute(trail, basePath, gates, options);
+    const route = buildRoute(graph, trail, basePath, layers, options);
     const registered = registerRoute(route, seenRoutes, routes);
     if (registered.isErr()) {
       return registered;
@@ -218,16 +233,29 @@ const accumulateRoutes = (
  * - An HTTP method derived from intent (read -> GET, write -> POST, destroy -> DELETE)
  * - A path derived from the trail ID (dots become slashes)
  * - An input source derived from the method (GET -> query, others -> body)
- * - An `execute` function that validates, gates, and runs the implementation
+ * - An `execute` function that validates, layers, and runs the implementation
  *
  * Returns `Result.err(ValidationError)` if two trails derive the same
  * (method, path) pair. Returns `Result.ok(routes)` on success.
  */
-export const buildHttpRoutes = (
-  app: Topo,
-  options: BuildHttpRoutesOptions = {}
+export const deriveHttpRoutes = (
+  graph: Topo,
+  options: DeriveHttpRoutesOptions = {}
 ): Result<HttpRouteDefinition[], Error> => {
+  if (options.validate !== false) {
+    const validated = validateEstablishedTopo(graph);
+    if (validated.isErr()) {
+      return Result.err(validated.error);
+    }
+  }
+
   const basePath = (options.basePath ?? '').replace(/\/+$/, '');
-  const gates = options.gates ?? [];
-  return accumulateRoutes(eligibleTrails(app), basePath, gates, options);
+  const layers = options.layers ?? [];
+  return accumulateRoutes(
+    graph,
+    eligibleTrails(graph, options),
+    basePath,
+    layers,
+    options
+  );
 };