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

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 52ms on 56 files with 93 rules using 24 threads.
+Finished in 73ms on 126 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @ontrails/warden
 
+## 1.0.0-beta.15
+
+### Minor Changes
+
+- 4ad6b25: Lexicon rename cleanup (ADR-0023). Breaking for `@ontrails/core`, `@ontrails/cli`, and `@ontrails/tracing` at the boundary; internal-only churn for `@ontrails/warden`.
+
+  - **core**: the topo store schema renames `topo_provisions` / `topo_trail_provisions` → `topo_resources` / `topo_trail_resources` and `provision_count` → `resource_count`. Schema version bumped v4→v5. Stores still carrying the legacy schema are detected on open, dropped, and recreated from the new DDL — previous topo saves are cleared. Stored-data helpers `listTopoStoreProvisions` / `getTopoStoreProvision` / `readProvisionUsage` / `mapProvisionRow` renamed to their `resource` counterparts. TS row types `TopoTrailProvisionRow` / `TopoProvisionRow` renamed to `TopoTrailResourceRow` / `TopoResourceRow`.
+  - **cli**: CLI output mode env vars are now derived from the topo name per ADR-0023. Legacy globals `TRAILS_JSON` / `TRAILS_JSONL` are no longer honored — a topo named `stash` reads `STASH_JSON` / `STASH_JSONL`. `ActionResultContext` gains a `topoName: string` field; `resolveOutputMode(flags, topoName)` takes a topo name argument.
+  - **tracing**: legacy `.trails/dev/tracker.db` migration path removed. Any user still running a pre-rename beta build with a `tracker.db` should delete it or migrate before upgrading.
+  - **warden**: internal-only rename of `provisionDeclarations` / `provisionExists` rules and their trails to `resourceDeclarations` / `resourceExists`. No behavior change.
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/permits@1.0.0-beta.15
+  - @ontrails/schema@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @ontrails/core@1.0.0-beta.14
+  - @ontrails/schema@1.0.0-beta.14
+
 ## 1.0.0-beta.13
 
 ### Minor Changes

package/README.md

@@ -1,8 +1,8 @@
 # @ontrails/warden
 
-AST-based code convention rules for Trails. 13 lint rules that catch contract violations at development time, plus lock drift detection and CI formatters.
+AST-based code convention rules for Trails. Built-in lint rules catch contract violations at development time, alongside lock drift detection and CI formatters.
 
