@ontrails/warden 1.0.0-beta.32 → 1.0.0-beta.39

package/src/rules/trailhead-override-divergence.ts

@@ -0,0 +1,356 @@
+/**
+ * Warn when a call-site MCP trailhead map diverges from the app-authored
+ * `surfaces` overlay's `mcp` list bindings.
+ *
+ * The overlay is the authored, lockable default; a call-site trailhead map
+ * is a supported override-in-context that wins at runtime. Divergence between
+ * the two is legal but must be visible: an agent reading the committed lock
+ * would otherwise trust grouped entries the running surface does not project.
+ *
+ * Rule-kind note: no Warden rule kind currently sees both the serialized
+ * graph overlays and source ASTs directly. This rule is the closest honest
+ * shape — a project-aware source rule whose `ProjectContext` carries
+ * per-app authored `mcp` binding sets resolved from the run's topo targets
+ * (graph overlays when available, else app-module overlay registrations).
+ * A call-site map is attributed to an app only when one of its literal
+ * member selectors matches a trail id in that app's topo, so one app's
+ * authored bindings never flag another app's call-site map. Without
+ * context (`check` without context, or a run with no topo targets) the
+ * rule stays silent rather than guessing.
+ */
+
+import { classifySurfaceBinding, matchesTrailPattern } from '@ontrails/core';
+import type { SurfaceBindings } from '@ontrails/core';
+
+import {
+  extractStringOrTemplateLiteral,
+  findConfigProperty,
+  getNodeArgument,
+  getNodeElements,
+  getNodeExpression,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeName,
+  getNodeProperties,
+  getNodeTypeAnnotation,
+  getNodeValueNode,
+  getPropertyName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type {
+  AuthoredMcpSurfaceBindingSet,
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'trailhead-override-divergence';
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (
+    current?.type === 'TSAsExpression' ||
+    current?.type === 'TSSatisfiesExpression'
+  ) {
+    current = getNodeExpression(current) ?? getNodeArgument(current);
+  }
+  return current;
+};
+
+const objectProperties = (node: AstNode): readonly AstNode[] =>
+  node.type === 'ObjectExpression' ? (getNodeProperties(node) ?? []) : [];
+
+const propertyValue = (property: AstNode): AstNode | undefined =>
+  property.type === 'Property' ? getNodeValueNode(property) : undefined;
+
+const isTrailheadDefinition = (node: AstNode): boolean =>
+  node.type === 'ObjectExpression' &&
+  findConfigProperty(node, 'trails') !== null;
+
+const isTrailheadMapCandidate = (node: AstNode): boolean =>
+  objectProperties(node).some((property) => {
+    const value = unwrapExpression(propertyValue(property));
+    return value !== undefined && isTrailheadDefinition(value);
+  });
+
+const isTrailheadMapBindingName = (name: string | null): boolean =>
+  name !== null &&
+  (name === 'trailheads' ||
+    name.endsWith('Trailheads') ||
+    name.endsWith('TrailheadMap'));
+
+const hasTrailheadMapTypeAnnotation = (
+  sourceCode: string,
+  node: AstNode
+): boolean => {
+  const typeAnnotation = getNodeTypeAnnotation(node);
+  return (
+    typeAnnotation !== undefined &&
+    /\b(?:McpSurfaceTrailheadMap|TrailheadMap)\b/.test(
+      sourceCode.slice(typeAnnotation.start, typeAnnotation.end)
+    )
+  );
+};
+
+const diagnostic = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  message: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+/**
+ * Collect the literal selector strings of one trailhead definition. Returns
+ * `null` when any selector is dynamic — `surface-trailhead-coherence`
+ * already flags those, so this rule skips the comparison instead of
+ * double-reporting.
+ */
+const literalSelectors = (definition: AstNode): readonly string[] | null => {
+  const trailsProp = findConfigProperty(definition, 'trails');
+  const trailsValue = trailsProp ? propertyValue(trailsProp) : undefined;
+  const value = unwrapExpression(trailsValue);
+  if (!value) {
+    return null;
+  }
+  const nodes =
+    value.type === 'ArrayExpression'
+      ? getNodeElements(value).filter((element) => element !== null)
+      : [value];
+  const selectors: string[] = [];
+  for (const node of nodes) {
+    const selector = extractStringOrTemplateLiteral(node);
+    if (selector === null) {
+      return null;
+    }
+    selectors.push(selector);
+  }
+  return selectors;
+};
+
+const authoredGroupSelectors = (
+  bindings: SurfaceBindings
+): ReadonlyMap<string, readonly string[]> => {
+  const groups = new Map<string, readonly string[]>();
+  for (const [name, value] of Object.entries(bindings)) {
+    const shape = classifySurfaceBinding(value);
+    if (shape.kind === 'group') {
+      groups.set(name, shape.members);
+    }
+  }
+  return groups;
+};
+
+const sameSelectorSet = (
+  first: readonly string[],
+  second: readonly string[]
+): boolean => {
+  const firstSet = new Set(first);
+  const secondSet = new Set(second);
+  return (
+    firstSet.size === secondSet.size &&
+    [...firstSet].every((selector) => secondSet.has(selector))
+  );
+};
+
+const formatSelectors = (selectors: readonly string[]): string =>
+  [...new Set(selectors)]
+    .toSorted()
+    .map((selector) => `"${selector}"`)
+    .join(', ');
+
+/**
+ * Attribute a call-site trailhead map to a binding set: the map belongs to
+ * an app when at least one of its literal member selectors matches a trail
+ * id registered in that app's topo.
+ */
+const mapBelongsToSet = (
+  trailheadMap: AstNode,
+  set: AuthoredMcpSurfaceBindingSet
+): boolean =>
+  objectProperties(trailheadMap).some((property) => {
+    const value = unwrapExpression(propertyValue(property));
+    if (value === undefined || !isTrailheadDefinition(value)) {
+      return false;
+    }
+    const selectors = literalSelectors(value);
+    return (
+      selectors !== null &&
+      selectors.some((selector) =>
+        set.trailIds.some((trailId) => matchesTrailPattern(trailId, selector))
+      )
+    );
+  });
+
+const diagnoseTrailheadMap = (
+  sourceCode: string,
+  filePath: string,
+  trailheadMap: AstNode,
+  set: AuthoredMcpSurfaceBindingSet,
+  groups: ReadonlyMap<string, readonly string[]>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const groupNames = [...groups.keys()].toSorted();
+
+  for (const property of objectProperties(trailheadMap)) {
+    const trailheadId = getPropertyName(getNodeKey(property));
+    const value = unwrapExpression(propertyValue(property));
+    if (!trailheadId || value === undefined || !isTrailheadDefinition(value)) {
+      continue;
+    }
+
+    const authored = groups.get(trailheadId);
+    if (authored === undefined) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          property,
+          `Call-site MCP trailhead "${trailheadId}" has no matching mcp list binding in app "${set.appName}"'s surfaceOverlay (authored groups: ${groupNames.length > 0 ? groupNames.map((name) => `"${name}"`).join(', ') : 'none'}). The call-site map overrides the lockable default at runtime — author the same binding in surfaceOverlay({ mcp }) or rename one side.`
+        )
+      );
+      continue;
+    }
+
+    const selectors = literalSelectors(value);
+    if (selectors === null) {
+      continue;
+    }
+    if (!sameSelectorSet(selectors, authored)) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          property,
+          `Call-site MCP trailhead "${trailheadId}" selects [${formatSelectors(selectors)}] but app "${set.appName}"'s surfaceOverlay mcp binding "${trailheadId}" authors [${formatSelectors(authored)}]. The call-site map overrides the lockable default at runtime — align the member selectors or make the intentional divergence explicit by renaming one side.`
+        )
+      );
+    }
+  }
+
+  // The override replaces the authored default whole-map at runtime, so an
+  // authored group missing from the call-site map is silently dropped while
+  // the committed lock still advertises it.
+  const callSiteNames = new Set(
+    objectProperties(trailheadMap).flatMap((property) => {
+      const name = getPropertyName(getNodeKey(property));
+      const value = unwrapExpression(propertyValue(property));
+      return name && value !== undefined && isTrailheadDefinition(value)
+        ? [name]
+        : [];
+    })
+  );
+  for (const name of groupNames) {
+    if (!callSiteNames.has(name)) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          trailheadMap,
+          `App "${set.appName}"'s surfaceOverlay mcp binding "${name}" is not carried by this call-site trailhead map, so it will not be projected at runtime while the committed lock still advertises it. Add "${name}" to the call-site map or remove it from the authored overlay.`
+        )
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+/**
+ * Warn when a source file's call-site MCP trailhead map diverges from the
+ * app-authored `surfaces` overlay's `mcp` list bindings.
+ */
+export const trailheadOverrideDivergence: ProjectAwareWardenRule = {
+  check(): readonly WardenDiagnostic[] {
+    // Without project context there are no authored bindings to compare
+    // against; stay silent instead of guessing.
+    return [];
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const sets = (context.authoredMcpSurfaceBindingSets ?? [])
+      .map((set) => ({
+        groups: authoredGroupSelectors(set.bindings),
+        set,
+      }))
+      .filter(({ groups }) => groups.size > 0);
+    if (sets.length === 0) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const seen = new Set<number>();
+    const diagnostics: WardenDiagnostic[] = [];
+    const diagnoseCandidate = (node: AstNode | undefined): void => {
+      const unwrapped = unwrapExpression(node);
+      if (
+        unwrapped === undefined ||
+        unwrapped.type !== 'ObjectExpression' ||
+        seen.has(unwrapped.start) ||
+        !isTrailheadMapCandidate(unwrapped)
+      ) {
+        return;
+      }
+      seen.add(unwrapped.start);
+      for (const { set, groups } of sets) {
+        if (!mapBelongsToSet(unwrapped, set)) {
+          continue;
+        }
+        diagnostics.push(
+          ...diagnoseTrailheadMap(sourceCode, filePath, unwrapped, set, groups)
+        );
+      }
+    };
+
+    walk(ast, (node) => {
+      if (node.type === 'Property') {
+        const propertyName = getPropertyName(getNodeKey(node));
+        if (propertyName === 'trailheads') {
+          diagnoseCandidate(propertyValue(node));
+        }
+        return;
+      }
+
+      if (node.type === 'VariableDeclarator') {
+        const bindingName = getNodeName(getNodeId(node));
+        if (
+          typeof bindingName === 'string' &&
+          isTrailheadMapBindingName(bindingName)
+        ) {
+          diagnoseCandidate(getNodeInit(node) ?? undefined);
+        }
+        return;
+      }
+
+      if (
+        (node.type === 'TSAsExpression' ||
+          node.type === 'TSSatisfiesExpression') &&
+        hasTrailheadMapTypeAnnotation(sourceCode, node)
+      ) {
+        diagnoseCandidate(node);
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Call-site MCP trailhead maps stay aligned with the app-authored surfaces overlay mcp bindings they override.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/types.ts

@@ -3,6 +3,7 @@ import type {
   Intent,
   RuleDiagnosticBase,
   ScanTargets,
+  SurfaceBindings,
   Topo,
 } from '@ontrails/core';
 import type { TopoGraph } from '@ontrails/topographer';
@@ -104,8 +105,13 @@ export interface WardenGuidance {
  * Names the kind of mechanical change so agents, the guide, and downstream
  * regrades can route by class. `term-rewrite` is the durable name for retired
  * vocabulary renames (`vocab-cutover` is historical wording only).
+ * `export-restructure` names structural export rewrites — the finding is not
+ * a rename but a reshaping of a module export (for example wrapping a legacy
+ * CLI alias map into a `surfaceOverlay({ cli })` entry inside
+ * `trailsOverlays`), so downstream Regrade routes it to a structural
+ * transform class instead of a span replacement.
  */
-export type WardenFixClass = 'term-rewrite';
+export type WardenFixClass = 'export-restructure' | 'term-rewrite';
 
 /**
  * How safe a fix is to apply without human review.
@@ -235,6 +241,29 @@ export interface WardenDiagnostic extends RuleDiagnosticBase {
   readonly fix?: WardenFix | undefined;
 }
 
+/** Public exported symbol observed from a first-party package export target. */
+export interface WardenExportedSymbolDefinition {
+  /** Exported binding name. */
+  readonly name: string;
+  /** Export declaration kind that introduced the binding. */
+  readonly kind:
+    | 'class'
+    | 'const'
+    | 'enum'
+    | 'export'
+    | 'function'
+    | 'interface'
+    | 'type';
+  /** Absolute or runner-provided file path containing the definition. */
+  readonly filePath: string;
+  /** 1-based source line where the exported definition starts. */
+  readonly line: number;
+  /** First-party workspace package that owns the definition. */
+  readonly workspaceName: string;
+  /** Filesystem root of the owning workspace. */
+  readonly workspaceRoot: string;
+}
+
 /**
  * A warden rule analyzes one source file and returns diagnostics.
  *
@@ -258,10 +287,33 @@ export interface WardenRule {
   ) => readonly WardenDiagnostic[];
 }
 
+/**
+ * One app's authored `surfaces` overlay `mcp` bindings plus the trail ids
+ * that scope which source files the bindings can be compared against.
+ */
+export interface AuthoredMcpSurfaceBindingSet {
+  /** Stable app/topo label the bindings were authored for. */
+  readonly appName: string;
+  /** The `mcp` bindings from the app's `surfaces` overlay. */
+  readonly bindings: SurfaceBindings;
+  /** Trail ids registered in the owning app's topo. */
+  readonly trailIds: readonly string[];
+}
+
 /**
  * Options for compose-file rules that need knowledge of all trail IDs in a project.
  */
 export interface ProjectContext {
+  /**
+   * Per-app authored `mcp` surface bindings, resolved from the project's
+   * topo targets (the serialized graph overlays when available, else the
+   * app-module overlay registrations). Each set carries the owning app's
+   * trail ids so source rules can attribute a call-site surface option to
+   * the app whose overlay authored the default before comparing.
+   */
+  readonly authoredMcpSurfaceBindingSets?:
+    | readonly AuthoredMcpSurfaceBindingSet[]
+    | undefined;
   /** All known contour names in the project. */
   readonly knownContourIds?: ReadonlySet<string>;
   /** Store table IDs used with the CRUD factory across the project. */
@@ -294,6 +346,11 @@ export interface ProjectContext {
   >;
   /** Non-private published @ontrails workspaces discovered from the root manifest. */
   readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
+  /** Public package export definitions grouped by exported name. */
+  readonly exportedSymbolDefinitionsByName?: ReadonlyMap<
+    string,
+    readonly WardenExportedSymbolDefinition[]
+  >;
   /** Normalized trail intents by trail ID across the project. */
   readonly trailIntentsById?: ReadonlyMap<string, Intent>;
   /**

package/src/rules/webhook-route-collision.ts

@@ -1,4 +1,7 @@
-import { shouldIncludeTrailForSurface } from '@ontrails/core';
+import {
+  shouldIncludeTrailForSurface,
+  webhookPathPatternsOverlap,
+} from '@ontrails/core';
 import type { Topo, Trail } from '@ontrails/core';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
@@ -200,6 +203,65 @@ const collectPolicyMismatchDiagnostics = (
   return diagnostics;
 };
 
+const hasDynamicSegment = (path: string): boolean => path.includes('/:');
+
+/**
+ * Flag distinct route keys whose path patterns can both match one concrete
+ * request. Exact-key collisions are handled by the grouping pass; this pass
+ * extends detection to dynamic-segment patterns (`/hooks/:endpoint` vs
+ * `/hooks/github`), where at least one webhook claim participates.
+ */
+const collectPatternOverlapDiagnostics = (
+  claimsByRoute: ReadonlyMap<string, readonly RouteClaim[]>
+): WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const keys = [...claimsByRoute.keys()].toSorted();
+
+  for (const [index, leftKey] of keys.entries()) {
+    for (const rightKey of keys.slice(index + 1)) {
+      const leftClaims = claimsByRoute.get(leftKey) ?? [];
+      const rightClaims = claimsByRoute.get(rightKey) ?? [];
+      const [leftFirst] = leftClaims;
+      const [rightFirst] = rightClaims;
+      if (leftFirst === undefined || rightFirst === undefined) {
+        continue;
+      }
+      if (leftFirst.method !== rightFirst.method) {
+        continue;
+      }
+      if (
+        !(
+          hasDynamicSegment(leftFirst.path) ||
+          hasDynamicSegment(rightFirst.path)
+        )
+      ) {
+        continue;
+      }
+      const participants = [...leftClaims, ...rightClaims];
+      if (!participants.some((claim) => claim.type === 'webhook')) {
+        continue;
+      }
+      if (!webhookPathPatternsOverlap(leftFirst.path, rightFirst.path)) {
+        continue;
+      }
+      diagnostics.push({
+        filePath: TOPO_FILE,
+        line: 1,
+        message: `HTTP webhook route pattern overlap between ${leftKey} and ${rightKey}: ${sortedClaims(
+          participants
+        )
+          .map(claimLabel)
+          .join(
+            ', '
+          )}. Both patterns can match one request path; make the patterns disjoint or merge the sources.`,
+        rule: RULE_NAME,
+        severity: 'error',
+      });
+    }
+  }
+  return diagnostics;
+};
+
 const buildDiagnostics = (claims: readonly RouteClaim[]) => {
   const claimsByRoute = new Map<string, RouteClaim[]>();
   for (const claim of claims) {
@@ -227,6 +289,7 @@ const buildDiagnostics = (claims: readonly RouteClaim[]) => {
     }
     diagnostics.push(...collectPolicyMismatchDiagnostics(key, webhookClaims));
   }
+  diagnostics.push(...collectPatternOverlapDiagnostics(claimsByRoute));
   return diagnostics;
 };
 

package/src/trails/duplicate-exported-symbol.trail.ts

@@ -0,0 +1,48 @@
+import { duplicateExportedSymbol } from '../rules/duplicate-exported-symbol.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const duplicateExportedSymbolTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '/repo/packages/core/src/index.ts',
+            line: 1,
+            message:
+              'Exported symbol "createClient" is defined by @ontrails/core and also by @ontrails/store (/repo/packages/store/src/index.ts:1). Keep one package as the owner, rename one side, or document a deliberate ownership mirror before exporting both symbols.',
+            rule: 'duplicate-exported-symbol',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        exportedSymbolDefinitionsByName: {
+          createClient: [
+            {
+              filePath: '/repo/packages/core/src/index.ts',
+              kind: 'function',
+              line: 1,
+              name: 'createClient',
+              workspaceName: '@ontrails/core',
+              workspaceRoot: '/repo/packages/core',
+            },
+            {
+              filePath: '/repo/packages/store/src/index.ts',
+              kind: 'function',
+              line: 1,
+              name: 'createClient',
+              workspaceName: '@ontrails/store',
+              workspaceRoot: '/repo/packages/store',
+            },
+          ],
+        },
+        filePath: '/repo/packages/core/src/index.ts',
+        knownTrailIds: [],
+        sourceCode: 'export function createClient() {}',
+      },
+      name: 'Flags duplicate exported symbol definitions across packages',
+    },
+  ],
+  rule: duplicateExportedSymbol,
+});

package/src/trails/duplicate-public-contract.trail.ts

@@ -28,7 +28,7 @@ export const duplicatePublicContractTrail = wrapTopoRule({
             filePath: '<topo>',
             line: 1,
             message:
-              'Likely duplicate public trail contracts "diff", "survey.diff" share the same input, output, intent, permits, resources, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.',
+              'Likely duplicate public trail contracts "diff", "survey.diff" share the same input, output, intent, permits, resources, contours, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.',
             rule: 'duplicate-public-contract',
             severity: 'warn',
           },

package/src/trails/governed-symbol-residue.trail.ts

@@ -0,0 +1,24 @@
+import { governedSymbolResidue } from '../rules/governed-symbol-residue.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const governedSymbolResidueTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/example/src/trails/play.ts',
+        sourceCode: 'const composeInput = { id: "track" };\n',
+      },
+      name: 'Current governed symbol vocabulary is clean',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/example/src/trails/play.ts',
+        sourceCode: 'const crossInput = { id: "track" };\n',
+      },
+      name: 'Cross-compose vocabulary is owned by the beta.19 rule',
+    },
+  ],
+  rule: governedSymbolResidue,
+});

