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

package/src/build.ts

@@ -2,57 +2,131 @@
  * 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.
  */
 
 import {
+  AuthError,
   Result,
-  TRAILHEAD_KEY,
   ValidationError,
+  buildActivationProvenanceTraceAttrs,
+  collectAttachedTypedLayers,
   executeTrail,
-  validateEstablishedTopo,
+  filterSurfaceTrails,
+  getActivationWherePredicate,
+  getTraceSink,
+  LAYER_FIELD_RESERVED_NAMES,
+  matchesTrailPattern,
+  projectLayerFieldName,
+  TRACE_CONTEXT_KEY,
+  traceContextFromRecord,
+  validateInput,
+  validateWebhookSource,
+  validateSurfaceTopo,
+  verifyWebhookRequest,
+  writeActivationTraceRecord,
+  withActivationProvenance,
+  withSurfaceLayerNames,
+  zodToJsonSchema,
 } from '@ontrails/core';
 import type {
-  Gate,
-  ProvisionOverrideMap,
+  ActivationEntry,
+  ActivationProvenance,
+  ActivationSource,
+  AttachedTypedLayer,
+  BasePermit,
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  TraceContext,
   Topo,
   Trail,
   TrailContextInit,
+  WebhookSource,
+  WebhookVerifyRequest,
 } from '@ontrails/core';
 
+import { deriveHttpInputSource, deriveHttpMethod } from './method.js';
+import type { HttpMethod, InputSource } from './method.js';
+
+export type { HttpMethod, InputSource } from './method.js';
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
 