-Structural checks (cross target existence, declared provision existence, recursive crossing, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
+Structural checks (cross target existence, declared resource existence, recursive crossing, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
 
 ## Usage
 
@@ -20,7 +20,7 @@ Or programmatically:
 ```typescript
 import { runWarden, formatWardenReport } from '@ontrails/warden';
 
-const report = await runWarden(app, { exitCode: true });
+const report = await runWarden({ topo: graph });
 console.log(formatWardenReport(report));
 ```
 
@@ -30,17 +30,20 @@ console.log(formatWardenReport(report));
 | --- | --- | --- |
 | `no-throw-in-implementation` | error | `throw` inside blaze bodies |
 | `implementation-returns-result` | error | Blaze functions returning raw values instead of `Result` |
-| `context-no-trailhead-types` | error | Trailhead type imports (`Request`, `McpSession`) in trail files |
-| `no-sync-result-assumption` | error | Missing `await` on `.trailhead()` results |
-| `valid-detour-refs` | error | Detour targets that do not exist in the topo |
-| `no-throw-in-detour-target` | error | `throw` inside detour target trails |
-| `no-direct-implementation-call` | warn | Direct `.trailhead()` calls bypassing `ctx.cross()` |
-| `no-direct-impl-in-route` | warn | Direct `.trailhead()` calls inside trail bodies with `crosses` |
+| `context-no-surface-types` | error | Surface type imports (`Request`, `McpSession`) in trail files |
+| `no-sync-result-assumption` | error | Missing `await` on `.blaze()` results |
+| `valid-detour-contract` | error | Detours with non-constructor `on` values or non-callable `recover` values |
+| `no-throw-in-detour-recover` | error | `throw` inside detour `recover` functions |
+| `unreachable-detour-shadowing` | error | Later detours made unreachable by earlier same-or-broader `on:` error types |
+| `no-direct-implementation-call` | warn | Direct `.blaze()` calls bypassing `ctx.cross()` |
+| `no-direct-impl-in-route` | warn | Direct `.blaze()` calls inside trail bodies with `crosses` |
 | `prefer-schema-inference` | warn | Redundant field overrides already derivable from the schema |
 | `cross-declarations` | error/warn | `ctx.cross()` calls that drift from declared `crosses: [...]` |
-| `provision-declarations` | error/warn | `provision.from(ctx)` / `ctx.provision()` usage that drifts from declared `provisions: [...]` |
-| `provision-exists` | error | Declared or referenced provision IDs that do not resolve in project context |
+| `resource-declarations` | error/warn | `resource.from(ctx)` / `ctx.resource()` usage that drifts from declared `resources: [...]` |
+| `resource-exists` | error | Declared or referenced resource IDs that do not resolve in project context |
 | `valid-describe-refs` | warn | `@see` refs in `.describe()` that do not resolve |
+| `draft-file-marking` | error | Draft-bearing files missing `_draft.*` or `*.draft.*` filename markers |
+| `draft-visible-debt` | warn | Draft IDs remaining in source files that need promotion or removal |
 
 ## Drift detection
 
@@ -49,9 +52,9 @@ Warden integrates with `@ontrails/schema` to detect when the topo has changed wi
 ```typescript
 import { checkDrift } from '@ontrails/warden';
 
-const drift = await checkDrift(app);
+const drift = await checkDrift(process.cwd(), graph);
 if (drift.stale) {
-  console.log('lock file is stale -- regenerate with `trails survey generate`');
+  console.log('lock file is stale -- regenerate with `trails topo export`');
 }
 ```
 
@@ -63,7 +66,7 @@ Add to lefthook for pre-push enforcement:
 pre-push:
   commands:
     warden:
-      blaze: trails warden --exit-code
+      run: trails warden --exit-code
       tags: governance
 ```
 
@@ -75,10 +78,14 @@ import { formatGitHubAnnotations, formatJson, formatSummary } from '@ontrails/wa
 
 ## Trail-based API
 
-Every built-in warden rule is also available as a composable trail. This makes rules queryable, testable, and invocable through any Trails trailhead.
+Every built-in warden rule is also available as a composable trail. This makes rules queryable, testable, and invocable through any Trails surface.
 
 ```typescript
-import { wardenTopo, runWardenTrails } from '@ontrails/warden';
+import {
+  runTopoAwareWardenTrails,
+  runWardenTrails,
+  wardenTopo,
+} from '@ontrails/warden';
 
 // Inspect the warden rule trails
 console.log(wardenTopo.ids()); // ['warden.rule.no-throw-in-implementation', ...]
@@ -86,8 +93,11 @@ console.log(wardenTopo.ids()); // ['warden.rule.no-throw-in-implementation', ...
 // Run all rule trails against a source file
 const diagnostics = await runWardenTrails(filePath, sourceCode, {
   knownTrailIds: myApp.ids(),
-  knownProvisionIds: myApp.provisionIds(),
+  knownResourceIds: myApp.resourceIds(),
 });
+
+// Run built-in topo-aware rule trails once against the resolved graph
+const topoDiagnostics = await runTopoAwareWardenTrails(myApp);
 ```
 
 To wrap a custom rule as a trail, use `wrapRule` (imported from `@ontrails/warden/trails/wrap-rule`). This is the same factory used internally to build all built-in rule trails.
@@ -96,12 +106,13 @@ To wrap a custom rule as a trail, use `wrapRule` (imported from `@ontrails/warde
 
 | Export | What it does |
 | --- | --- |
-| `runWarden(app, options?)` | Run all rules and drift checks, return a report |
+| `runWarden(options?)` | Run all rules and drift checks, return a report |
 | `formatWardenReport(report)` | Human-readable report |
-| `checkDrift(app)` | Check if the lock file matches the current topo |
+| `checkDrift(rootDir, topo?)` | Check if the lock file matches the current topo |
 | `wardenRules` | Registry of all built-in rules |
 | `wardenTopo` | `Topo` of all built-in rule trails (one per rule) |
-| `runWardenTrails(filePath, sourceCode, options?)` | Dispatch all rule trails for a file, collect diagnostics |
+| `runWardenTrails(filePath, sourceCode, options?)` | Dispatch file-scoped rule trails for a file, collect diagnostics |
+| `runTopoAwareWardenTrails(topo)` | Dispatch built-in topo-aware rule trails once for a resolved topo |
 | `formatGitHubAnnotations(report)` | GitHub Actions annotation format |
 | `formatJson(report)` | Machine-readable JSON |
 | `formatSummary(report)` | Compact summary line |

package/dist/cli.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Topo } from '@ontrails/core';
 import type { DriftResult } from './drift.js';
-import type { WardenDiagnostic } from './rules/types.js';
+import type { TopoAwareWardenRule, WardenDiagnostic } from './rules/types.js';
 /**
  * Options for the warden CLI runner.
  */
@@ -17,8 +17,25 @@ export interface WardenOptions {
     readonly lintOnly?: boolean | undefined;
     /** Only run drift detection, skip lint rules */
     readonly driftOnly?: boolean | undefined;
-    /** App topology for drift detection. When provided, enables real trailhead lock comparison. */
+    /**
+     * App topology for drift detection. When provided, enables real trailhead
+     * lock comparison and unlocks the topo-aware rule dispatch path.
+     *
+     * @remarks
+     * Topo-aware rules (both built-in `wardenTopoRules` and `extraTopoRules`)
+     * only fire when a `Topo` is supplied. Runs without a topo silently skip
+     * topo-aware dispatch — callers that depend on a topo-aware rule firing
+     * must pass `topo` explicitly.
+     */
     readonly topo?: Topo | undefined;
+    /**
+     * Extra topo-aware rules to run in addition to the built-in registry.
+     *
+     * Primarily a test hook — production callers should register rules via
+     * `wardenTopoRules` in `rules/index.ts`. These rules are only invoked
+     * when `topo` is also supplied (see `topo` remarks).
+     */
+    readonly extraTopoRules?: readonly TopoAwareWardenRule[] | undefined;
 }
 /**
  * Result of a warden run.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9C,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAwND;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,UAAS,aAAkB,KAC1B,OAAO,CAAC,YAAY,CAqBtB,CAAC;AAsDF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,MAmBzD,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAiB9C,OAAO,KAAK,EAGV,mBAAmB,EACnB,gBAAgB,EAEjB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAqiBD;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,UAAS,aAAkB,KAC1B,OAAO,CAAC,YAAY,CAwBtB,CAAC;AA2DF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,MAmBzD,CAAC"}

package/dist/cli.js

@@ -5,9 +5,11 @@
  * and returns a structured report.
  */
 import { resolve } from 'node:path';
+import { getContourReferences } from '@ontrails/core';
 import { checkDrift } from './drift.js';
-import { collectProvisionDefinitionIds, findConfigProperty, findTrailDefinitions, parse, walk, } from './rules/ast.js';
-import { wardenRules } from './rules/index.js';
+import { collectContourDefinitionIds, collectContourReferenceTargetsByName, collectCrudTableIds as collectCrudTableIdsFromAst, collectCrossTargetTrailIds, collectOnTargetSignalIds as collectOnTargetSignalIdsFromAst, collectReconcileTableIds as collectReconcileTableIdsFromAst, collectResourceDefinitionIds, collectSignalDefinitionIds, collectTrailIntentsById, findTrailDefinitions, parse, } from './rules/ast.js';
+import { collectFileCrudCoverage } from './rules/incomplete-crud.js';
+import { wardenRules, wardenTopoRules } from './rules/index.js';
 /**
  * Collect all .ts files under a directory, excluding node_modules, dist, and .git.
  */
@@ -36,6 +38,68 @@ const collectTsFiles = (dir) => {
     }
     return files;
 };