package/src/trails/index.ts

@@ -10,10 +10,12 @@ export { deprecationWithoutGuidanceTrail } from './deprecation-without-guidance.
 export { duplicatePublicContractTrail } from './duplicate-public-contract.trail.js';
 export { draftFileMarkingTrail } from './draft-file-marking.trail.js';
 export { draftVisibleDebtTrail } from './draft-visible-debt.trail.js';
+export { duplicateExportedSymbolTrail } from './duplicate-exported-symbol.trail.js';
 export { errorMappingCompletenessTrail } from './error-mapping-completeness.trail.js';
 export { exampleValidTrail } from './example-valid.trail.js';
 export { firesDeclarationsTrail } from './fires-declarations.trail.js';
 export { forkWithoutPreservedBlazeTrail } from './fork-without-preserved-blaze.trail.js';
+export { governedSymbolResidueTrail } from './governed-symbol-residue.trail.js';
 export { implementationReturnsResultTrail } from './implementation-returns-result.trail.js';
 export { incompleteAccessorForStandardOpTrail } from './incomplete-accessor-for-standard-op.trail.js';
 export { incompleteCrudTrail } from './incomplete-crud.trail.js';
@@ -26,6 +28,7 @@ export { missingReconcileTrail } from './missing-reconcile.trail.js';
 export { onReferencesExistTrail } from './on-references-exist.trail.js';
 export { noDevPermitInSourceTrail } from './no-dev-permit-in-source.trail.js';
 export { noDestructuredComposeTrail } from './no-destructured-compose.trail.js';
