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

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @ontrails/warden
 
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`f42ca6e`](https://github.com/outfitter-dev/trails/commit/f42ca6e40b29155acec446e5bf44e52e014466bd): Hard cutover: the CLI consumes `cli` bindings from the app-authored surfaces overlay. Scalar bindings behave identically to the removed cliAliases (parity-tested) — the binding name splits on `.` into a transparent synonym command path for exactly one trail. List bindings arrive as command groups: each expanded member trail gets a group-prefixed route that dispatches the member trail with its identity preserved, and a singleton list stays a group. Expansion is fail-fast boundary validation: a scalar binding resolving to zero or multiple trails, or a group with an empty member union, is a `ValidationError` naming the binding. `DeriveTopoGraphOptions.cliAliases`, the `cliAliases`/`trailsCliAliases` app-module export convention, and the per-kind compile lift are deleted; `deriveCliCommands`/`createProgram` take `overlays` instead of `aliases`, and both topo-graph derivation pipelines expand the same bindings through one shared helper so runtime CLI routes and lock routes come from one semantic. A leftover legacy export is now a Warden error (`no-legacy-cli-alias-export`) naming the `surfaceOverlay({ cli: { ... } })` rewrite.
+
+  This is a breaking API removal shipped under the lockstep beta patch convention (pre-1.0 hard-cutover posture, zero external adoption); the removed options have no deprecation window by design.
+
+- [`bafde1f`](https://github.com/outfitter-dev/trails/commit/bafde1fc8172abb8d8617f69a3c7a70667626d10): Fresh derivations now collect app-module overlays through the shared channel compile uses. `@ontrails/adapter-kit` exports `resolveTrailsOverlays()`, the one reader of an app module's `trailsOverlays` export; the compile-path fresh app lease and Warden's fresh topo loading both go through it, making per-namespace drift asymmetry structurally impossible. Warden drift checks (`checkDrift` now accepts derive options carrying overlays) and the topo-aware rule context graph derive with the same overlays the committed lock embeds, so rules like `surface-overlay-coherence` fire on standard runs. Stale drift results name the drifted overlay namespaces (`DriftResult.driftedOverlayNamespaces`) and point at `trails compile` as the remediation.
+- [`b077fb7`](https://github.com/outfitter-dev/trails/commit/b077fb7ba6d9724cac6f0e59bc3fec9aec28984c): Add the export-restructure Regrade class family (TRL-1210). `export-restructure:cli-aliases` inverts legacy `cliAliases`/`trailsCliAliases` exports into `surfaceOverlay({ cli })` bindings inside the module's `trailsOverlays` export — adding the `@ontrails/core` import, deleting the legacy export, and routing anything it cannot prove safe (computed keys, spreads, in-module `aliases:` references) to `needs-review` with the exact target shape named. `export-restructure:mcp-trailheads` projects call-site MCP trailhead maps into `surfaceOverlay({ mcp })` group bindings: it rewrites in place when the same module exports `trailsOverlays`, and otherwise emits a classified `needs-review` handoff naming the module-overlay target while the call-site map stays as the richer-metadata override-in-context. Warden's fix-class union grows to `'export-restructure' | 'term-rewrite'`, `no-legacy-cli-alias-export` now advertises the `export-restructure` class, and `loadWardenRegradeClasses` supersedes `loadWardenTermRewriteClasses` (still exported) as the full Warden-routed class loader. Class-mode Regrade also gains the full plan lifecycle: `trails regrade plan --type class --class-ids ...` writes a `.trails/regrade/<slug>.json` plan carrying class ids, scope, and intent, `regrade check` re-runs the dry run and gates on outstanding rewrites or review, and `regrade apply` applies and graduates the plan to `.trails/regrade/history/<slug>-<hash>.json` — the same plan → check → apply → history evidence trail vocabulary regrades already had, now available to structural transforms. The class family ships for downstream apps bridging the pre-1.0 gap, so pre-cutover alias exports and trailhead maps migrate mechanically instead of by hand.
+- [`81373bc`](https://github.com/outfitter-dev/trails/commit/81373bc5e980bb06d56fb06af4f0986f72e318c7): Wave-2 MCP cutover to the app-authored `surfaces` overlay. The overlay's `mcp` bindings are now the authored, lockable default for the MCP surface: a list binding derives one grouped trailhead tool (member selection in `{ trail, input }`, member identity preserved in `{ trail, output }`, deterministic derived description), and a scalar binding derives an additional tool synonym whose MCP-safe name is published verbatim and must expand to exactly one trail. `deriveMcpTools`/`createServer` accept the new `overlays` option; `@ontrails/core` gains `expandMcpSurfaceBindings` and `deriveMcpTrailheadDescription`.
+
+  The call-site `CreateServerOptions.trailheads` map survives as permanent override-in-context design, not a compatibility bridge: when both channels are present, the call-site map wins at runtime. Warden's new `trailhead-override-divergence` rule (warn) names both sides when a call-site map's binding names or member selectors diverge from the authored overlay default.
+
+  Topographer now derives `graph.trailheads` from the overlay's `mcp` list bindings in both `deriveTopoGraph` and the store-side graph build, so trailhead facts flow from compiled locks into Wayfinder reads for the first time. The never-wired `DeriveTopoGraphOptions.trailheads` option and the `TopoGraphTrailheadDeclaration`/`TopoGraphTrailheadTrailSelector` types are removed — a beta-window hard cutover of an option no caller could reach; author the equivalent `mcp` list binding in `surfaceOverlay({ mcp })` instead.
+
+- [`820b4ad`](https://github.com/outfitter-dev/trails/commit/820b4ad9c40ea383b3c489a05fe7e4b2328e324f): Add `surfaceOverlay` — the shared surface-naming schema (scalar binding = synonym, list binding = grouped entry, singleton list stays a group) with app-authored/adapter-derived overlay provenance enforced at collection and consumption, and the `surface-overlay-coherence` Warden rule. MCP tool-name derivation moves to `@ontrails/core` (`deriveMcpToolName`) so the surface and governance read one projection; `@ontrails/mcp`'s `deriveToolName` now delegates to it. The coherence rule activates on standard warden runs once fresh derivations collect app-module overlays through the shared compile channel (TRL-1209, next in this stack).
+- [`58db715`](https://github.com/outfitter-dev/trails/commit/58db715209442604fe58f5004fec37426c5969b1): `duplicate-public-contract` now includes contour anchoring in the normalized contract fingerprint, so factory CRUD trails derived against different contours (for example two tables' `delete` trails that both normalize to `{ id } → void` with the same intent) are no longer flagged as duplicates. Genuine duplicates — identical facts with the same or no contour anchoring — still warn, and the diagnostic message names contours among the shared facts.
+- [`7cd0576`](https://github.com/outfitter-dev/trails/commit/7cd0576db8bc421cfd441c126f884e425e2254af): `signal-graph-coaching` no longer flags store-derived table signals (`created`/`updated`/`removed`) that have no consumers. Store resources advertise those signals as available capability, so leaving them unconsumed is a legitimate steady state for store-backed apps. Non-store produced signals without consumers still warn, and dead-signal coaching (no producer and no consumer) is unchanged.
+- [`b9e82a3`](https://github.com/outfitter-dev/trails/commit/b9e82a33546356c93fbc302fb934a83f19f1c2c5): Webhook ingress v2 (TRL-1194, absorbing TRL-1174 and TRL-1175): store-verified, per-endpoint webhook ingress becomes framework-expressible. `webhook()` accepts dynamic path segments (`path: '/hooks/:endpoint'`) whose values are delivered as envelope fields, opt-in `rawBody: true` delivery (a non-JSON body is no longer a surface-level failure — the trail owns payload interpretation), an allowlisted `headers` list delivered lowercased, and `resources` that make `verify` resource-capable: the HTTP surface resolves the declared resources into a context for the verifier and releases them afterwards, so signature checks can reach stores holding per-endpoint secrets. Envelope-mode ingress responds 202 Accepted; classic static webhooks keep their exact-match, JSON-gated, 200 behavior. Core exports `parseWebhookPathParams`, `matchWebhookPath`, `webhookPathPatternsOverlap`, and `createResources`. The `webhook-route-collision` Warden rule now also flags dynamic patterns that overlap other webhook or derived routes, not just exact method/path duplicates.
+
+## 1.0.0-beta.38
+
+### Patch Changes
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+### Patch Changes
+
+- [`6e63e48`](https://github.com/outfitter-dev/trails/commit/6e63e483617b84cb6868d0c4d58d5b5a8d3b9ed2): Complete the v1 grouped surface-entry vocabulary cutover from facet to trailhead, including Regrade dogfood support for governed string literal renames and composed AST rewrite application.
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`1f5659b`](https://github.com/outfitter-dev/trails/commit/1f5659bfe39568f7bbee0503ace8b6e562d3f899): Add the `duplicate-exported-symbol` Warden rule to warn when multiple first-party packages define the same exported symbol name.
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`fc002d5`](https://github.com/outfitter-dev/trails/commit/fc002d5669f4303427e99f45f9998fd0b0172bdb): Add governed AST identifier rename helpers and Warden residue detection for
+  active vocabulary symbol transitions.
+- [`6ca0d8f`](https://github.com/outfitter-dev/trails/commit/6ca0d8f776801eee71ddd86cb88c198eaf5815fd): Add a typed governed-vocabulary transition registry that Warden owns and Regrade
+  can consume for migration planning.
+
 ## 1.0.0-beta.32
 
 ### Patch Changes

package/README.md

@@ -171,7 +171,7 @@ This is the same factory used internally to build all built-in rule trails.
 | --- | --- |
 | `runWarden(options?)` | Run all rules and drift checks, return a report |
 | `formatWardenReport(report)` | Human-readable report |
-| `checkDrift(rootDir, topo?)` | Check if the lock file matches the current topo |
+| `checkDrift(rootDir, topo?, options?)` | Check if the lock file matches the current topo; pass `{ overlays }` from the app module so the comparison graph carries the overlay content compile embeds. Stale results name `driftedOverlayNamespaces` when overlays diverge |
 | `wardenRules` | Registry of all built-in rules |
 | `builtinWardenRuleMetadata` | Tier, scope, lifecycle, and invariant metadata for built-in rules |
 | `getWardenRuleMetadata(ruleOrName)` | Resolve inline or built-in metadata for a Warden rule |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "bin": {
     "warden": "./bin/warden.ts"
   },
@@ -28,21 +28,21 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.32",
-    "@ontrails/cli": "^1.0.0-beta.32",
-    "@ontrails/config": "^1.0.0-beta.32",
-    "@ontrails/permits": "^1.0.0-beta.32",
-    "@ontrails/store": "^1.0.0-beta.32",
+    "@ontrails/adapter-kit": "^1.0.0-beta.39",
+    "@ontrails/cli": "^1.0.0-beta.39",
+    "@ontrails/config": "^1.0.0-beta.39",
+    "@ontrails/permits": "^1.0.0-beta.39",
+    "@ontrails/store": "^1.0.0-beta.39",
     "oxc-parser": "^0.121.0",
     "oxc-resolver": "11.19.1",
     "oxc-walker": "^1.0.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.32"
+    "@ontrails/testing": "^1.0.0-beta.39"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.32",
-    "@ontrails/topographer": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.39",
+    "@ontrails/topographer": "^1.0.0-beta.39"
   }
 }

package/src/cli.ts

@@ -8,10 +8,18 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 
 import { resolveTrailsProjectRoot } from '@ontrails/config';
-import { getContourReferences, matchesAnyPathGlob } from '@ontrails/core';
-import type { Topo } from '@ontrails/core';
+import {
+  getContourReferences,
+  matchesAnyPathGlob,
+  resolveSurfaceOverlayBindings,
+  surfaceBindingsFromLockOverlays,
+} from '@ontrails/core';
+import type { SurfaceBindings, Topo } from '@ontrails/core';
 import { deriveTopoGraph } from '@ontrails/topographer';
-import type { TopoGraph } from '@ontrails/topographer';
+import type {
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+} from '@ontrails/topographer';
 
 import type {
   EffectiveWardenConfig,
@@ -28,11 +36,12 @@ import { resolveWardenConfig } from './config.js';
 import { isDraftMarkedFile } from './draft.js';
 import { applySafeFixesToSource, hasSafeFixEdits } from './fix.js';
 import type { DriftResult } from './drift.js';
-import { checkDrift } from './drift.js';
+import { checkDrift, staleDriftMessage } from './drift.js';
 import { loadProjectWardenRules } from './project-rules.js';
 import type { ProjectWardenRules } from './project-rules.js';
 import {
   collectProjectDocumentationImportResolutions,
+  collectProjectExportedSymbolDefinitions,
   collectProjectImportResolutions,
   collectPublicWorkspaces,
 } from './project-context.js';
@@ -57,10 +66,12 @@ import {
   isWardenSourceScanTarget,
 } from './rules/scan.js';
 import type {
+  AuthoredMcpSurfaceBindingSet,
   ProjectAwareWardenRule,
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenExportedSymbolDefinition,
   WardenGuidanceLink,
   WardenRule,
   WardenRuleTier,
@@ -75,6 +86,12 @@ export interface WardenTopoTarget {
   readonly graph?: TopoGraph | undefined;
   /** Stable app/topo label used to tag topo-aware diagnostics. */
   readonly name?: string | undefined;
+  /**
+   * App-module overlay registrations collected through the shared
+   * `resolveTrailsOverlays` channel, so fresh drift and topo-aware rule
+   * derivations carry the same overlays the committed lock embeds.
+   */
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   /** Resolved topo module to inspect. */
   readonly topo: Topo;
 }
@@ -354,6 +371,9 @@ interface SourceFile {
 }
 
 interface MutableProjectContext {
+  authoredMcpSurfaceBindingSets:
+    | readonly AuthoredMcpSurfaceBindingSet[]
+    | undefined;
   contourReferencesByName: Map<string, Set<string>>;
   crudTableIds: Set<string>;
   composeTargetTrailIds: Set<string>;
@@ -364,6 +384,10 @@ interface MutableProjectContext {
   knownTrailIds: Set<string>;
   topoTrailIds: Set<string>;
   importResolutionsByFile: Map<string, readonly WardenImportResolution[]>;
+  exportedSymbolDefinitionsByName: Map<
+    string,
+    readonly WardenExportedSymbolDefinition[]
+  >;
   documentedImportResolutionsByFile: Map<
     string,
     readonly WardenImportResolution[]
@@ -375,6 +399,7 @@ interface MutableProjectContext {
 }
 
 const createMutableProjectContext = (): MutableProjectContext => ({
+  authoredMcpSurfaceBindingSets: undefined,
   composeTargetTrailIds: new Set<string>(),
   contourReferencesByName: new Map<string, Set<string>>(),
   crudCoverageByEntity: new Map<string, Set<string>>(),
@@ -383,6 +408,7 @@ const createMutableProjectContext = (): MutableProjectContext => ({
     string,
     readonly WardenImportResolution[]
   >(),
+  exportedSymbolDefinitionsByName: new Map(),
   importResolutionsByFile: new Map<string, readonly WardenImportResolution[]>(),
   knownContourIds: new Set<string>(),
   knownResourceIds: new Set<string>(),
@@ -412,6 +438,9 @@ const addContourReferenceTargets = (
 };
 
 const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
+  ...(context.authoredMcpSurfaceBindingSets === undefined
+    ? {}
+    : { authoredMcpSurfaceBindingSets: context.authoredMcpSurfaceBindingSets }),
   ...(context.contourReferencesByName.size > 0
     ? {
         contourReferencesByName: new Map(
@@ -453,6 +482,12 @@ const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
           context.documentedImportResolutionsByFile,
       }
     : {}),
+  ...(context.exportedSymbolDefinitionsByName.size > 0
+    ? {
+        exportedSymbolDefinitionsByName:
+          context.exportedSymbolDefinitionsByName,
+      }
+    : {}),
   ...(context.onTargetSignalIds.size > 0
     ? { onTargetSignalIds: context.onTargetSignalIds }
     : {}),
@@ -849,13 +884,69 @@ const collectFileDocumentedImportResolutions = (
   }
 };
 
+const collectFileExportedSymbolDefinitions = (
+  rootDir: string,
+  sourceFiles: readonly SourceFile[],
+  context: MutableProjectContext
+): void => {
+  const definitionsByName = collectProjectExportedSymbolDefinitions({
+    publicWorkspaces: context.publicWorkspaces,
+    rootDir,
+    sourceFiles,
+  });
+  for (const [name, definitions] of definitionsByName) {
+    context.exportedSymbolDefinitionsByName.set(name, definitions);
+  }
+};
+
+/**
+ * Resolve per-app authored `mcp` surface bindings across the run's topo
+ * targets, so project-aware source rules can compare call-site surface
+ * options against the authored default of the app they belong to.
+ *
+ * Prefers the serialized graph overlays when a target carries a precomputed
+ * graph; otherwise reads the app-module overlay registrations. Invalid
+ * overlays are skipped here — `surface-overlay-coherence` reports them on
+ * the topo-aware path.
+ */
+const collectAuthoredMcpSurfaceBindingSets = (
+  topoTargets: readonly WardenTopoTarget[]
+): readonly AuthoredMcpSurfaceBindingSet[] | undefined => {
+  const sets: AuthoredMcpSurfaceBindingSet[] = [];
+  for (const target of topoTargets) {
+    let bindings: SurfaceBindings | undefined;
+    try {
+      const graphOverlays = target.graph?.overlays;
+      bindings =
+        graphOverlays === undefined
+          ? resolveSurfaceOverlayBindings(target.overlays)?.mcp
+          : surfaceBindingsFromLockOverlays(graphOverlays)?.mcp;
+    } catch {
+      continue;
+    }
+    if (bindings === undefined) {
+      continue;
+    }
+    sets.push({
+      appName: target.name ?? target.topo.name,
+      bindings,
+      trailIds: [...target.topo.trails.keys()],
+    });
+  }
+  return sets.length > 0 ? sets : undefined;
+};
+
 const buildProjectContext = (
   sourceFiles: readonly SourceFile[],
   rootDir: string,
   appTopos: readonly Topo[] = [],
-  scope: WardenScope = EMPTY_WARDEN_SCOPE
+  scope: WardenScope = EMPTY_WARDEN_SCOPE,
+  authoredMcpSurfaceBindingSets:
+    | readonly AuthoredMcpSurfaceBindingSet[]
+    | undefined = undefined
 ): ProjectContext => {
   const context = createMutableProjectContext();
+  context.authoredMcpSurfaceBindingSets = authoredMcpSurfaceBindingSets;
   const typeScriptSourceFiles = sourceFiles.filter(
     (sourceFile) => sourceFile.kind === 'typescript'
   );
@@ -888,6 +979,7 @@ const buildProjectContext = (
     documentationSourceFiles,
     context
   );
+  collectFileExportedSymbolDefinitions(rootDir, typeScriptSourceFiles, context);
 
   return toProjectContext(context);
 };
@@ -1046,6 +1138,7 @@ const topoRuleFailureDiagnostic = (
 const lintTopo = async (
   appTopo: Topo,
   graph: TopoGraph | undefined,
+  overlays: readonly TopoGraphOverlayRegistration[] | undefined,
   extraTopoRules: readonly TopoAwareWardenRule[],
   selector: WardenRuleSelector
 ): Promise<readonly WardenDiagnostic[]> => {
@@ -1056,7 +1149,7 @@ const lintTopo = async (
   ].filter((rule) => isSelectedTopoRule(rule, selector));
   let contextGraph: TopoGraph;
   try {
-    contextGraph = graph ?? deriveTopoGraph(appTopo);
+    contextGraph = graph ?? deriveTopoGraph(appTopo, { overlays });
   } catch (error) {
     for (const rule of rules) {
       diagnostics.push(topoRuleFailureDiagnostic(rule, error));
@@ -1141,6 +1234,7 @@ const lintTopoTargets = async (
     const topoDiagnostics = await lintTopo(
       target.topo,
       target.graph,
+      target.overlays,
       extraTopoRules,
       selector
     );
@@ -1200,7 +1294,8 @@ const lintFiles = async (
     sourceFiles,
     rootDir,
     topoTargets.map((target) => target.topo),
-    scope
+    scope,
+    collectAuthoredMcpSurfaceBindingSets(topoTargets)
   );
   const allDiagnostics: WardenDiagnostic[] = [
     ...lintSourceFiles(sourceFiles, context, extraSourceRules, selector),
@@ -1278,11 +1373,18 @@ const checkDriftForTopoTargets = async (
   topoTargets: readonly WardenTopoTarget[]
 ): Promise<DriftResult> => {
   if (topoTargets.length <= 1) {
-    return checkDrift(rootDir, topoTargets[0]?.topo);
+    const [target] = topoTargets;
+    return checkDrift(
+      rootDir,
+      target?.topo,
+      target === undefined ? undefined : { overlays: target.overlays }
+    );
   }
 
   const driftResults = await Promise.all(
-    topoTargets.map((target) => checkDrift(rootDir, target.topo))
+    topoTargets.map((target) =>
+      checkDrift(rootDir, target.topo, { overlays: target.overlays })
+    )
   );
   const committedHashes = new Set(
     driftResults.map((result) => result.committedHash)
@@ -1316,9 +1418,17 @@ const checkDriftForTopoTargets = async (
   }
 
   const currentHash = aggregateDriftHash(topoTargets, driftResults);
+  const driftedOverlayNamespaces = [
+    ...new Set(
+      driftResults.flatMap((result) => result.driftedOverlayNamespaces ?? [])
+    ),
+  ].toSorted();
   return {
     committedHash,
     currentHash,
+    ...(driftedOverlayNamespaces.length === 0
+      ? {}
+      : { driftedOverlayNamespaces }),
     stale: committedHash !== null && committedHash !== currentHash,
   };
 };
@@ -1638,7 +1748,7 @@ const formatDriftSection = (drift: DriftResult | null): string[] => {
     return [`Drift: blocked (${drift.blockedReason})`, ''];
   }
   const label = drift.stale
-    ? 'Drift: trails.lock is stale (regenerate with `trails compile`)'
+    ? `Drift: ${staleDriftMessage(drift)}`
     : 'Drift: clean';
   return [label, ''];
 };

package/src/command.ts

@@ -12,8 +12,10 @@ import type {
   CliFlagValueAlias,
   CliFlagValueAliasDeclaration,
 } from '@ontrails/cli';
+import { resolveTrailsOverlays } from '@ontrails/adapter-kit';
 import type { Topo } from '@ontrails/core';
 import { AmbiguousError, NotFoundError } from '@ontrails/core';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topographer';
 import {
   loadTrailsConfigValue,
   resolveTrailsProjectRoot,
@@ -682,12 +684,22 @@ const resolveNamedAppModulePath = (
     : resolveFilesystemModulePath(rootDir, matched);
 };
 
-const importTopoFromModulePath = async (modulePath: string): Promise<Topo> => {
+interface LoadedWardenTopoModule {
+  /** App-module overlay registrations read through the shared channel. */
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
+  readonly topo: Topo;
+}
+
+const importTopoFromModulePath = async (
+  modulePath: string
+): Promise<LoadedWardenTopoModule> => {
   const loaded = (await import(pathToFileURL(modulePath).href)) as Record<
     string,
     unknown
   >;
-  return extractTopo(modulePath, loaded);
+  const topo = extractTopo(modulePath, loaded);
+  const overlays = resolveTrailsOverlays(loaded, modulePath);
+  return overlays === undefined ? { topo } : { overlays, topo };
 };
 
 const topoLoadDiagnostic = ({
@@ -759,9 +771,11 @@ export const resolveWardenTopoTargets = async ({
     for (const appName of apps) {
       try {
         const modulePath = resolveNamedAppModulePath(rootDir, appName);
+        const loaded = await importTopoFromModulePath(modulePath);
         topos.push({
           name: appName,
-          topo: await importTopoFromModulePath(modulePath),
+          overlays: loaded.overlays,
+          topo: loaded.topo,
         });
       } catch (error) {
         diagnostics.push(
@@ -778,10 +792,16 @@ export const resolveWardenTopoTargets = async ({
 
   try {
     const modulePath = resolveDiscoveredModulePath(rootDir);
-    const topo = await importTopoFromModulePath(modulePath);
+    const loaded = await importTopoFromModulePath(modulePath);
     return {
       diagnostics,
-      topos: [{ name: topo.name, topo }],
+      topos: [
+        {
+          name: loaded.topo.name,
+          overlays: loaded.overlays,
+          topo: loaded.topo,
+        },
+      ],
     };
   } catch (error) {
     if (error instanceof NotFoundError) {

package/src/drift.ts

@@ -15,14 +15,33 @@ import {
   ValidationError,
 } from '@ontrails/core';
 import {
+  collectTopoGraphOverlays,
   createTopoStore,
   deriveTopoGraph,
   deriveTopoGraphHash,
   isTopoArtifactRegenerationError,
   readLockManifest,
+  readTopoGraph,
   readTrailsLock,
 } from '@ontrails/topographer';
-import type { LockManifest } from '@ontrails/topographer';
+import type {
+  DeriveTopoGraphOptions,
+  LockManifest,
+  TopoGraphOverlays,
+} from '@ontrails/topographer';
+
+/**
+ * Derive options `checkDrift` accepts so the fresh comparison graph carries
+ * the same app-module overlays the committed lock embeds.
+ *
+ * @example
+ * ```ts
+ * import type { CheckDriftOptions } from '@ontrails/warden';
+ *
+ * const options: CheckDriftOptions = { overlays: lease.overlays };
+ * ```
+ */
+export type CheckDriftOptions = Pick<DeriveTopoGraphOptions, 'overlays'>;
 
 /**
  * Result of a drift check comparing committed trails.lock against the current state.
@@ -36,6 +55,12 @@ export interface DriftResult {
   readonly committedHash: string | null;
   /** Hash computed from the current trail topology */
   readonly currentHash: string;
+  /**
+   * Overlay namespaces whose committed facts differ from the freshly derived
+   * facts, sorted lexicographically. Present only when the lock is stale and
+   * the caller supplied a topo plus derive options.
+   */
+  readonly driftedOverlayNamespaces?: readonly string[] | undefined;
 }
 
 interface BlockedLockRead {
@@ -91,14 +116,89 @@ const isBlockedLockRead = (
 ): result is BlockedLockRead =>
   result !== null && 'kind' in result && result.kind === 'blocked-lock-read';
 
+/**
+ * Read the committed lock's embedded graph overlays, tolerating both the v4
+ * root `trails.lock` envelope and the legacy `.trails/` artifact layout.
+ */
+const readCommittedGraphOverlays = async (
+  rootDir: string
+): Promise<TopoGraphOverlays | undefined> => {
+  const committedGraph =
+    (await readTopoGraph({ dir: rootDir })) ??
+    (await readTopoGraph({ dir: deriveTrailsDir({ rootDir }) }));
+  return committedGraph?.overlays;
+};
+
+/**
+ * Name the overlay namespaces whose committed facts drifted from the freshly
+ * derived facts. Compares canonical JSON per namespace across the union of
+ * committed and current namespaces; returns a sorted list.
+ */
+const collectDriftedOverlayNamespaces = async (
+  rootDir: string,
+  topo: Topo,
+  options: CheckDriftOptions
+): Promise<readonly string[]> => {
+  let committed: TopoGraphOverlays | undefined;
+  try {
+    committed = await readCommittedGraphOverlays(rootDir);
+  } catch {
+    return [];
+  }
+  const current = collectTopoGraphOverlays(topo, options.overlays);
+  const namespaces = new Set([
+    ...Object.keys(committed ?? {}),
+    ...Object.keys(current ?? {}),
+  ]);
+  return [...namespaces]
+    .filter(
+      (namespace) =>
+        JSON.stringify(committed?.[namespace]) !==
+        JSON.stringify(current?.[namespace])
+    )
+    .toSorted();
+};
+
+/**
+ * Format a stale drift result into one human-readable sentence.
+ *
+ * Names the drifted overlay namespaces when the drift check identified them,
+ * and always points at `trails compile` as the remediation.
+ *
+ * @example
+ * ```ts
+ * import { staleDriftMessage } from './drift.js';
+ *
+ * staleDriftMessage({
+ *   committedHash: 'aaa',
+ *   currentHash: 'bbb',
+ *   driftedOverlayNamespaces: ['surfaces'],
+ *   stale: true,
+ * });
+ * // => 'trails.lock is stale — drifted overlay namespaces: surfaces (regenerate with `trails compile`)'
+ * ```
+ */
+export const staleDriftMessage = (drift: DriftResult): string => {
+  const namespaces = drift.driftedOverlayNamespaces;
+  const detail =
+    namespaces !== undefined && namespaces.length > 0
+      ? ` — drifted overlay namespaces: ${namespaces.join(', ')}`
+      : '';
+  return `trails.lock is stale${detail} (regenerate with \`trails compile\`)`;
+};
+
 /**
  * Check whether the committed trails.lock is stale compared to the current topology.
  *
  * When no topo is provided, returns a clean result (no drift detectable without runtime info).
+ * When a topo is provided, `options.overlays` carries the app-module overlay
+ * registrations so the fresh comparison graph embeds the same namespaced
+ * facts the compile path writes into the committed lock.
  */
 export const checkDrift = async (
   rootDir: string,
-  topo?: Topo | undefined
+  topo?: Topo | undefined,
+  options?: CheckDriftOptions | undefined
 ): Promise<DriftResult> => {
   try {
     const lockManifest = await readCommittedLockManifest(rootDir);
@@ -127,15 +227,24 @@ export const checkDrift = async (
     const currentHash =
       topo === undefined
         ? (readStoredHash() ?? 'unknown')
-        : deriveTopoGraphHash(deriveTopoGraph(topo));
+        : deriveTopoGraphHash(deriveTopoGraph(topo, options));
+    const stale =
+      topoArtifact !== null &&
+      currentHash !== 'unknown' &&
+      topoArtifact.sha256 !== currentHash;
+    const driftedOverlayNamespaces =
+      stale && topo !== undefined && options !== undefined
+        ? await collectDriftedOverlayNamespaces(rootDir, topo, options)
+        : undefined;
 
     return {
       committedHash: topoArtifact?.sha256 ?? null,
       currentHash,
-      stale:
-        topoArtifact !== null &&
-        currentHash !== 'unknown' &&
-        topoArtifact.sha256 !== currentHash,
+      ...(driftedOverlayNamespaces === undefined ||
+      driftedOverlayNamespaces.length === 0
+        ? {}
+        : { driftedOverlayNamespaces }),
+      stale,
     };
   } catch (error) {
     if (

package/src/fix.ts

@@ -95,16 +95,22 @@ export const applySafeFixesToSource = (
   const applied: WardenDiagnostic[] = [];
   const skipped: WardenDiagnostic[] = [];
   const edits: ResolvedEdit[] = [];
+  const seenEdits = new Set<string>();
 
   for (const diagnostic of diagnostics) {
     if (hasSafeFixEdits(diagnostic)) {
       applied.push(diagnostic);
       for (const edit of diagnostic.fix.edits) {
-        edits.push({
+        const resolvedEdit = {
           end: edit.end,
           replacement: edit.replacement,
           start: edit.start,
-        });
+        };
+        const key = `${String(resolvedEdit.start)}\0${String(resolvedEdit.end)}\0${resolvedEdit.replacement}`;
+        if (!seenEdits.has(key)) {
+          seenEdits.add(key);
+          edits.push(resolvedEdit);
+        }
       }
     } else {
       skipped.push(diagnostic);