+const createMutableProjectContext = () => ({
+    contourReferencesByName: new Map(),
+    crossTargetTrailIds: new Set(),
+    crudCoverageByEntity: new Map(),
+    crudTableIds: new Set(),
+    knownContourIds: new Set(),
+    knownResourceIds: new Set(),
+    knownSignalIds: new Set(),
+    knownTrailIds: new Set(),
+    onTargetSignalIds: new Set(),
+    reconcileTableIds: new Set(),
+    trailIntentsById: new Map(),
+});
+const addContourReferenceTargets = (context, contourName, targets) => {
+    const existing = context.contourReferencesByName.get(contourName);
+    if (existing) {
+        for (const target of targets) {
+            existing.add(target);
+        }
+        return;
+    }
+    context.contourReferencesByName.set(contourName, new Set(targets));
+};
+const toProjectContext = (context) => ({
+    ...(context.contourReferencesByName.size > 0
+        ? {
+            contourReferencesByName: new Map([...context.contourReferencesByName.entries()].map(([name, targets]) => [name, [...targets]])),
+        }
+        : {}),
+    ...(context.crudTableIds.size > 0
+        ? { crudTableIds: context.crudTableIds }
+        : {}),
+    ...(context.crudCoverageByEntity.size > 0
+        ? {
+            crudCoverageByEntity: new Map([...context.crudCoverageByEntity.entries()].map(([entityId, operations]) => [
+                entityId,
+                new Set(operations),
+            ])),
+        }
+        : {}),
+    crossTargetTrailIds: context.crossTargetTrailIds,
+    knownContourIds: context.knownContourIds,
+    knownResourceIds: context.knownResourceIds,
+    knownSignalIds: context.knownSignalIds,
+    knownTrailIds: context.knownTrailIds,
+    ...(context.onTargetSignalIds.size > 0
+        ? { onTargetSignalIds: context.onTargetSignalIds }
+        : {}),
+    ...(context.reconcileTableIds.size > 0
+        ? { reconcileTableIds: context.reconcileTableIds }
+        : {}),
+    trailIntentsById: context.trailIntentsById,
+});
+const collectKnownContourIds = (sourceCode, filePath, knownContourIds) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const id of collectContourDefinitionIds(ast)) {
+        knownContourIds.add(id);
+    }
+};
 const collectKnownTrailIds = (sourceCode, filePath, knownTrailIds) => {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
@@ -45,35 +109,80 @@ const collectKnownTrailIds = (sourceCode, filePath, knownTrailIds) => {
         knownTrailIds.add(def.id);
     }
 };