-export interface BuildHttpRoutesOptions {
+export interface DeriveHttpRoutesOptions extends BaseSurfaceOptions {
   readonly basePath?: string | undefined;
-  /** 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 gates?: readonly Gate[] | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
-  /** Set to `false` to skip topo validation while building routes. */
-  readonly validate?: boolean | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
 }
 
-export type HttpMethod = 'GET' | 'POST' | 'DELETE';
+export type HttpHeaderSource =
+  | Headers
+  | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+export interface HttpExecutionContext {
+  readonly headers?: HttpHeaderSource | undefined;
+}
+
+export interface ResolveHttpPermitInput {
+  readonly authorization?: string | undefined;
+  readonly bearerToken?: string | undefined;
+  readonly headers?: HttpHeaderSource | undefined;
+  readonly requestId?: string | undefined;
+}
 
-/** Input source derived from the HTTP method. */
-export type InputSource = 'query' | 'body';
+export type ResolveHttpPermit = (
+  input: ResolveHttpPermitInput
+) =>
+  | Promise<Result<BasePermit | null | undefined, Error>>
+  | Result<BasePermit | null | undefined, Error>;
 
 export interface HttpRouteDefinition {
   readonly method: HttpMethod;
   readonly path: string;
   readonly trailId: string;
   readonly inputSource: InputSource;
-  readonly trail: Trail<unknown, unknown>;
+  readonly trail: Trail<unknown, unknown, unknown>;
+  /**
+   * JSON Schema for the merged request input (trail input + projected layer
+   * input fields). Empty/undefined when the trail declares no input and no
+   * typed layer is attached. Surface adapters and OpenAPI generators read
+   * this to build the published request shape.
+   *
+   * @see TRL-474.
+   */
+  readonly inputSchema?: Record<string, unknown> | undefined;
+  /**
+   * Per-layer projections describing the parameter names the route accepts
+   * for typed layers and the routing target back onto each layer's input
+   * schema. Empty when the trail has no typed layer attached.
+   *
+   * Surface adapters use this to partition the parsed request into
+   * `{ trailInput, layerInputs }` before invoking `execute`. The `execute`
+   * function published below performs the same partitioning for callers
+   * that pass the full merged record straight through.
+   *
+   * @see TRL-474.
+   */
+  readonly layerInputProjections?: readonly HttpLayerInputProjection[];
+  readonly parseWebhookInput?:
+    | ((rawPayload: unknown) => Result<unknown, Error>)
+    | undefined;
+  readonly verifyWebhook?:
+    | ((request: WebhookVerifyRequest) => Promise<Result<void, Error>>)
+    | undefined;
+  readonly recordWebhookInvalid?:
+    | ((errorCategory?: string | undefined) => Promise<void>)
+    | undefined;
+  readonly webhookSource?: WebhookSource | undefined;
   /**
-   * 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.
@@ -60,11 +134,14 @@ export interface HttpRouteDefinition {
    * @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.
+   * @param context - Optional request context such as headers. When supplied,
+   *   HTTP Bearer credentials can be resolved into `ctx.permit`.
    */
   readonly execute: (
     input: unknown,
     requestId?: string | undefined,
-    abortSignal?: AbortSignal | undefined
+    abortSignal?: AbortSignal | undefined,
+    context?: HttpExecutionContext | undefined
   ) => Promise<Result<unknown, Error>>;
 }
 
@@ -72,16 +149,9 @@ export interface HttpRouteDefinition {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/** Explicit intent → HTTP method mapping. */
-const intentToMethod: Record<string, HttpMethod> = {
-  destroy: 'DELETE',
-  read: 'GET',
-  write: 'POST',
-};
-
 /** Derive HTTP method from trail intent. */
-const deriveMethod = (trail: Trail<unknown, unknown>): HttpMethod =>
-  intentToMethod[trail.intent] ?? 'POST';
+const deriveMethod = (trail: Trail<unknown, unknown, unknown>): HttpMethod =>
+  deriveHttpMethod(trail.intent);
 
 /** Derive HTTP path from trail ID: `entity.show` -> `/entity/show`. */
 const derivePath = (basePath: string, trailId: string): string => {
@@ -90,24 +160,466 @@ const derivePath = (basePath: string, trailId: string): string => {
   return `${base}/${segments}`;
 };
 
-/** Derive input source from HTTP method. */
-const deriveInputSource = (method: HttpMethod): InputSource =>
-  method === 'GET' ? 'query' : 'body';
+/** Build per-request context overrides with the HTTP surface marker. */
+const withHttpSurface = (
+  requestId: string | undefined,
+  layers: readonly Layer[]
+): Partial<TrailContextInit> =>
+  withSurfaceLayerNames(
+    'http',
+    layers,
+    requestId === undefined ? {} : { requestId }
+  );
 
-/** Check if a trail should be included (skip internal trails). */
-const shouldInclude = (trail: Trail<unknown, unknown>): boolean =>
-  trail.meta?.['internal'] !== true;
+const readHeader = (
+  headers: HttpHeaderSource | undefined,
+  name: string
+): string | undefined => {
+  if (headers === undefined) {
+    return undefined;
+  }
+  if (headers instanceof Headers) {
+    return headers.get(name) ?? undefined;
+  }
+  const needle = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== needle || value === undefined) {
+      continue;
+    }
+    return typeof value === 'string' ? value : value[0];
+  }
+  return undefined;
+};
 
-/** Build per-request context overrides with the HTTP trailhead marker. */
-const withHttpTrailhead = (
-  requestId: string | undefined
-): Partial<TrailContextInit> => ({
-  ...(requestId === undefined ? {} : { requestId }),
-  extensions: {
-    [TRAILHEAD_KEY]: 'http' as const,
+const parseBearerAuthorization = (
+  authorization: string | undefined
+): Result<string | undefined, Error> => {
+  if (authorization === undefined || authorization.length === 0) {
+    return Result.ok();
+  }
+  const match = authorization.match(/^Bearer\s+(.+)$/i);
+  const token = match?.[1]?.trim();
+  if (token === undefined || token.length === 0) {
+    return Result.err(
+      new AuthError('Malformed Authorization header; expected Bearer token', {
+        context: { code: 'invalid_authorization_header' },
+      })
+    );
+  }
+  return Result.ok(token);
+};
+
+const isBearerAuthorization = (authorization: string | undefined): boolean =>
+  authorization !== undefined && /^Bearer(?:\s|$)/i.test(authorization.trim());
+
+const shouldResolveHttpPermit = (
+  options: DeriveHttpRoutesOptions,
+  authorization: string | undefined,
+  requiresPermit: boolean
+): boolean =>
+  requiresPermit ||
+  (options.resolvePermit !== undefined && isBearerAuthorization(authorization));
+
+const resolveHttpPermit = async (
+  options: DeriveHttpRoutesOptions,
+  request: HttpExecutionContext | undefined,
+  requestId: string | undefined,
+  requiresPermit: boolean
+): Promise<Result<BasePermit | undefined, Error>> => {
+  const authorization = readHeader(request?.headers, 'authorization');
+  if (!shouldResolveHttpPermit(options, authorization, requiresPermit)) {
+    return Result.ok();
+  }
+  const token = parseBearerAuthorization(authorization);
+  if (token.isErr()) {
+    return token;
+  }
+  if (token.value === undefined) {
+    return Result.ok();
+  }
+  if (options.resolvePermit === undefined) {
+    return Result.ok();
+  }
+  const resolved = await options.resolvePermit({
+    authorization,
+    bearerToken: token.value,
+    headers: request?.headers,
+    requestId,
+  });
+  if (resolved.isErr()) {
+    return resolved;
+  }
+  return Result.ok(resolved.value ?? undefined);
+};
+
+const createWebhookActivationFireId = (): string => {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (typeof randomUUID === 'function') {
+    return randomUUID.call(globalThis.crypto);
+  }
+  return `webhook_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+};
+
+const webhookActivationProvenance = (
+  source: WebhookSource,
+  fireId: string
+): ActivationProvenance => ({
+  fireId,
+  rootFireId: fireId,
+  source: {
+    id: source.id,
+    kind: 'webhook',
+    ...(source.meta === undefined ? {} : { meta: source.meta }),
   },
 });
 
+const webhookActivationTraceAttrs = (
+  source: WebhookSource,
+  activation: ActivationProvenance,
+  trailId: string
+): Readonly<Record<string, unknown>> => ({
+  ...buildActivationProvenanceTraceAttrs(activation),
+  'trails.activation.target_trail.id': trailId,
+  'trails.activation.webhook.method': source.method,
+  'trails.activation.webhook.path': source.path,
+});
+
+const recordWebhookActivationTrace = async (
+  graph: Topo,
+  source: WebhookSource,
+  activation: ActivationProvenance,
+  trailId: string,
+  name: 'activation.webhook' | 'activation.webhook.invalid',
+  status: 'err' | 'ok',
+  errorCategory?: string | undefined
+): Promise<TraceContext | undefined> => {
+  const record = await writeActivationTraceRecord(
+    name,
+    webhookActivationTraceAttrs(source, activation, trailId),
+    status,
+    errorCategory,
+    undefined,
+    graph.observe?.trace ?? getTraceSink()
+  );
+  return record === undefined ? undefined : traceContextFromRecord(record);
+};
+
+/**
+ * Internal recorder signature for webhook invalid traces.
+ *
+ * Unlike the public `HttpRouteDefinition['recordWebhookInvalid']`, this
+ * accepts an `activationFireId` so a single inbound failed request can share
+ * one activation fire ID across every consumer fan-out — letting
+ * observability correlate sibling consumers' invalid records as one
+ * activation root, mirroring the success path.
+ */
+type WebhookInvalidConsumerRecorder = (
+  errorCategory: string | undefined,
+  activationFireId: string
+) => Promise<void>;
+
+const createWebhookInvalidRecorder =
+  (
+    graph: Topo,
+    source: WebhookSource,
+    trailId: string
+  ): WebhookInvalidConsumerRecorder =>
+  async (errorCategory, activationFireId) => {
+    const activation = webhookActivationProvenance(source, activationFireId);
+    await recordWebhookActivationTrace(
+      graph,
+      source,
+      activation,
+      trailId,
+      'activation.webhook.invalid',
+      'err',
+      errorCategory ?? 'validation'
+    );
+  };
+
+/**
+ * Wrap a single-consumer invalid recorder as the public `recordWebhookInvalid`
+ * function. Generates one activation fire ID per inbound failed request,
+ * matching the fan-out behavior so single and merged routes share the same
+ * observability shape.
+ */
+const createWebhookInvalidPublicRecorder =
+  (
+    consumerRecorder: WebhookInvalidConsumerRecorder
+  ): NonNullable<HttpRouteDefinition['recordWebhookInvalid']> =>
+  async (errorCategory = 'validation') =>
+    await consumerRecorder(errorCategory, createWebhookActivationFireId());
+
+const withWebhookActivation = (
+  activation: ActivationProvenance,
+  requestId: string | undefined,
+  traceContext: TraceContext | undefined,
+  layers: readonly Layer[]
+): Partial<TrailContextInit> => {
+  const ctx = withActivationProvenance(
+    withHttpSurface(requestId, layers),
+    activation
+  );
+  return traceContext === undefined
+    ? ctx
+    : {
+        ...ctx,
+        extensions: {
+          ...ctx.extensions,
+          [TRACE_CONTEXT_KEY]: traceContext,
+        },
+      };
+};
+
+// ---------------------------------------------------------------------------
+// Layer input projection (TRL-474)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-layer projection onto an HTTP route's request input.
+ *
+ * `routing` maps the parameter name a consumer sees on the request (a query
+ * key for `intent: 'read'`, a body field for write/destroy) to the authored
+ * field name on the layer's input schema. When no rename was required the
+ * two are the same; on collision the parameter name carries the layer
+ * prefix while the routing target preserves the original field.
+ */
+export interface HttpLayerInputProjection {
+  readonly layerName: string;
+  /** parameterName → originalFieldName for this layer. */
+  readonly routing: ReadonlyMap<string, string>;
+  /** Fragment merged into the route's `inputSchema.properties`. */
+  readonly properties: Readonly<Record<string, unknown>>;
+  /** Field names appended to the route's `inputSchema.required` list. */
+  readonly required: readonly string[];
+}
+
+const buildHttpRenameTarget = (
+  layerName: string,
+  originalName: string
+): string => {
+  if (originalName.length === 0) {
+    return layerName;
+  }
+  const [head, ...rest] = originalName;
+  if (head === undefined) {
+    return layerName;
+  }
+  return `${layerName}${head.toUpperCase()}${rest.join('')}`;
+};
+
+const isJsonObjectSchema = (
+  value: unknown
+): value is { properties?: Record<string, unknown>; required?: string[] } =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const readRequiredFields = (value: unknown): readonly string[] => {
+  if (!isJsonObjectSchema(value) || !Array.isArray(value.required)) {
+    return [];
+  }
+  return value.required.every((field) => typeof field === 'string')
+    ? value.required
+    : [];
+};
+
+const projectHttpLayerInput = (
+  layer: Layer,
+  claimedNames: Set<string>
+): HttpLayerInputProjection => {
+  if (layer.input === undefined) {
+    return {
+      layerName: layer.name,
+      properties: {},
+      required: [],
+      routing: new Map(),
+    };
+  }
+
+  const layerSchema = zodToJsonSchema(layer.input);
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  const routing = new Map<string, string>();
+
+  if (
+    !isJsonObjectSchema(layerSchema) ||
+    layerSchema.properties === undefined
+  ) {
+    return {
+      layerName: layer.name,
+      properties,
+      required,
+      routing,
+    };
+  }
+
+  const requiredSet = new Set<string>(layerSchema.required);
+  for (const [fieldName, fieldSchema] of Object.entries(
+    layerSchema.properties
+  )) {
+    const renamed = buildHttpRenameTarget(layer.name, fieldName);
+    const projection = projectLayerFieldName(
+      layer.name,
+      fieldName,
+      fieldName,
+      renamed,
+      claimedNames,
+      LAYER_FIELD_RESERVED_NAMES
+    );
+    properties[projection.claimedName] = fieldSchema;
+    if (requiredSet.has(fieldName)) {
+      required.push(projection.claimedName);
+    }
+    routing.set(projection.claimedName, projection.routingTarget);
+  }
+
+  return { layerName: layer.name, properties, required, routing };
+};
+
+interface HttpInputProjection {
+  readonly schema: Record<string, unknown> | undefined;
+  readonly projections: readonly HttpLayerInputProjection[];
+}
+
+const projectHttpInputSchema = (
+  trail: Trail<unknown, unknown, unknown>,
+  attachedLayers: readonly AttachedTypedLayer[]
+): HttpInputProjection => {
+  const baseSchema = zodToJsonSchema(trail.input);
+  if (attachedLayers.length === 0) {
+    return { projections: [], schema: baseSchema };
+  }
+
+  const baseProperties =
+    isJsonObjectSchema(baseSchema) && baseSchema.properties !== undefined
+      ? baseSchema.properties
+      : undefined;
+  const baseRequired =
+    isJsonObjectSchema(baseSchema) && Array.isArray(baseSchema.required)
+      ? baseSchema.required
+      : [];
+
+  const claimedNames = new Set<string>(
+    baseProperties === undefined ? [] : Object.keys(baseProperties)
+  );
+
+  const mergedProperties: Record<string, unknown> = {
+    ...baseProperties,
+  };
+  const mergedRequired = [...baseRequired];
+  const projections: HttpLayerInputProjection[] = [];
+
+  for (const { layer } of attachedLayers) {
+    const projection = projectHttpLayerInput(layer, claimedNames);
+    if (projection.routing.size === 0) {
+      continue;
+    }
+    Object.assign(mergedProperties, projection.properties);
+    mergedRequired.push(...projection.required);
+    projections.push(projection);
+  }
+
+  if (projections.length === 0) {
+    return { projections: [], schema: baseSchema };
+  }
+
+  const mergedSchema: Record<string, unknown> = isJsonObjectSchema(baseSchema)
+    ? { ...baseSchema, properties: mergedProperties, type: 'object' }
+    : { properties: mergedProperties, type: 'object' };
+  if (mergedRequired.length > 0) {
+    mergedSchema['required'] = mergedRequired;
+  } else if ('required' in mergedSchema) {
+    delete mergedSchema['required'];
+  }
+
+  return { projections, schema: mergedSchema };
+};
+
+const mergeHttpInputSchemas = (
+  left: Record<string, unknown> | undefined,
+  right: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined => {
+  if (left === undefined) {
+    return right;
+  }
+  if (right === undefined) {
+    return left;
+  }
+  const leftProperties =
+    isJsonObjectSchema(left) && left.properties !== undefined
+      ? left.properties
+      : undefined;
+  const rightProperties =
+    isJsonObjectSchema(right) && right.properties !== undefined
+      ? right.properties
+      : undefined;
+  const merged: Record<string, unknown> = {
+    ...left,
+    ...right,
+    properties: {
+      ...leftProperties,
+      ...rightProperties,
+    },
+    type: 'object',
+  };
+  const required = [
+    ...new Set([...readRequiredFields(left), ...readRequiredFields(right)]),
+  ];
+  if (required.length > 0) {
+    merged['required'] = required;
+  } else {
+    delete merged['required'];
+  }
+  return merged;
+};
+
+/**
+ * Partition a parsed request input into the trail input plus per-layer
+ * inputs, using each layer's routing table.
+ *
+ * Layer-projected parameter names are stripped from the trail input so the
+ * trail's schema validation only ever sees its own fields. A layer that
+ * received no parameters is omitted from `layerInputs` so consumers can
+ * cleanly assert which layers were activated by the request.
+ */
+const partitionHttpInput = (
+  input: unknown,
+  projections: readonly HttpLayerInputProjection[]
+): {
+  readonly trailInput: unknown;
+  readonly layerInputs: Record<string, unknown>;
+} => {
+  if (projections.length === 0 || !isJsonObjectSchema(input)) {
+    return { layerInputs: {}, trailInput: input };
+  }
+  const record = input as Record<string, unknown>;
+  const claimedKeys = new Set<string>();
+  const layerInputs: Record<string, unknown> = {};
+  for (const projection of projections) {
+    const layerInput: Record<string, unknown> = {};
+    let received = false;
+    for (const [paramName, fieldName] of projection.routing) {
+      claimedKeys.add(paramName);
+      const value = record[paramName];
+      if (value === undefined) {
+        continue;
+      }
+      layerInput[fieldName] = value;
+      received = true;
+    }
+    if (received) {
+      layerInputs[projection.layerName] = layerInput;
+    }
+  }
+  const trailInput: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (claimedKeys.has(key)) {
+      continue;
+    }
+    trailInput[key] = value;
+  }
+  return { layerInputs, trailInput };
+};
+
 // ---------------------------------------------------------------------------
 // Execute factory
 // ---------------------------------------------------------------------------
@@ -120,40 +632,225 @@ 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,
+    layerProjections: readonly HttpLayerInputProjection[]
   ): HttpRouteDefinition['execute'] =>
-  (input, requestId, abortSignal) =>
-    executeTrail(t, input, {
+  async (input, requestId, abortSignal, request) => {
+    const { trailInput, layerInputs } = partitionHttpInput(
+      input,
+      layerProjections
+    );
+    const permitResolution = await resolveHttpPermit(
+      options,
+      request,
+      requestId,
+      t.permit !== undefined
+    );
+    if (permitResolution.isErr()) {
+      return Result.err(permitResolution.error);
+    }
+    const permit = permitResolution.value;
+    return await executeTrail(t, trailInput, {
       abortSignal,
       configValues: options.configValues,
       createContext: options.createContext,
-      ctx: withHttpTrailhead(requestId),
-      gates,
-      provisions: options.provisions,
+      ctx: withHttpSurface(requestId, layers),
+      ...(Object.keys(layerInputs).length === 0 ? {} : { layerInputs }),
+      ...(permit === undefined ? {} : { permit }),
+      resources: options.resources,
+      surfaceLayers: layers,
+      topo: graph,
+      topoLayers: graph.layers,
     });
+  };
+
+/**
+ * Internal executor signature used for shared webhook source fan-out.
+ *
+ * Unlike the public `HttpRouteDefinition['execute']`, this accepts an
+ * `activationFireId` so a single inbound request can share one activation
+ * fire ID across every consumer fan-out — letting observability correlate
+ * sibling consumers as one activation root.
+ */
+type WebhookConsumerExecute = (
+  input: unknown,
+  requestId: string | undefined,
+  abortSignal: AbortSignal | undefined,
+  request: HttpExecutionContext | undefined,
+  activationFireId: string
+) => Promise<Result<unknown, Error>>;
+
+const createWebhookConsumerExecute =
+  (
+    graph: Topo,
+    t: Trail<unknown, unknown, unknown>,
+    activationEntry: ActivationEntry,
+    source: WebhookSource,
+    layers: readonly Layer[],
+    options: DeriveHttpRoutesOptions,
+    layerProjections: readonly HttpLayerInputProjection[]
+  ): WebhookConsumerExecute =>
+  async (input, requestId, abortSignal, request, activationFireId) => {
+    const predicate = getActivationWherePredicate(activationEntry.where);
+    if (predicate !== undefined) {
+      let shouldRun = false;
+      try {
+        shouldRun = await predicate(input);
+      } catch (error) {
+        return Result.err(
+          new ValidationError(
+            `Webhook source "${source.id}" activation predicate failed`,
+            { cause: error instanceof Error ? error : new Error(String(error)) }
+          )
+        );
+      }
+      if (!shouldRun) {
+        return Result.ok();
+      }
+    }
+
+    const activation = webhookActivationProvenance(source, activationFireId);
+    const traceContext = await recordWebhookActivationTrace(
+      graph,
+      source,
+      activation,
+      t.id,
+      'activation.webhook',
+      'ok'
+    );
+    const { trailInput, layerInputs } = partitionHttpInput(
+      input,
+      layerProjections
+    );
+    const permitResolution = await resolveHttpPermit(
+      options,
+      request,
+      requestId,
+      t.permit !== undefined
+    );
+    if (permitResolution.isErr()) {
+      return Result.err(permitResolution.error);
+    }
+    const permit = permitResolution.value;
+    return await executeTrail(t, trailInput, {
+      abortSignal,
+      configValues: options.configValues,
+      createContext: options.createContext,
+      ctx: withWebhookActivation(activation, requestId, traceContext, layers),
+      ...(Object.keys(layerInputs).length === 0 ? {} : { layerInputs }),
+      ...(permit === undefined ? {} : { permit }),
+      resources: options.resources,
+      surfaceLayers: layers,
+      topo: graph,
+      topoLayers: graph.layers,
+    });
+  };
+
+/**
+ * Wrap a single-consumer webhook executor as the public `execute` function.
+ *
+ * Generates one activation fire ID per inbound request, matching the fan-out
+ * behavior so single and merged routes share the same observability shape.
+ */
+const createWebhookExecute =
+  (consumerExecute: WebhookConsumerExecute): HttpRouteDefinition['execute'] =>
+  async (input, requestId, abortSignal, request) =>
+    await consumerExecute(
+      input,
+      requestId,
+      abortSignal,
+      request,
+      createWebhookActivationFireId()
+    );
 
 // ---------------------------------------------------------------------------
 // Builder helpers
 // ---------------------------------------------------------------------------
 
 /** 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,
+  });
+
+const isInternalTrail = (trail: Trail<unknown, unknown, unknown>): boolean =>
+  trail.visibility === 'internal' || trail.meta?.['internal'] === true;
+
+const matchesAnyPattern = (
+  trailId: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+
+const passesIncludeFilter = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.length === 0 ||
+  matchesAnyPattern(trailId, include);
+
+const eligibleWebhookTrails = (
+  graph: Topo,
+  options: DeriveHttpRoutesOptions
+): Trail<unknown, unknown, unknown>[] =>
+  graph.list().filter((trail) => {
+    if (isInternalTrail(trail) && !options.include?.includes(trail.id)) {
+      return false;
+    }
+    if (matchesAnyPattern(trail.id, options.exclude)) {
+      return false;
+    }
+    if (!passesIncludeFilter(trail.id, options.include)) {
+      return false;
+    }
+    return (
+      options.intent === undefined ||
+      options.intent.length === 0 ||
+      options.intent.includes(trail.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);
+  const attachedLayers = collectAttachedTypedLayers(
+    graph,
+    trail,
+    options.layers
+  );
+  const inputProjection = projectHttpInputSchema(trail, attachedLayers);
   return {
-    execute: createExecute(trail, gates, options),
-    inputSource: deriveInputSource(method),
+    execute: createExecute(
+      graph,
+      trail,
+      layers,
+      options,
+      inputProjection.projections
+    ),
+    ...(inputProjection.schema === undefined
+      ? {}
+      : { inputSchema: inputProjection.schema }),
+    inputSource: deriveHttpInputSource(method),
+    ...(inputProjection.projections.length === 0
+      ? {}
+      : { layerInputProjections: inputProjection.projections }),
     method,
     path,
     trail,
@@ -161,6 +858,160 @@ const buildRoute = (
   };
 };
 
+const normalizeSourcePath = (basePath: string, sourcePath: string): string => {
+  const base = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  return `${base}${sourcePath}`;
+};
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+type ZodSchemaInput = Parameters<typeof validateInput>[0];
+
+const isZodSchema = (value: unknown): value is ZodSchemaInput =>
+  isObjectRecord(value) && typeof value['safeParse'] === 'function';
+
+const parseOutputSchema = (
+  parse: WebhookSource['parse'] | undefined
+): ZodSchemaInput | undefined => {
+  if (isZodSchema(parse)) {
+    return parse;
+  }
+  if (isObjectRecord(parse) && isZodSchema(parse['output'])) {
+    return parse['output'];
+  }
+  return undefined;
+};
+
+const webhookValidationMessage = (
+  source: ActivationSource,
+  issues: ReturnType<typeof validateWebhookSource>
+): string =>
+  `Webhook source "${source.id}" is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join('; ')}`;
+
+const toWebhookSource = (
+  source: ActivationSource
+): Result<WebhookSource, Error> => {
+  const issues = validateWebhookSource(source);
+  if (issues.length > 0) {
+    return Result.err(
+      new ValidationError(webhookValidationMessage(source, issues), {
+        context: { issues },
+      })
+    );
+  }
+  const webhookSource = source as WebhookSource;
+  const method = (source.method ?? 'POST').trim().toUpperCase();
+  const path = source.path?.trim();
+  if (method === webhookSource.method && path === webhookSource.path) {
+    return Result.ok(webhookSource);
+  }
+  return Result.ok(
+    Object.freeze({
+      ...webhookSource,
+      method,
+      path,
+    }) as WebhookSource
+  );
+};
+
+const createWebhookInputParser =
+  (source: WebhookSource): HttpRouteDefinition['parseWebhookInput'] =>
+  (rawPayload) => {
+    const schema = parseOutputSchema(source.parse);
+    if (schema === undefined) {
+      return Result.err(
+        new ValidationError(
+          `Webhook source "${source.id}" does not expose a parse output schema`
+        )
+      );
+    }
+    const parsed = validateInput(schema, rawPayload);
+    if (parsed.isErr()) {
+      return Result.err(
+        new ValidationError(
+          `Webhook source "${source.id}" payload is invalid: ${parsed.error.message}`,
+          {
+            cause: parsed.error,
+            ...(parsed.error.context === undefined
+              ? {}
+              : { context: parsed.error.context }),
+          }
+        )
+      );
+    }
+    return parsed;
+  };
+
+const WEBHOOK_CONSUMERS = Symbol('webhookConsumers');
+const WEBHOOK_INVALID_RECORDERS = Symbol('webhookInvalidRecorders');
+
+type WebhookInvalidRecorder = NonNullable<
+  HttpRouteDefinition['recordWebhookInvalid']
+>;
+
+type MergeableWebhookRoute = HttpRouteDefinition & {
+  readonly [WEBHOOK_CONSUMERS]?: readonly WebhookConsumerExecute[];
+  readonly [WEBHOOK_INVALID_RECORDERS]?: readonly WebhookInvalidConsumerRecorder[];
+};
+
+const buildWebhookRoute = (
+  graph: Topo,
+  trail: Trail<unknown, unknown, unknown>,
+  activation: ActivationEntry,
+  basePath: string,
+  layers: readonly Layer[],
+  options: DeriveHttpRoutesOptions
+): Result<HttpRouteDefinition, Error> => {
+  const source = toWebhookSource(activation.source);
+  if (source.isErr()) {
+    return source;
+  }
+  const attachedLayers = collectAttachedTypedLayers(
+    graph,
+    trail,
+    options.layers
+  );
+  const inputProjection = projectHttpInputSchema(trail, attachedLayers);
+  const consumerExecute = createWebhookConsumerExecute(
+    graph,
+    trail,
+    activation,
+    source.value,
+    layers,
+    options,
+    inputProjection.projections
+  );
+  const consumerInvalidRecorder = createWebhookInvalidRecorder(
+    graph,
+    source.value,
+    trail.id
+  );
+  const route: MergeableWebhookRoute = {
+    [WEBHOOK_CONSUMERS]: [consumerExecute],
+    [WEBHOOK_INVALID_RECORDERS]: [consumerInvalidRecorder],
+    execute: createWebhookExecute(consumerExecute),
+    ...(inputProjection.schema === undefined
+      ? {}
+      : { inputSchema: inputProjection.schema }),
+    inputSource: 'webhook',
+    ...(inputProjection.projections.length === 0
+      ? {}
+      : { layerInputProjections: inputProjection.projections }),
+    method: source.value.method,
+    parseWebhookInput: createWebhookInputParser(source.value),
+    path: normalizeSourcePath(basePath, source.value.path),
+    recordWebhookInvalid: createWebhookInvalidPublicRecorder(
+      consumerInvalidRecorder
+    ),
+    trail,
+    trailId: trail.id,
+    verifyWebhook: (request) => verifyWebhookRequest(source.value, request),
+    webhookSource: source.value,
+  };
+  return Result.ok(route);
+};
+
 // ---------------------------------------------------------------------------
 // Collision detection
 // ---------------------------------------------------------------------------
@@ -169,44 +1020,247 @@ const buildRoute = (
 const routeKey = (route: HttpRouteDefinition): `${string} ${string}` =>
   `${route.method} ${route.path}`;
 
+const isSameWebhookSourceLocation = (
+  left: HttpRouteDefinition,
+  right: HttpRouteDefinition
+): boolean =>
+  left.inputSource === 'webhook' &&
+  right.inputSource === 'webhook' &&
+  left.webhookSource !== undefined &&
+  right.webhookSource !== undefined &&
+  left.webhookSource.id === right.webhookSource.id &&
+  left.webhookSource.method === right.webhookSource.method &&
+  left.webhookSource.path === right.webhookSource.path;
+
+/**
+ * Two webhook source routes can only merge when they declare the same
+ * verifier identity. Reference equality on `verify` matches the projection
+ * model used elsewhere — a shared source object always passes, while two
+ * separately-declared verifier functions are treated as distinct policies
+ * even when their bodies look equivalent.
+ */
+const hasMatchingWebhookVerifier = (
+  left: HttpRouteDefinition,
+  right: HttpRouteDefinition
+): boolean => left.webhookSource?.verify === right.webhookSource?.verify;
+
+/**
+ * Two webhook source routes can only merge when they declare the same parse
+ * contract identity. Reference equality on `parse` mirrors the verifier rule:
+ * a shared source object always passes, while two separately-declared parse
+ * schemas (or handlers) are treated as distinct contracts even when their
+ * shapes look equivalent. Without this check the merged route silently keeps
+ * whichever parser registered first, so payloads valid for later consumers
+ * could be rejected and unintended shapes could be passed downstream.
+ */
+const hasMatchingWebhookParse = (
+  left: HttpRouteDefinition,
+  right: HttpRouteDefinition
+): boolean => left.webhookSource?.parse === right.webhookSource?.parse;
+
+const webhookConsumers = (
+  route: MergeableWebhookRoute
+): readonly WebhookConsumerExecute[] | undefined => route[WEBHOOK_CONSUMERS];
+
+const webhookInvalidRecorders = (
+  route: MergeableWebhookRoute
+): readonly WebhookInvalidConsumerRecorder[] =>
+  route[WEBHOOK_INVALID_RECORDERS] ?? [];
+
+type MergeWebhookOutcome =
+  | { readonly kind: 'merged'; readonly route: HttpRouteDefinition }
+  | { readonly kind: 'verifier-mismatch'; readonly error: ValidationError }
+  | { readonly kind: 'parse-mismatch'; readonly error: ValidationError }
+  | { readonly kind: 'not-mergeable' };
+
+const mergeWebhookRoutes = (
+  existing: HttpRouteDefinition,
+  route: HttpRouteDefinition
+): MergeWebhookOutcome => {
+  if (!isSameWebhookSourceLocation(existing, route)) {
+    return { kind: 'not-mergeable' };
+  }
+  if (!hasMatchingWebhookVerifier(existing, route)) {
+    return {
+      error: new ValidationError(
+        `HTTP route collision: trails "${existing.trailId}" and "${route.trailId}" share webhook source "${existing.webhookSource?.id}" on ${route.method} ${route.path} but declare a mismatched webhook verifier policy. Reuse the same WebhookSource object so both consumers run under one verifier.`
+      ),
+      kind: 'verifier-mismatch',
+    };
+  }
+  if (!hasMatchingWebhookParse(existing, route)) {
+    return {
+      error: new ValidationError(
+        `HTTP route collision: trails "${existing.trailId}" and "${route.trailId}" share webhook source "${existing.webhookSource?.id}" on ${route.method} ${route.path} but declare a mismatched webhook parse contract. Reuse the same WebhookSource object so both consumers parse payloads under one contract.`
+      ),
+      kind: 'parse-mismatch',
+    };
+  }
+
+  const existingConsumers = webhookConsumers(existing as MergeableWebhookRoute);
+  const incomingConsumers = webhookConsumers(route as MergeableWebhookRoute);
+  if (existingConsumers === undefined || incomingConsumers === undefined) {
+    return { kind: 'not-mergeable' };
+  }
+  const consumers: readonly WebhookConsumerExecute[] = [
+    ...existingConsumers,
+    ...incomingConsumers,
+  ];
+
+  const recorders = [
+    ...webhookInvalidRecorders(existing as MergeableWebhookRoute),
+    ...webhookInvalidRecorders(route as MergeableWebhookRoute),
+  ] as const;
+
+  // Fan-out: every consumer's recorder must fire on parse/verify failures so
+  // each trail emits its own activation.webhook.invalid trace record. A
+  // single activation fire ID is generated per inbound failed request and
+  // shared across all recorders so observability can correlate the sibling
+  // invalid records as one activation root, mirroring the success path. A
+  // recorder failure must not prevent the remaining recorders from running.
+  const recordWebhookInvalidFanOut: WebhookInvalidRecorder | undefined =
+    recorders.length === 0
+      ? undefined
+      : async (errorCategory) => {
+          const activationFireId = createWebhookActivationFireId();
+          await Promise.all(
+            recorders.map(async (record) => {
+              try {
+                await record(errorCategory, activationFireId);
+              } catch {
+                // Recorder failures must never short-circuit the fan-out;
+                // sink errors are already swallowed inside writeToSink.
+              }
+            })
+          );
+        };
+
+  const merged: MergeableWebhookRoute = {
+    ...existing,
+    [WEBHOOK_CONSUMERS]: consumers,
+    [WEBHOOK_INVALID_RECORDERS]: recorders,
+    inputSchema: mergeHttpInputSchemas(existing.inputSchema, route.inputSchema),
+    layerInputProjections: [
+      ...(existing.layerInputProjections ?? []),
+      ...(route.layerInputProjections ?? []),
+    ],
+    ...(recordWebhookInvalidFanOut === undefined
+      ? {}
+      : { recordWebhookInvalid: recordWebhookInvalidFanOut }),
+    async execute(input, requestId, abortSignal, request) {
+      // One activation fire ID per inbound webhook request, shared across every
+      // fan-out consumer so observability can correlate them as siblings of a
+      // single activation root.
+      const activationFireId = createWebhookActivationFireId();
+
+      // Fan-out: every consumer must get its attempt even when an earlier
+      // consumer fails. Remember the first error, run the rest, and only
+      // surface ok when every consumer succeeded.
+      const values: unknown[] = [];
+      let firstError: Result<unknown, Error> | undefined;
+      for (const consumerExecute of consumers) {
+        const result = await consumerExecute(
+          input,
+          requestId,
+          abortSignal,
+          request,
+          activationFireId
+        );
+        if (result.isErr()) {
+          if (firstError === undefined) {
+            firstError = result;
+          }
+          continue;
+        }
+        values.push(result.value);
+      }
+      if (firstError !== undefined) {
+        return firstError;
+      }
+      return Result.ok(values);
+    },
+  };
+  return { kind: 'merged', route: merged };
+};
+
 /** Register a route, checking for (path, method) collisions. */
 const registerRoute = (
   route: HttpRouteDefinition,
-  seenRoutes: Map<string, string>,
+  seenRoutes: Map<string, HttpRouteDefinition>,
   routes: HttpRouteDefinition[]
 ): Result<void, Error> => {
   const key = routeKey(route);
-  const existingId = seenRoutes.get(key);
-  if (existingId !== undefined) {
+  const existing = seenRoutes.get(key);
+  if (existing !== undefined) {
+    const outcome = mergeWebhookRoutes(existing, route);
+    if (outcome.kind === 'merged') {
+      seenRoutes.set(key, outcome.route);
+      const routeIndex = routes.indexOf(existing);
+      if (routeIndex !== -1) {
+        routes[routeIndex] = outcome.route;
+      }
+      return Result.ok();
+    }
+    if (
+      outcome.kind === 'verifier-mismatch' ||
+      outcome.kind === 'parse-mismatch'
+    ) {
+      return Result.err(outcome.error);
+    }
     return Result.err(
       new ValidationError(
-        `HTTP route collision: trails "${existingId}" and "${route.trailId}" both derive ${route.method} ${route.path}`
+        `HTTP route collision: trails "${existing.trailId}" and "${route.trailId}" both derive ${route.method} ${route.path}`
       )
     );
   }
-  seenRoutes.set(key, route.trailId);
+  seenRoutes.set(key, route);
   routes.push(route);
   return Result.ok();
 };
 
 /** Accumulate route definitions, returning early on the first collision. */
 const accumulateRoutes = (
-  trails: Trail<unknown, unknown>[],
+  graph: Topo,
+  trails: Trail<unknown, unknown, unknown>[],
+  webhookTrails: 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>();
+  const seenRoutes = new Map<string, HttpRouteDefinition>();
 
   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;
     }
   }
 
+  for (const trail of webhookTrails) {
+    for (const activation of trail.activationSources) {
+      if (activation.source.kind !== 'webhook') {
+        continue;
+      }
+      const route = buildWebhookRoute(
+        graph,
+        trail,
+        activation,
+        basePath,
+        layers,
+        options
+      );
+      if (route.isErr()) {
+        return route;
+      }
+      const registered = registerRoute(route.value, seenRoutes, routes);
+      if (registered.isErr()) {
+        return registered;
+      }
+    }
+  }
+
   return Result.ok(routes);
 };
 
@@ -221,23 +1275,28 @@ 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(app);
-    if (validated.isErr()) {
-      return Result.err(validated.error);
-    }
+  const validated = validateSurfaceTopo(graph, options);
+  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),
+    eligibleWebhookTrails(graph, options),
+    basePath,
+    layers,
+    options
+  );
 };