+export { noLegacyCliAliasExportTrail } from './no-legacy-cli-alias-export.trail.js';
 export { noLegacyLayerImportsTrail } from './no-legacy-layer-imports.trail.js';
 export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
 export { noNativeErrorResultTrail } from './no-native-error-result.trail.js';
@@ -54,8 +57,10 @@ export { resourceMockCoverageTrail } from './resource-mock-coverage.trail.js';
 export { scheduledDestroyIntentTrail } from './scheduled-destroy-intent.trail.js';
 export { signalGraphCoachingTrail } from './signal-graph-coaching.trail.js';
 export { staticResourceAccessorPreferenceTrail } from './static-resource-accessor-preference.trail.js';
-export { surfaceFacetCoherenceTrail } from './surface-facet-coherence.trail.js';
+export { surfaceOverlayCoherenceTrail } from './surface-overlay-coherence.trail.js';
+export { surfaceTrailheadCoherenceTrail } from './surface-trailhead-coherence.trail.js';
 export { trailForkCoachingTrail } from './trail-fork-coaching.trail.js';
+export { trailheadOverrideDivergenceTrail } from './trailhead-override-divergence.trail.js';
 export { unmaterializedActivationSourceTrail } from './unmaterialized-activation-source.trail.js';
 export { unreachableDetourShadowingTrail } from './unreachable-detour-shadowing.trail.js';
 export { validDetourContractTrail } from './valid-detour-contract.trail.js';