-const collectDetourTargetTrailIds = (sourceCode, filePath, detourTargetTrailIds) => {
+const collectCrossedTrailIds = (sourceCode, filePath, crossTargetTrailIds) => {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
         return;
     }
-    for (const def of findTrailDefinitions(ast)) {
-        const detoursProp = findConfigProperty(def.config, 'detours');
-        if (!detoursProp) {
-            continue;
+    for (const id of collectCrossTargetTrailIds(ast, sourceCode)) {
+        crossTargetTrailIds.add(id);
+    }
+};
+const collectKnownResourceIds = (sourceCode, filePath, knownResourceIds) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const id of collectResourceDefinitionIds(ast)) {
+        knownResourceIds.add(id);
+    }
+};
+const collectKnownSignalIds = (sourceCode, filePath, knownSignalIds) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const id of collectSignalDefinitionIds(ast)) {
+        knownSignalIds.add(id);
+    }
+};
+const collectTrailIntents = (sourceCode, filePath, trailIntentsById) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const [id, intent] of collectTrailIntentsById(ast)) {
+        trailIntentsById.set(id, intent);
+    }
+};
+const collectCrudTableIds = (sourceCode, filePath, crudTableIds) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const id of collectCrudTableIdsFromAst(ast)) {
+        crudTableIds.add(id);
+    }
+};
+const collectOnTargetSignalIds = (sourceCode, filePath, onTargetSignalIds) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const id of collectOnTargetSignalIdsFromAst(ast, sourceCode)) {
+        onTargetSignalIds.add(id);
+    }
+};
+const collectCrudCoverageByEntity = (sourceCode, filePath, coverageByEntity) => {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+        return;
+    }
+    for (const [entityId, operations] of collectFileCrudCoverage(ast, sourceCode)) {
+        const bucket = coverageByEntity.get(entityId) ?? new Set();
+        for (const operation of operations) {
+            bucket.add(operation);
         }
-        // Walk the detours value for string literals that look like trail IDs
-        walk(detoursProp, (node) => {
-            if (node.type !== 'Literal') {
-                return;
-            }
-            const val = node.value;
-            if (val && val.includes('.')) {
-                detourTargetTrailIds.add(val);
-            }
-        });
+        coverageByEntity.set(entityId, bucket);
     }
 };
