@ontrails/warden 1.0.0-beta.3 → 1.0.0-beta.30

package/src/rules/index.ts

@@ -1,54 +1,270 @@
+import { activationOrphan } from './activation-orphan.js';
+import { cliCommandRouteCoherence } from './cli-command-route-coherence.js';
+import { circularRefs } from './circular-refs.js';
+import { contourExists } from './contour-exists.js';
 import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { composesDeclarations } from './composes-declarations.js';
+import { deadInternalTrail } from './dead-internal-trail.js';
+import { deadPublicTrail } from './dead-public-trail.js';
+import { draftFileMarking } from './draft-file-marking.js';
+import { draftVisibleDebt } from './draft-visible-debt.js';
+import { duplicatePublicContract } from './duplicate-public-contract.js';
+import { errorMappingCompleteness } from './error-mapping-completeness.js';
+import { exampleValid } from './example-valid.js';
+import { firesDeclarations } from './fires-declarations.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
-import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
+import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+import { incompleteCrud } from './incomplete-crud.js';
+import { intentPropagation } from './intent-propagation.js';
+import { layerFieldNameDrift } from './layer-field-name-drift.js';
+import { libraryProjectionCoherence } from './library-projection-coherence.js';
+import { missingVisibility } from './missing-visibility.js';
+import { missingReconcile } from './missing-reconcile.js';
+import { noDevPermitInSource } from './no-dev-permit-in-source.js';
+import { noDestructuredCompose } from './no-destructured-compose.js';
+import { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
+import { noNativeErrorResult } from './no-native-error-result.js';
+import { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+import { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 import { noSyncResultAssumption } from './no-sync-result-assumption.js';
-import { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+import { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
 import { noThrowInImplementation } from './no-throw-in-implementation.js';
+import { noTopLevelSurface } from './no-top-level-surface.js';
+import { onReferencesExist } from './on-references-exist.js';
+import { orphanedSignal } from './orphaned-signal.js';
+import { ownerProjectionParity } from './owner-projection-parity.js';
+import { permitGovernance } from './permit-governance.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
-import type { WardenRule } from './types.js';
+import { publicExportExampleCoverage } from './public-export-example-coverage.js';
+import { publicInternalDeepImports } from './public-internal-deep-imports.js';
+import { publicOutputSchema } from './public-output-schema.js';
+import { publicUnionOutputDiscriminants } from './public-union-output-discriminants.js';
+import { readIntentFires } from './read-intent-fires.js';
+import { referenceExists } from './reference-exists.js';
+import { resolvedImportBoundary } from './resolved-import-boundary.js';
+import { resourceDeclarations } from './resource-declarations.js';
+import { resourceExists } from './resource-exists.js';
+import { resourceIdGrammar } from './resource-id-grammar.js';
+import { resourceMockCoverage } from './resource-mock-coverage.js';
+import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
+import { signalGraphCoaching } from './signal-graph-coaching.js';
+import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+import { surfaceFacetCoherence } from './surface-facet-coherence.js';
+import { trailForkCoaching } from './trail-fork-coaching.js';
+import {
+  forkWithoutPreservedBlaze,
+  markerSchemaUnsupported,
+  versionPinnedCompose,
+} from './trail-versioning-source.js';
+import {
+  deprecationWithoutGuidance,
+  pendingForce,
+  versionGap,
+  versionWithoutExamples,
+} from './trail-versioning-topo.js';
+import type { TopoAwareWardenRule, WardenRule } from './types.js';
+import { unmaterializedActivationSource } from './unmaterialized-activation-source.js';
+import { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+import { validDetourContract } from './valid-detour-contract.js';
 import { validDescribeRefs } from './valid-describe-refs.js';
-import { validDetourRefs } from './valid-detour-refs.js';
+import { wardenExportSymmetry } from './warden-export-symmetry.js';
+import { wardenRulesUseAst } from './warden-rules-use-ast.js';
+import { webhookRouteCollision } from './webhook-route-collision.js';
 
 export type {
+  WardenFix,
+  WardenFixCapability,
+  WardenFixClass,
+  WardenFixEdit,
+  WardenFixSafety,
+  WardenGuidance,
+  WardenGuidanceLink,
+  WardenRuleLifecycle,
+  WardenRuleLifecycleState,
+  WardenRuleConcern,
+  WardenRuleMetadata,
+  WardenRuleScope,
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
   WardenRule,
+  WardenRuleTier,
   WardenSeverity,
 } from './types.js';
 
+export {
+  builtinWardenRuleMetadata,
+  getWardenRuleMetadata,
+  listWardenRuleMetadata,
+  wardenFixClasses,
+  wardenFixSafeties,
+  wardenRuleConcerns,
+  wardenRuleLifecycleStates,
+  wardenRuleScopes,
+  wardenRuleTiers,
+} from './metadata.js';
+export type { BuiltinWardenRuleName } from './metadata.js';
+
+export { activationOrphan } from './activation-orphan.js';
+export { cliCommandRouteCoherence } from './cli-command-route-coherence.js';
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
+export { circularRefs } from './circular-refs.js';
+export { contourExists } from './contour-exists.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
-export { validDetourRefs } from './valid-detour-refs.js';
-export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
+export { composesDeclarations } from './composes-declarations.js';
+export { deadInternalTrail } from './dead-internal-trail.js';
+export { deadPublicTrail } from './dead-public-trail.js';
+export { draftFileMarking } from './draft-file-marking.js';
+export { draftVisibleDebt } from './draft-visible-debt.js';
+export { duplicatePublicContract } from './duplicate-public-contract.js';
+export { errorMappingCompleteness } from './error-mapping-completeness.js';
+export { exampleValid } from './example-valid.js';
+export { firesDeclarations } from './fires-declarations.js';
+export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+export { incompleteCrud } from './incomplete-crud.js';
+export { intentPropagation } from './intent-propagation.js';
+export { libraryProjectionCoherence } from './library-projection-coherence.js';
+export { layerFieldNameDrift } from './layer-field-name-drift.js';
+export { missingVisibility } from './missing-visibility.js';
+export { missingReconcile } from './missing-reconcile.js';
+export { onReferencesExist } from './on-references-exist.js';
+export { noDevPermitInSource } from './no-dev-permit-in-source.js';
+export { noDestructuredCompose } from './no-destructured-compose.js';
+export { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
+export { noNativeErrorResult } from './no-native-error-result.js';
+export { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+export { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 export { noSyncResultAssumption } from './no-sync-result-assumption.js';
 export { implementationReturnsResult } from './implementation-returns-result.js';
-export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+export { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
+export { noTopLevelSurface } from './no-top-level-surface.js';
+export { orphanedSignal } from './orphaned-signal.js';
+export { ownerProjectionParity } from './owner-projection-parity.js';
+export { permitGovernance } from './permit-governance.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
+export { publicInternalDeepImports } from './public-internal-deep-imports.js';
+export { publicOutputSchema } from './public-output-schema.js';
+export { publicUnionOutputDiscriminants } from './public-union-output-discriminants.js';
+export { readIntentFires } from './read-intent-fires.js';
+export { referenceExists } from './reference-exists.js';
+export { resolvedImportBoundary } from './resolved-import-boundary.js';
+export { resourceDeclarations } from './resource-declarations.js';
+export { resourceExists } from './resource-exists.js';
+export { resourceIdGrammar } from './resource-id-grammar.js';
+export { resourceMockCoverage } from './resource-mock-coverage.js';
+export { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
+export { signalGraphCoaching } from './signal-graph-coaching.js';
+export { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+export { surfaceFacetCoherence } from './surface-facet-coherence.js';
+export { trailForkCoaching } from './trail-fork-coaching.js';
+export {
+  forkWithoutPreservedBlaze,
+  markerSchemaUnsupported,
+  versionPinnedCompose,
+} from './trail-versioning-source.js';
+export {
+  deprecationWithoutGuidance,
+  pendingForce,
+  versionGap,
+  versionWithoutExamples,
+} from './trail-versioning-topo.js';
+export { unmaterializedActivationSource } from './unmaterialized-activation-source.js';
+export { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+export { validDetourContract } from './valid-detour-contract.js';
 export { validDescribeRefs } from './valid-describe-refs.js';
+export { webhookRouteCollision } from './webhook-route-collision.js';
 
-/**
- * All built-in warden rules, keyed by rule name.
- *
- * Rules that duplicate validateTopo checks (follows-trails-exist,
- * no-recursive-follows, event-origins-exist, examples-match-schema,
- * require-output-schema) and follows-matches-calls (now covered by
- * testExamples follows coverage) have been removed.
- */
+/** All built-in warden rules, keyed by rule name. */
 export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   string,
   WardenRule
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
+  [circularRefs.name, circularRefs],
+  [contourExists.name, contourExists],
   [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+  [composesDeclarations.name, composesDeclarations],
+  [deadInternalTrail.name, deadInternalTrail],
+  [deadPublicTrail.name, deadPublicTrail],
+  [draftFileMarking.name, draftFileMarking],
+  [draftVisibleDebt.name, draftVisibleDebt],
+  [errorMappingCompleteness.name, errorMappingCompleteness],
+  [exampleValid.name, exampleValid],
+  [firesDeclarations.name, firesDeclarations],
+  [incompleteCrud.name, incompleteCrud],
+  [intentPropagation.name, intentPropagation],
+  [layerFieldNameDrift.name, layerFieldNameDrift],
+  [missingVisibility.name, missingVisibility],
+  [missingReconcile.name, missingReconcile],
+  [onReferencesExist.name, onReferencesExist],
+  [orphanedSignal.name, orphanedSignal],
+  [ownerProjectionParity.name, ownerProjectionParity],
+  [publicExportExampleCoverage.name, publicExportExampleCoverage],
+  [publicInternalDeepImports.name, publicInternalDeepImports],
+  [resourceDeclarations.name, resourceDeclarations],
+  [readIntentFires.name, readIntentFires],
+  [referenceExists.name, referenceExists],
+  [resolvedImportBoundary.name, resolvedImportBoundary],
+  [resourceIdGrammar.name, resourceIdGrammar],
+  [resourceExists.name, resourceExists],
+  [resourceMockCoverage.name, resourceMockCoverage],
   [preferSchemaInference.name, preferSchemaInference],
+  [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
+  [surfaceFacetCoherence.name, surfaceFacetCoherence],
+  [trailForkCoaching.name, trailForkCoaching],
   [validDescribeRefs.name, validDescribeRefs],
-  [validDetourRefs.name, validDetourRefs],
+  [noDevPermitInSource.name, noDevPermitInSource],
+  [noDestructuredCompose.name, noDestructuredCompose],
   [noDirectImplementationCall.name, noDirectImplementationCall],
+  [noLegacyLayerImports.name, noLegacyLayerImports],
+  [noNativeErrorResult.name, noNativeErrorResult],
+  [noRedundantResultErrorWrap.name, noRedundantResultErrorWrap],
+  [noRetiredCrossVocabulary.name, noRetiredCrossVocabulary],
   [noSyncResultAssumption.name, noSyncResultAssumption],
   [implementationReturnsResult.name, implementationReturnsResult],
-  [noThrowInDetourTarget.name, noThrowInDetourTarget],
-  [noDirectImplInRoute.name, noDirectImplInRoute],
+  [noThrowInDetourRecover.name, noThrowInDetourRecover],
+  [noTopLevelSurface.name, noTopLevelSurface],
+  [unreachableDetourShadowing.name, unreachableDetourShadowing],
+  [wardenExportSymmetry.name, wardenExportSymmetry],
+  [wardenRulesUseAst.name, wardenRulesUseAst],
+  [forkWithoutPreservedBlaze.name, forkWithoutPreservedBlaze],
+  [markerSchemaUnsupported.name, markerSchemaUnsupported],
+  [versionPinnedCompose.name, versionPinnedCompose],
 ]);
+
+/**
+ * Built-in topo-aware warden rules, keyed by rule name.
+ *
+ * These rules inspect the compiled runtime trail graph once per topo,
+ * rather than scanning source files. Kept in a separate registry because
+ * their dispatch shape differs from `WardenRule` / `ProjectAwareWardenRule`.
+ *
+ * @remarks
+ * Topo-aware rules only fire when the warden runtime is invoked with a
+ * resolved `Topo` (see `WardenOptions.topo`). Runs without a topo — e.g.
+ * pure source-directory lints — silently skip this registry. Rules
+ * registered here must tolerate non-execution when no topo is available.
+ */
+export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
+  new Map<string, TopoAwareWardenRule>([
+    [activationOrphan.name, activationOrphan],
+    [cliCommandRouteCoherence.name, cliCommandRouteCoherence],
+    [duplicatePublicContract.name, duplicatePublicContract],
+    [incompleteAccessorForStandardOp.name, incompleteAccessorForStandardOp],
+    [libraryProjectionCoherence.name, libraryProjectionCoherence],
+    [permitGovernance.name, permitGovernance],
+    [publicOutputSchema.name, publicOutputSchema],
+    [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],
+    [scheduledDestroyIntent.name, scheduledDestroyIntent],
+    [signalGraphCoaching.name, signalGraphCoaching],
+    [unmaterializedActivationSource.name, unmaterializedActivationSource],
+    [validDetourContract.name, validDetourContract],
+    [deprecationWithoutGuidance.name, deprecationWithoutGuidance],
+    [pendingForce.name, pendingForce],
+    [versionGap.name, versionGap],
+    [versionWithoutExamples.name, versionWithoutExamples],
+    [webhookRouteCollision.name, webhookRouteCollision],
+  ]);

package/src/rules/intent-propagation.ts

@@ -0,0 +1,127 @@
+import type { Intent } from '@ontrails/core';
+import {
+  collectNamedTrailIds,
+  collectTrailIntentsById,
+  extractDefinitionComposeTargetIds,
+  findTrailDefinitions,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const buildIntentPropagationDiagnostic = (
+  trailId: string,
+  targetTrailId: string,
+  targetIntent: Exclude<Intent, 'read'>,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares intent: 'read' but composes "${targetTrailId}" with intent: '${targetIntent}'. Read trails must not compose write or destroy side effects.`,
+  rule: 'intent-propagation',
+  severity: 'warn',
+});
+
+const buildDiagnosticsForComposeTargets = (
+  trailId: string,
+  targetTrailIds: readonly string[],
+  filePath: string,
+  line: number,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] =>
+  targetTrailIds.flatMap((targetTrailId) => {
+    const targetIntent = trailIntentsById.get(targetTrailId);
+    if (!targetIntent || targetIntent === 'read') {
+      return [];
+    }
+
+    return [
+      buildIntentPropagationDiagnostic(
+        trailId,
+        targetTrailId,
+        targetIntent,
+        filePath,
+        line
+      ),
+    ];
+  });
+
+const buildDiagnosticsForTrail = (
+  def: ReturnType<typeof findTrailDefinitions>[number],
+  sourceCode: string,
+  filePath: string,
+  namedTrailIds: ReadonlyMap<string, string>,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (def.kind !== 'trail' || trailIntentsById.get(def.id) !== 'read') {
+    return [];
+  }
+
+  return buildDiagnosticsForComposeTargets(
+    def.id,
+    extractDefinitionComposeTargetIds(def.config, sourceCode, namedTrailIds),
+    filePath,
+    offsetToLine(sourceCode, def.start),
+    trailIntentsById
+  );
+};
+
+const checkIntentPropagation = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const namedTrailIds = collectNamedTrailIds(ast);
+  return findTrailDefinitions(ast).flatMap((def) =>
+    buildDiagnosticsForTrail(
+      def,
+      sourceCode,
+      filePath,
+      namedTrailIds,
+      trailIntentsById
+    )
+  );
+};
+
+export const intentPropagation: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkIntentPropagation(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectTrailIntentsById(ast) : new Map<string, Intent>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localTrailIntentsById = ast
+      ? collectTrailIntentsById(ast)
+      : new Map<string, Intent>();
+    const trailIntentsById = new Map(localTrailIntentsById);
+    for (const [trailId, intent] of context.trailIntentsById ?? []) {
+      trailIntentsById.set(trailId, intent);
+    }
+    return checkIntentPropagation(ast, sourceCode, filePath, trailIntentsById);
+  },
+  description:
+    "Warn when a trail declaring intent: 'read' composes a trail whose normalized intent is write or destroy.",
+  name: 'intent-propagation',
+  severity: 'warn',
+};

package/src/rules/layer-field-name-drift.ts

@@ -0,0 +1,102 @@
+import { sep } from 'node:path';
+
+import {
+  getNodeCallee,
+  getNodeId,
+  getNodeInit,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'layer-field-name-drift';
+
+const LEGACY_RESERVED_SET_NAMES = new Set(['META_FLAG_CANDIDATES']);
+
+const normalizePath = (filePath: string): string =>
+  filePath.split(sep).join('/');
+
+const isSurfaceSourceFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return /(^|\/)packages\/(cli|http|mcp)\/src\//.test(normalized);
+};
+
+const isTestFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return (
+    normalized.includes('/__tests__/') || /\.test\.[cm]?tsx?$/.test(normalized)
+  );
+};
+
+const looksLikeLayerReservedNameSet = (name: string): boolean => {
+  const lower = name.toLowerCase();
+  return (
+    LEGACY_RESERVED_SET_NAMES.has(name) ||
+    (lower.includes('layer') &&
+      lower.includes('reserved') &&
+      (lower.includes('name') || lower.includes('flag')))
+  );
+};
+
+const isSetConstruction = (node: AstNode | undefined): boolean => {
+  if (node?.type !== 'NewExpression') {
+    return false;
+  }
+  const callee = getNodeCallee(node);
+  return identifierName(callee) === 'Set';
+};
+
+const isLocalReservedSetInitializer = (node: AstNode | undefined): boolean =>
+  node?.type === 'ArrayExpression' || isSetConstruction(node);
+
+const buildDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  name: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message: `layer-field-name-drift: surface-local reserved name set "${name}" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+export const layerFieldNameDrift: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!isSurfaceSourceFile(filePath) || isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (node.type !== 'VariableDeclarator') {
+        return;
+      }
+      const id = getNodeId(node);
+      const init = getNodeInit(node);
+      const name = identifierName(id);
+      if (
+        name &&
+        looksLikeLayerReservedNameSet(name) &&
+        isLocalReservedSetInitializer(init)
+      ) {
+        diagnostics.push(buildDiagnostic(sourceCode, filePath, node, name));
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Prevent surface-local reserved-name sets from drifting layer input field projection across surfaces.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/library-projection-coherence.ts

@@ -0,0 +1,100 @@
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type {
+  TopoGraph,
+  TopoGraphLibraryProjection,
+} from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'library-projection-coherence';
+const TOPO_FILE = '<topo>';
+
+const resolveGraph = (
+  topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
+  graph: TopoGraph | undefined
+): TopoGraph => graph ?? deriveTopoGraph(topo);
+
+const renderTrailIds = (trailIds: readonly string[]): string =>
+  trailIds
+    .toSorted((left, right) => left.localeCompare(right))
+    .map((trailId) => `"${trailId}"`)
+    .join(', ');
+
+const collisionDiagnostic = (
+  exportName: string,
+  trailIds: readonly string[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection export collision on "${exportName}": trails ${renderTrailIds(trailIds)} derive the same package export. Rename one trail or add a library export override before materializing the generated package.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const missingTargetDiagnostic = (
+  exportName: string,
+  trailId: string
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection export "${exportName}" targets unknown trail "${trailId}". Resolved library exports must stay attached to existing trail contracts.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const duplicateExportDiagnostic = (
+  exportName: string,
+  trailIds: readonly string[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection contains duplicate export "${exportName}" for trails ${renderTrailIds(trailIds)}. The resolved projection should record the collision and keep only one emitted export.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const collectDuplicateExportDiagnostics = (
+  projection: TopoGraphLibraryProjection
+): readonly WardenDiagnostic[] => {
+  const trailIdsByExport = new Map<string, string[]>();
+  for (const entry of projection.exports) {
+    const trailIds = trailIdsByExport.get(entry.exportName) ?? [];
+    trailIds.push(entry.trailId);
+    trailIdsByExport.set(entry.exportName, trailIds);
+  }
+  return [...trailIdsByExport.entries()]
+    .filter(([, trailIds]) => trailIds.length > 1)
+    .map(([exportName, trailIds]) =>
+      duplicateExportDiagnostic(exportName, trailIds)
+    );
+};
+
+const collectMissingTargetDiagnostics = (
+  projection: TopoGraphLibraryProjection,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] =>
+  projection.exports
+    .filter((entry) => !knownTrailIds.has(entry.trailId))
+    .map((entry) => missingTargetDiagnostic(entry.exportName, entry.trailId));
+
+export const libraryProjectionCoherence: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = resolveGraph(topo, context?.graph);
+    if (!graph.library) {
+      return [];
+    }
+
+    const knownTrailIds = new Set(topo.trails.keys());
+    return [
+      ...graph.library.collisions.map((collision) =>
+        collisionDiagnostic(collision.exportName, collision.trailIds)
+      ),
+      ...collectDuplicateExportDiagnostics(graph.library),
+      ...collectMissingTargetDiagnostics(graph.library, knownTrailIds),
+    ];
+  },
+  description:
+    'Ensure resolved library projection exports are collision-free and target existing trails.',
+  name: RULE_NAME,
+  severity: 'error',
+};