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

package/src/build.ts

@@ -2,19 +2,20 @@
  * 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 layers, and runs the
+ * `execute` function that validates input, composes gates, and runs the
  * implementation -- all without referencing any HTTP framework types.
  */
 
 import {
   Result,
-  SURFACE_KEY,
+  TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
+  validateEstablishedTopo,
 } from '@ontrails/core';
 import type {
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -26,15 +27,17 @@ import type {
 
 export interface BuildHttpRoutesOptions {
   readonly basePath?: string | undefined;
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  readonly layers?: readonly Layer[] | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly gates?: readonly Gate[] | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
+  /** Set to `false` to skip topo validation while building routes. */
+  readonly validate?: boolean | undefined;
 }
 
 export type HttpMethod = 'GET' | 'POST' | 'DELETE';
@@ -49,19 +52,19 @@ export interface HttpRouteDefinition {
   readonly inputSource: InputSource;
   readonly trail: Trail<unknown, unknown>;
   /**
-   * Validate input, compose layers, and execute the trail implementation.
+   * Validate input, compose gates, 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.
    *
-   * @param signal - Optional AbortSignal from the HTTP request. When provided,
+   * @param abortSignal - Optional AbortSignal from the HTTP request. When provided,
    *   it takes final precedence over any context factory signal, allowing
    *   client-initiated cancellation to propagate into trail execution.
    */
   readonly execute: (
     input: unknown,
     requestId?: string | undefined,
-    signal?: AbortSignal | undefined
+    abortSignal?: AbortSignal | undefined
   ) => Promise<Result<unknown, Error>>;
 }
 
@@ -93,15 +96,15 @@ const deriveInputSource = (method: HttpMethod): InputSource =>
 
 /** Check if a trail should be included (skip internal trails). */
 const shouldInclude = (trail: Trail<unknown, unknown>): boolean =>
-  trail.metadata?.['internal'] !== true;
+  trail.meta?.['internal'] !== true;
 
-/** Build per-request context overrides with the HTTP surface marker. */
-const withHttpSurface = (
+/** Build per-request context overrides with the HTTP trailhead marker. */
+const withHttpTrailhead = (
   requestId: string | undefined
 ): Partial<TrailContextInit> => ({
   ...(requestId === undefined ? {} : { requestId }),
   extensions: {
-    [SURFACE_KEY]: 'http' as const,
+    [TRAILHEAD_KEY]: 'http' as const,
   },
 });
 
@@ -118,17 +121,17 @@ const withHttpSurface = (
 const createExecute =
   (
     t: Trail<unknown, unknown>,
-    layers: readonly Layer[],
+    gates: readonly Gate[],
     options: BuildHttpRoutesOptions
   ): HttpRouteDefinition['execute'] =>
-  (input, requestId, signal) =>
+  (input, requestId, abortSignal) =>
     executeTrail(t, input, {
+      abortSignal,
       configValues: options.configValues,
       createContext: options.createContext,
-      ctx: withHttpSurface(requestId),
-      layers,
-      services: options.services,
-      signal,
+      ctx: withHttpTrailhead(requestId),
+      gates,
+      provisions: options.provisions,
     });
 
 // ---------------------------------------------------------------------------
@@ -143,13 +146,13 @@ const eligibleTrails = (app: Topo): Trail<unknown, unknown>[] =>
 const buildRoute = (
   trail: Trail<unknown, unknown>,
   basePath: string,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildHttpRoutesOptions
 ): HttpRouteDefinition => {
   const method = deriveMethod(trail);
   const path = derivePath(basePath, trail.id);
   return {
-    execute: createExecute(trail, layers, options),
+    execute: createExecute(trail, gates, options),
     inputSource: deriveInputSource(method),
     method,
     path,
@@ -190,14 +193,14 @@ const registerRoute = (
 const accumulateRoutes = (
   trails: Trail<unknown, unknown>[],
   basePath: string,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildHttpRoutesOptions
 ): Result<HttpRouteDefinition[], Error> => {
   const routes: HttpRouteDefinition[] = [];
   const seenRoutes = new Map<string, string>();
 
   for (const trail of trails) {
-    const route = buildRoute(trail, basePath, layers, options);
+    const route = buildRoute(trail, basePath, gates, options);
     const registered = registerRoute(route, seenRoutes, routes);
     if (registered.isErr()) {
       return registered;
@@ -218,7 +221,7 @@ 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, layers, and runs the implementation
+ * - An `execute` function that validates, gates, and runs the implementation
  *
  * Returns `Result.err(ValidationError)` if two trails derive the same
  * (method, path) pair. Returns `Result.ok(routes)` on success.
@@ -227,7 +230,14 @@ export const buildHttpRoutes = (
   app: Topo,
   options: BuildHttpRoutesOptions = {}
 ): Result<HttpRouteDefinition[], Error> => {
+  if (options.validate !== false) {
+    const validated = validateEstablishedTopo(app);
+    if (validated.isErr()) {
+      return Result.err(validated.error);
+    }
+  }
+
   const basePath = (options.basePath ?? '').replace(/\/+$/, '');
-  const layers = options.layers ?? [];
-  return accumulateRoutes(eligibleTrails(app), basePath, layers, options);
+  const gates = options.gates ?? [];
+  return accumulateRoutes(eligibleTrails(app), basePath, gates, options);
 };

package/src/hono/__tests__/{blaze.test.ts → trailhead.test.ts}

@@ -4,55 +4,55 @@ import {
   InternalError,
   NotFoundError,
   Result,
-  service,
+  provision,
   trail,
   topo,
 } from '@ontrails/core';
-import type { Layer } from '@ontrails/core';
+import type { Gate } from '@ontrails/core';
 import { z } from 'zod';
 
-import { blaze } from '../blaze.js';
+import { trailhead } from '../trailhead.js';
 
 // ---------------------------------------------------------------------------
 // Test trails
 // ---------------------------------------------------------------------------
 
 const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ reply: input.message }),
   description: 'Echo a message back',
   input: z.object({ message: z.string() }),
   intent: 'read',
   output: z.object({ reply: z.string() }),
-  run: (input) => Result.ok({ reply: input.message }),
 });
 
 const createTrail = trail('item.create', {
+  blaze: (input) => Result.ok({ id: '123', name: input.name }),
   description: 'Create an item',
   input: z.object({ name: z.string() }),
   output: z.object({ id: z.string(), name: z.string() }),
-  run: (input) => Result.ok({ id: '123', name: input.name }),
 });
 
 const deleteTrail = trail('item.delete', {
+  blaze: (_input) => Result.ok({ deleted: true }),
   description: 'Delete an item',
   input: z.object({ id: z.string() }),
   intent: 'destroy',
-  run: (_input) => Result.ok({ deleted: true }),
 });
 
 const notFoundTrail = trail('item.get', {
+  blaze: (_input) => Result.err(new NotFoundError('Item not found')),
   description: 'Get an item that does not exist',
   input: z.object({ id: z.string() }),
   intent: 'read',
-  run: (_input) => Result.err(new NotFoundError('Item not found')),
 });
 
 const internalTrail = trail('crash', {
+  blaze: () => Result.err(new InternalError('Something broke')),
   description: 'Always fails with internal error',
   input: z.object({}),
-  run: () => Result.err(new InternalError('Something broke')),
 });
 
-const dbService = service('db.main', {
+const dbProvision = provision('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
@@ -65,7 +65,7 @@ const dbService = service('db.main', {
 
 /** Make a request against a Hono test app. */
 const request = (
-  app: Awaited<ReturnType<typeof blaze>>,
+  app: Awaited<ReturnType<typeof trailhead>>,
   method: string,
   path: string,
   body?: Record<string, unknown>,
@@ -82,7 +82,7 @@ const request = (
 
 /** Make a request with a raw string body. */
 const requestRaw = (
-  app: Awaited<ReturnType<typeof blaze>>,
+  app: Awaited<ReturnType<typeof trailhead>>,
   method: string,
   path: string,
   rawBody: string,
@@ -100,29 +100,31 @@ const requestRaw = (
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('blaze (Hono adapter)', () => {
+describe('trailhead (Hono connector)', () => {
   describe('validation', () => {
-    test('blaze throws on invalid topo', async () => {
+    test('trailhead throws on invalid topo', async () => {
       const t = trail('broken', {
-        follow: ['nonexistent.trail'],
+        blaze: () => Result.ok({}),
+        crosses: ['nonexistent.trail'],
         input: z.object({}),
         output: z.object({}),
-        run: () => Result.ok({}),
       });
       const app = topo('test', { t });
-      await expect(blaze(app, { serve: false })).rejects.toThrow(/validation/i);
+      await expect(trailhead(app, { serve: false })).rejects.toThrow(
+        /validation/i
+      );
     });
 
-    test('blaze skips validation when validate: false', async () => {
+    test('trailhead skips validation when validate: false', async () => {
       const t = trail('broken', {
-        follow: ['nonexistent.trail'],
+        blaze: () => Result.ok({}),
+        crosses: ['nonexistent.trail'],
         input: z.object({}),
         output: z.object({}),
-        run: () => Result.ok({}),
       });
       const app = topo('test', { t });
       await expect(
-        blaze(app, { serve: false, validate: false })
+        trailhead(app, { serve: false, validate: false })
       ).resolves.toBeDefined();
     });
   });
@@ -130,7 +132,7 @@ describe('blaze (Hono adapter)', () => {
   describe('GET handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/echo?message=hello');
       expect(res.status).toBe(200);
@@ -141,7 +143,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 on invalid input', async () => {
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/echo');
       expect(res.status).toBe(400);
@@ -155,7 +157,7 @@ describe('blaze (Hono adapter)', () => {
   describe('POST handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/item/create', {
         name: 'Widget',
@@ -168,7 +170,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 on invalid input', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/item/create', {});
       expect(res.status).toBe(400);
@@ -179,14 +181,14 @@ describe('blaze (Hono adapter)', () => {
 
     test('POST with empty input schema succeeds without a body', async () => {
       const emptyWriteTrail = trail('empty.write', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
         intent: 'write',
         output: z.object({ ok: z.boolean() }),
-        run: () => Result.ok({ ok: true }),
       });
 
       const app = topo('testapp', { emptyWriteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       // No body, no Content-Type header — mirrors a client that obeys the
       // OpenAPI spec (no requestBody declared for empty-input POST routes).
@@ -201,7 +203,7 @@ describe('blaze (Hono adapter)', () => {
   describe('DELETE handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { deleteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'DELETE', '/item/delete', {
         id: 'abc',
@@ -216,7 +218,7 @@ describe('blaze (Hono adapter)', () => {
   describe('error mapping', () => {
     test('NotFoundError maps to 404', async () => {
       const app = topo('testapp', { notFoundTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/item/get?id=missing');
       expect(res.status).toBe(404);
@@ -228,7 +230,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('InternalError maps to 500', async () => {
       const app = topo('testapp', { internalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/crash', {});
       expect(res.status).toBe(500);
@@ -239,14 +241,14 @@ describe('blaze (Hono adapter)', () => {
 
     test('thrown exceptions map to 500', async () => {
       const throwTrail = trail('throw', {
-        input: z.object({}),
-        run: () => {
+        blaze: () => {
           throw new Error('unexpected crash');
         },
+        input: z.object({}),
       });
 
       const app = topo('testapp', { throwTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/throw', {});
       expect(res.status).toBe(500);
@@ -256,12 +258,12 @@ describe('blaze (Hono adapter)', () => {
     });
   });
 
-  describe('layers', () => {
-    test('layers compose around trail execution', async () => {
+  describe('gates', () => {
+    test('gates compose around trail execution', async () => {
       const calls: string[] = [];
 
-      const testLayer: Layer = {
-        name: 'test-layer',
+      const testGate: Gate = {
+        name: 'test-gate',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             calls.push('before');
@@ -273,7 +275,7 @@ describe('blaze (Hono adapter)', () => {
       };
 
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { layers: [testLayer], serve: false });
+      const hono = await trailhead(app, { gates: [testGate], serve: false });
 
       const res = await request(hono, 'GET', '/echo?message=hi');
       expect(res.status).toBe(200);
@@ -284,7 +286,7 @@ describe('blaze (Hono adapter)', () => {
   describe('malformed JSON body', () => {
     test('returns 400 for invalid JSON in POST body', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await requestRaw(hono, 'POST', '/item/create', '{invalid');
       expect(res.status).toBe(400);
@@ -297,7 +299,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 for invalid JSON in DELETE body', async () => {
       const app = topo('testapp', { deleteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await requestRaw(hono, 'DELETE', '/item/delete', 'not-json');
       expect(res.status).toBe(400);
@@ -310,13 +312,13 @@ describe('blaze (Hono adapter)', () => {
   describe('query param parsing', () => {
     test('numeric-looking string is preserved as string', async () => {
       const stringIdTrail = trail('lookup', {
+        blaze: (input) => Result.ok({ id: input.id }),
         input: z.object({ id: z.string() }),
         intent: 'read',
-        run: (input) => Result.ok({ id: input.id }),
       });
 
       const app = topo('testapp', { stringIdTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/lookup?id=00123');
       expect(res.status).toBe(200);
@@ -327,13 +329,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('repeated keys become arrays', async () => {
       const tagsTrail = trail('tags', {
+        blaze: (input) => Result.ok({ tags: input.tags }),
         input: z.object({ tags: z.array(z.string()) }),
         intent: 'read',
-        run: (input) => Result.ok({ tags: input.tags }),
       });
 
       const app = topo('testapp', { tagsTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/tags?tags=a&tags=b');
       expect(res.status).toBe(200);
@@ -344,13 +346,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('single value is wrapped in array when schema expects z.array()', async () => {
       const tagsTrail = trail('tags.single', {
+        blaze: (input) => Result.ok({ tags: input.tags }),
         input: z.object({ tags: z.array(z.string()) }),
         intent: 'read',
-        run: (input) => Result.ok({ tags: input.tags }),
       });
 
       const app = topo('testapp', { tagsTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/tags/single?tags=foo');
       expect(res.status).toBe(200);
@@ -361,13 +363,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('single value stays scalar when schema expects a string', async () => {
       const nameTrail = trail('name.check', {
+        blaze: (input) => Result.ok({ name: input.name }),
         input: z.object({ name: z.string() }),
         intent: 'read',
-        run: (input) => Result.ok({ name: input.name }),
       });
 
       const app = topo('testapp', { nameTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/name/check?name=bar');
       expect(res.status).toBe(200);
@@ -378,13 +380,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('optional array field with single value is wrapped in array', async () => {
       const optArrayTrail = trail('opt.array', {
+        blaze: (input) => Result.ok({ ids: input.ids }),
         input: z.object({ ids: z.array(z.string()).optional() }),
         intent: 'read',
-        run: (input) => Result.ok({ ids: input.ids }),
       });
 
       const app = topo('testapp', { optArrayTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/opt/array?ids=one');
       expect(res.status).toBe(200);
@@ -399,17 +401,17 @@ describe('blaze (Hono adapter)', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.check', {
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
+          return Result.ok({ ok: true });
+        },
         input: z.object({}),
         intent: 'read',
         output: z.object({ ok: z.boolean() }),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
-          return Result.ok({ ok: true });
-        },
       });
 
       const app = topo('testapp', { signalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/signal/check');
       expect(res.status).toBe(200);
@@ -420,17 +422,17 @@ describe('blaze (Hono adapter)', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.aborted', {
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
+          return Result.ok({ ok: true });
+        },
         input: z.object({}),
         intent: 'read',
         output: z.object({ ok: z.boolean() }),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
-          return Result.ok({ ok: true });
-        },
       });
 
       const app = topo('testapp', { signalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const controller = new AbortController();
       controller.abort();
@@ -453,16 +455,16 @@ describe('blaze (Hono adapter)', () => {
       let capturedRequestId: string | undefined;
 
       const ctxTrail = trail('ctx.check', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedRequestId = ctx.requestId;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/ctx/check', undefined, {
         'X-Request-ID': 'custom-req-123',
@@ -476,20 +478,20 @@ describe('blaze (Hono adapter)', () => {
       let contextUsed = false;
 
       const ctxTrail = trail('ctx.custom', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           contextUsed = ctx.extensions?.['custom'] === true;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
-      const hono = await blaze(app, {
+      const hono = await trailhead(app, {
         createContext: () => ({
+          abortSignal: new AbortController().signal,
           extensions: { custom: true },
           requestId: 'test-id',
-          signal: new AbortController().signal,
         }),
         serve: false,
       });
@@ -499,23 +501,23 @@ describe('blaze (Hono adapter)', () => {
       expect(contextUsed).toBe(true);
     });
 
-    test('service overrides reach the trail through blaze()', async () => {
-      const serviceTrail = trail('service.check', {
+    test('provision overrides reach the trail through trailhead()', async () => {
+      const provisionTrail = trail('provision.check', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: dbProvision.from(ctx).source as string }),
         input: z.object({}),
         intent: 'read',
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ source: dbService.from(ctx).source as string }),
-        services: [dbService],
+        provisions: [dbProvision],
       });
 
-      const app = topo('testapp', { dbService, serviceTrail });
-      const hono = await blaze(app, {
+      const app = topo('testapp', { dbProvision, provisionTrail });
+      const hono = await trailhead(app, {
+        provisions: { 'db.main': { source: 'override' } },
         serve: false,
-        services: { 'db.main': { source: 'override' } },
       });
 
-      const res = await request(hono, 'GET', '/service/check');
+      const res = await request(hono, 'GET', '/provision/check');
       expect(res.status).toBe(200);
 
       const json = await res.json();

package/src/hono/index.ts

@@ -1 +1 @@
-export { blaze, type BlazeHttpOptions } from './blaze.js';
+export { trailhead, type TrailheadHttpOptions } from './trailhead.js';