-const collectKnownProvisionIds = (sourceCode, filePath, knownProvisionIds) => {
+const collectReconcileTableIds = (sourceCode, filePath, reconcileTableIds) => {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
         return;
     }
-    for (const id of collectProvisionDefinitionIds(ast)) {
-        knownProvisionIds.add(id);
+    for (const id of collectReconcileTableIdsFromAst(ast)) {
+        reconcileTableIds.add(id);
     }
 };
 const loadSourceFiles = async (rootDir) => {
@@ -91,65 +200,145 @@ const loadSourceFiles = async (rootDir) => {
     }
     return sourceFiles;
 };
-const collectTopoDetourTargetTrailIds = (appTopo) => {
-    const detourTargetTrailIds = new Set();
+const collectTopoKnownIds = (appTopo, context) => {
+    for (const name of appTopo.contours.keys()) {
+        context.knownContourIds.add(name);
+    }
+    for (const id of appTopo.trails.keys()) {
+        context.knownTrailIds.add(id);
+    }
+    for (const id of appTopo.resources.keys()) {
+        context.knownResourceIds.add(id);
+    }
+    for (const id of appTopo.signals.keys()) {
+        context.knownSignalIds.add(id);
+    }
+};
+const collectTopoCrossesAndIntents = (appTopo, context) => {
     for (const trail of appTopo.trails.values()) {
-        const detours = trail['detours'];
-        if (!detours) {
-            continue;
-        }
-        for (const targets of Object.values(detours)) {
-            for (const id of targets) {
-                detourTargetTrailIds.add(id);
-            }
+        context.trailIntentsById.set(trail.id, trail.intent);
+        for (const crossedTrailId of trail.crosses) {
+            context.crossTargetTrailIds.add(crossedTrailId);
         }
     }
-    return detourTargetTrailIds;
 };
-const buildProjectContextFromTopo = (appTopo) => {
-    const knownTrailIds = new Set(appTopo.trails.keys());
-    const knownProvisionIds = new Set(appTopo.provisions.keys());
-    const detourTargetTrailIds = collectTopoDetourTargetTrailIds(appTopo);
-    return {
-        detourTargetTrailIds,
-        knownProvisionIds,
-        knownTrailIds,
-    };
+const collectTopoContourReferences = (appTopo, context) => {
+    for (const contour of appTopo.listContours()) {
+        addContourReferenceTargets(context, contour.name, getContourReferences(contour).map((reference) => reference.contour));
+    }
+};
+const collectTopoTrailContext = (appTopo, context) => {
+    collectTopoKnownIds(appTopo, context);
+    collectTopoCrossesAndIntents(appTopo, context);
+    collectTopoContourReferences(appTopo, context);
+};
+const collectFileKnownIds = (sourceFile, context) => {
+    collectKnownContourIds(sourceFile.sourceCode, sourceFile.filePath, context.knownContourIds);
+    collectKnownTrailIds(sourceFile.sourceCode, sourceFile.filePath, context.knownTrailIds);
+    collectKnownResourceIds(sourceFile.sourceCode, sourceFile.filePath, context.knownResourceIds);
+    collectKnownSignalIds(sourceFile.sourceCode, sourceFile.filePath, context.knownSignalIds);
+};
+const collectFileTrailRelationships = (sourceFile, context) => {
+    collectCrossedTrailIds(sourceFile.sourceCode, sourceFile.filePath, context.crossTargetTrailIds);
+    collectTrailIntents(sourceFile.sourceCode, sourceFile.filePath, context.trailIntentsById);
+};
+const collectFileSupplementalProjectContext = (sourceFile, context) => {
+    collectCrudTableIds(sourceFile.sourceCode, sourceFile.filePath, context.crudTableIds);
+    collectOnTargetSignalIds(sourceFile.sourceCode, sourceFile.filePath, context.onTargetSignalIds);
+    collectReconcileTableIds(sourceFile.sourceCode, sourceFile.filePath, context.reconcileTableIds);
+    collectCrudCoverageByEntity(sourceFile.sourceCode, sourceFile.filePath, context.crudCoverageByEntity);
+};
+const collectFileProjectContext = (sourceFile, context) => {
+    collectFileKnownIds(sourceFile, context);
+    collectFileTrailRelationships(sourceFile, context);
+    collectFileSupplementalProjectContext(sourceFile, context);
 };
-const buildProjectContextFromFiles = (sourceFiles) => {
-    const knownTrailIds = new Set();
-    const knownProvisionIds = new Set();
-    const detourTargetTrailIds = new Set();
+const collectFileContourReferences = (sourceFile, context) => {
+    const ast = parse(sourceFile.filePath, sourceFile.sourceCode);
+    if (!ast) {
+        return;
+    }
+    const referencesByName = collectContourReferenceTargetsByName(ast, context.knownContourIds);
+    for (const [contourName, targets] of referencesByName) {
+        addContourReferenceTargets(context, contourName, targets);
+    }
+};
+const buildProjectContext = (sourceFiles, appTopo) => {
+    const context = createMutableProjectContext();
+    if (appTopo) {
+        collectTopoTrailContext(appTopo, context);
+        for (const sourceFile of sourceFiles) {
+            collectFileSupplementalProjectContext(sourceFile, context);
+        }
+    }
+    else {
+        for (const sourceFile of sourceFiles) {
+            collectFileProjectContext(sourceFile, context);
+        }
+    }
     for (const sourceFile of sourceFiles) {
-        collectKnownTrailIds(sourceFile.sourceCode, sourceFile.filePath, knownTrailIds);
-        collectKnownProvisionIds(sourceFile.sourceCode, sourceFile.filePath, knownProvisionIds);
-        collectDetourTargetTrailIds(sourceFile.sourceCode, sourceFile.filePath, detourTargetTrailIds);
+        collectFileContourReferences(sourceFile, context);
     }
+    return toProjectContext(context);
+};
+const isProjectAwareRule = (rule) => 'checkWithContext' in rule;
+const topoRuleFailureDiagnostic = (rule, error) => {
+    const cause = error instanceof Error ? error : new Error(String(error));
     return {
-        detourTargetTrailIds,
-        knownProvisionIds,
-        knownTrailIds,
+        filePath: '<topo>',
+        line: 1,
+        message: `Topo-aware rule "${rule.name}" threw: ${cause.message}`,
+        rule: rule.name,
+        severity: 'error',
     };
 };
-const isProjectAwareRule = (rule) => 'checkWithContext' in rule;
 /**
- * Lint all files against all warden rules.
+ * Run all registered topo-aware rules against the resolved topo.
+ *
+ * Topo-aware rules fire exactly once per run (not per file) because they
+ * inspect the compiled trail graph, not source text.
  */
-const lintFiles = async (rootDir, appTopo) => {
-    const allDiagnostics = [];
-    const sourceFiles = await loadSourceFiles(rootDir);
-    const context = appTopo
-        ? buildProjectContextFromTopo(appTopo)
-        : buildProjectContextFromFiles(sourceFiles);
+const lintTopo = async (appTopo, extraTopoRules) => {
+    const diagnostics = [];
+    const rules = [
+        ...wardenTopoRules.values(),
+        ...extraTopoRules,
+    ];
+    for (const rule of rules) {
+        try {
+            diagnostics.push(...(await rule.checkTopo(appTopo)));
+        }
+        catch (error) {
+            diagnostics.push(topoRuleFailureDiagnostic(rule, error));
+        }
+    }
+    return diagnostics;
+};
+const lintSourceFiles = (sourceFiles, context) => {
+    const diagnostics = [];
     for (const sourceFile of sourceFiles) {
         for (const rule of wardenRules.values()) {
             if (isProjectAwareRule(rule)) {
-                allDiagnostics.push(...rule.checkWithContext(sourceFile.sourceCode, sourceFile.filePath, context));
+                diagnostics.push(...rule.checkWithContext(sourceFile.sourceCode, sourceFile.filePath, context));
                 continue;
             }
-            allDiagnostics.push(...rule.check(sourceFile.sourceCode, sourceFile.filePath));
+            diagnostics.push(...rule.check(sourceFile.sourceCode, sourceFile.filePath));
         }
     }
+    return diagnostics;
+};
+/**
+ * Lint all files against all warden rules.
+ */
+const lintFiles = async (rootDir, appTopo, extraTopoRules = []) => {
+    const sourceFiles = await loadSourceFiles(rootDir);
+    const context = buildProjectContext(sourceFiles, appTopo);
+    const allDiagnostics = [
+        ...lintSourceFiles(sourceFiles, context),
+    ];
+    if (appTopo) {
+        allDiagnostics.push(...(await lintTopo(appTopo, extraTopoRules)));
+    }
     return allDiagnostics;
 };
 /**
@@ -159,7 +348,7 @@ export const runWarden = async (options = {}) => {
     const rootDir = resolve(options.rootDir ?? process.cwd());
     const allDiagnostics = options.driftOnly
         ? []
-        : await lintFiles(rootDir, options.topo);
+        : await lintFiles(rootDir, options.topo, options.extraTopoRules ?? []);
     const drift = options.lintOnly
         ? null
         : await checkDrift(rootDir, options.topo);
@@ -169,7 +358,9 @@ export const runWarden = async (options = {}) => {
         diagnostics: allDiagnostics,
         drift,
         errorCount,
-        passed: errorCount === 0 && !(drift?.stale ?? false),
+        passed: errorCount === 0 &&
+            !(drift?.stale ?? false) &&
+            drift?.blockedReason === undefined,
         warnCount,
     };
 };
@@ -196,8 +387,11 @@ const formatDriftSection = (drift) => {
     if (drift === null) {
         return [];
     }
+    if (drift.blockedReason !== undefined) {
+        return [`Drift: blocked (${drift.blockedReason})`, ''];
+    }
     const label = drift.stale
-        ? 'Drift: trailhead.lock is stale (regenerate with `trails survey generate`)'
+        ? 'Drift: trails.lock is stale (regenerate with `trails topo export`)'
         : 'Drift: clean';
     return [label, ''];
 };
@@ -212,7 +406,10 @@ const formatResultLine = (report) => {
     if (report.errorCount > 0) {
         parts.push(`${report.errorCount} errors`);
     }
-    if (report.drift?.stale) {
+    if (report.drift?.blockedReason !== undefined) {
+        parts.push('established exports blocked');
+    }
+    else if (report.drift?.stale) {
         parts.push('drift detected');
     }
     return `Result: FAIL (${parts.join(', ')})`;