@ontrails/warden 1.0.0-beta.41 → 1.0.0-beta.43

package/src/rules/surface-overlay-coherence.ts

@@ -147,7 +147,7 @@ const cliCollisionDiagnostics = (
       routeByName.set(segment, { kind: 'canonical', trailId: entry.id });
     }
     for (const route of entry.cli?.routes ?? []) {
-      // Surface-sourced alias routes are the projections of the overlay
+      // Surface-sourced alias routes are the renderings of the overlay
       // bindings themselves (TRL-1207), so a binding can never "shadow"
       // one — only canonical paths and trail-owned aliases are real
       // entries a binding name could collide with.

package/src/rules/trail-versioning-source.ts

@@ -1070,7 +1070,7 @@ export const markerSchemaUnsupported: WardenRule = {
     return diagnostics;
   },
   description:
-    'Reject versioned trail schema constructs that cannot be projected into stable marker contracts.',
+    'Reject versioned trail schema constructs that cannot be rendered into stable marker contracts.',
   name: MARKER_SCHEMA_UNSUPPORTED,
   severity: 'error',
 };

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

@@ -5,11 +5,11 @@
  * 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.
+ * would otherwise trust grouped entries the running surface does not render.
  *
  * 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
+ * shape — a render-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
@@ -256,7 +256,7 @@ const diagnoseTrailheadMap = (
           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.`
+          `App "${set.appName}"'s surfaceOverlay mcp binding "${name}" is not carried by this call-site trailhead map, so it will not be rendered at runtime while the committed lock still advertises it. Add "${name}" to the call-site map or remove it from the authored overlay.`
         )
       );
     }
@@ -271,7 +271,7 @@ const diagnoseTrailheadMap = (
  */
 export const trailheadOverrideDivergence: ProjectAwareWardenRule = {
   check(): readonly WardenDiagnostic[] {
-    // Without project context there are no authored bindings to compare
+    // Without render context there are no authored bindings to compare
     // against; stay silent instead of guessing.
     return [];
   },

package/src/rules/types.ts

@@ -11,6 +11,7 @@ import type { TopoGraph } from '@ontrails/topography';
 import type { WardenDepth } from '../config.js';
 import type { WardenImportResolution } from '../resolve.js';
 import type { WardenPublicWorkspace } from '../workspaces.js';
+import type { GovernedVocabularyHistoryProvenance } from './retired-vocabulary.js';
 
 /**
  * Severity level for warden diagnostics.
@@ -83,7 +84,7 @@ export interface WardenGuidanceLink {
 }
 
 /**
- * Structured remediation guidance that can be rendered for humans or projected
+ * Structured remediation guidance that can be rendered for humans or rendered
  * into agent-facing manifests without scraping diagnostic prose.
  */
 export interface WardenGuidance {
@@ -143,7 +144,7 @@ export interface WardenFixEdit {
 }
 
 /**
- * Source targets a fix class can inspect when projected into downstream tools.
+ * Source targets a fix class can inspect when rendered into downstream tools.
  *
  * Warden itself decides which committed files it scans. This metadata is for
  * consumers such as Regrade that need to derive a narrower collection before
@@ -179,7 +180,7 @@ export interface WardenFix {
 }
 
 /**
- * Per-rule fix capability, projected into the guide/manifest.
+ * Per-rule fix capability, rendered into the guide/manifest.
  *
  * Declares that a rule can emit {@link WardenFix} metadata and the default
  * safety for its fixes, so `warden --help`, the guide, and agent surfaces can
@@ -191,7 +192,7 @@ export interface WardenFixCapability {
   readonly class: WardenFixClass;
   /** Default safety for fixes this rule emits. */
   readonly safety: WardenFixSafety;
-  /** Downstream scan targets for tools that project this fix capability. */
+  /** Downstream scan targets for tools that render this fix capability. */
   readonly scanTargets?: WardenFixScanTargets | undefined;
 }
 
@@ -213,7 +214,7 @@ export interface WardenRuleMetadata {
   readonly tier: WardenRuleTier;
   /** Structured remediation guidance for diagnostics emitted by this rule. */
   readonly guidance?: WardenGuidance | undefined;
-  /** Declares that this rule can emit fix metadata, for guide projection. */
+  /** Declares that this rule can emit fix metadata, for guide rendering. */
   readonly fix?: WardenFixCapability | undefined;
 }
 
@@ -280,6 +281,10 @@ export interface WardenRule {
   readonly description: string;
   /** Optional inline classification. Built-ins are classified by registry. */
   readonly metadata?: WardenRuleMetadata | undefined;
+  /** Source file kinds this rule explicitly supports beyond TypeScript. */
+  readonly sourceKinds?:
+    | readonly ('documentation' | 'text' | 'typescript')[]
+    | undefined;
   /** Run the rule against source code and return any diagnostics */
   readonly check: (
     sourceCode: string,
@@ -304,6 +309,16 @@ export interface AuthoredMcpSurfaceBindingSet {
  * Options for compose-file rules that need knowledge of all trail IDs in a project.
  */
 export interface ProjectContext {
+  /** Whether this project owns the governed transition registry and must prove completed migrations. */
+  readonly governedVocabularyHistoryRequired?: boolean | undefined;
+  /** Validated committed Regrade history evidence keyed by governed transition. */
+  readonly governedVocabularyHistoryByTransitionId?:
+    | ReadonlyMap<string, GovernedVocabularyHistoryEvidence>
+    | undefined;
+  /** Invalid committed history artifacts observed while building context. */
+  readonly governedVocabularyHistoryIssues?:
+    | readonly GovernedVocabularyHistoryIssue[]
+    | undefined;
   /**
    * Per-app authored `mcp` surface bindings, resolved from the project's
    * topo targets (the serialized graph overlays when available, else the
@@ -368,10 +383,41 @@ export interface ProjectContext {
   readonly crudCoverageByEntity?: ReadonlyMap<string, ReadonlySet<string>>;
 }
 
+export interface GovernedVocabularyHistoryEvidence {
+  readonly caseSensitive: boolean;
+  readonly id: string;
+  readonly latestFormObservations: readonly GovernedVocabularyHistoryFormObservation[];
+  readonly path: string;
+  readonly provenance?: GovernedVocabularyHistoryProvenance;
+  readonly runCount: number;
+  readonly transitionId: string;
+}
+
+/** One vocabulary-form observation preserved in committed Regrade history. */
+export interface GovernedVocabularyHistoryFormObservation {
+  readonly disposition: string;
+  readonly form: string;
+  readonly line: number;
+  readonly path: string;
+  readonly reason: string;
+  readonly scopeTier?: 'in-scope' | 'policy-classified' | undefined;
+  readonly verdict: 'applied' | 'deferred' | 'modified' | 'skipped';
+}
+
+export interface GovernedVocabularyHistoryIssue {
+  readonly message: string;
+  readonly path: string;
+  readonly transitionId?: string;
+}
+
 /**
  * A project-aware rule that requires knowledge of all trail IDs.
  */
 export interface ProjectAwareWardenRule extends WardenRule {
+  /** Run project-wide validation once, independently of any source file. */
+  readonly checkProject?: (
+    context: ProjectContext
+  ) => readonly WardenDiagnostic[];
   /** Run the rule with project-level context */
   readonly checkWithContext: (
     sourceCode: string,

package/src/trails/governed-vocabulary-permutation-watch.trail.ts

@@ -0,0 +1,16 @@
+import { governedVocabularyPermutationWatch } from '../rules/governed-vocabulary-permutation-watch.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const governedVocabularyPermutationWatchTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/example/src/trails/play.ts',
+        sourceCode: 'const entityId = "track";\n',
+      },
+      name: 'Project history watch runs at the project boundary',
+    },
+  ],
+  rule: governedVocabularyPermutationWatch,
+});

package/src/trails/index.ts

@@ -17,12 +17,13 @@ export { exampleValidTrail } from './example-valid.trail.js';
 export { firesDeclarationsTrail } from './fires-declarations.trail.js';
 export { forkWithoutPreservedImplementationTrail } from './fork-without-preserved-implementation.trail.js';
 export { governedSymbolResidueTrail } from './governed-symbol-residue.trail.js';
+export { governedVocabularyPermutationWatchTrail } from './governed-vocabulary-permutation-watch.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';
 export { intentPropagationTrail } from './intent-propagation.trail.js';
 export { layerFieldNameDriftTrail } from './layer-field-name-drift.trail.js';
-export { libraryProjectionCoherenceTrail } from './library-projection-coherence.trail.js';
+export { libraryRenderCoherenceTrail } from './library-render-coherence.trail.js';
 export { markerSchemaUnsupportedTrail } from './marker-schema-unsupported.trail.js';
 export { missingVisibilityTrail } from './missing-visibility.trail.js';
 export { missingReconcileTrail } from './missing-reconcile.trail.js';
@@ -40,7 +41,7 @@ export { noThrowInDetourRecoverTrail } from './no-throw-in-detour-recover.trail.
 export { noThrowInImplementationTrail } from './no-throw-in-implementation.trail.js';
 export { noTopLevelSurfaceTrail } from './no-top-level-surface.trail.js';
 export { orphanedSignalTrail } from './orphaned-signal.trail.js';
-export { ownerProjectionParityTrail } from './owner-projection-parity.trail.js';
+export { ownerRenderParityTrail } from './owner-render-parity.trail.js';
 export { pendingForceTrail } from './pending-force.trail.js';
 export { permitGovernanceTrail } from './permit-governance.trail.js';
 export { preferSchemaInferenceTrail } from './prefer-schema-inference.trail.js';

package/src/trails/layer-field-name-drift.trail.ts

@@ -21,7 +21,7 @@ const collides = LAYER_FIELD_RESERVED_NAMES.has('all');
             filePath: 'packages/cli/src/build.ts',
             line: 1,
             message:
-              'layer-field-name-drift: surface-local reserved name set "META_FLAG_CANDIDATES" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.',
+              'layer-field-name-drift: surface-local reserved name set "META_FLAG_CANDIDATES" can make layer input fields render differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.',
             rule: 'layer-field-name-drift',
             severity: 'error',
           },

package/src/trails/{library-projection-coherence.trail.ts → library-render-coherence.trail.ts}

@@ -1,7 +1,7 @@
 import { Result, topo, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { libraryProjectionCoherence } from '../rules/library-projection-coherence.js';
+import { libraryRenderCoherence } from '../rules/library-render-coherence.js';
 import { wrapTopoRule } from './wrap-rule.js';
 
 const output = z.object({ ok: z.boolean() });
@@ -18,7 +18,7 @@ const kebab = trail('widget-ping', {
   output,
 });
 
-export const libraryProjectionCoherenceTrail = wrapTopoRule({
+export const libraryRenderCoherenceTrail = wrapTopoRule({
   examples: [
     {
       expected: {
@@ -27,17 +27,17 @@ export const libraryProjectionCoherenceTrail = wrapTopoRule({
             filePath: '<topo>',
             line: 1,
             message:
-              'Library projection export collision on "widgetPing": trails "widget-ping", "widget.ping" derive the same package export. Rename one trail or add a library export override before materializing the generated package.',
-            rule: 'library-projection-coherence',
+              'Library rendering export collision on "widgetPing": trails "widget-ping", "widget.ping" derive the same package export. Rename one trail or add a library export override before materializing the generated package.',
+            rule: 'library-render-coherence',
             severity: 'error',
           },
         ],
       },
       input: {
-        topo: topo('library-projection-coherence', { dotted, kebab }),
+        topo: topo('library-render-coherence', { dotted, kebab }),
       },
       name: 'Library export collision',
     },
   ],
-  rule: libraryProjectionCoherence,
+  rule: libraryRenderCoherence,
 });

package/src/trails/{owner-projection-parity.trail.ts → owner-render-parity.trail.ts}

@@ -1,9 +1,9 @@
 import { fileURLToPath } from 'node:url';
 
-import { ownerProjectionParity } from '../rules/owner-projection-parity.js';
+import { ownerRenderParity } from '../rules/owner-render-parity.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const ownerProjectionParityTrail = wrapRule({
+export const ownerRenderParityTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
@@ -19,8 +19,8 @@ export const httpMethodByIntent = {
   write: 'POST',
 } as const satisfies Record<Intent, 'GET' | 'POST' | 'DELETE'>;`,
       },
-      name: 'HTTP method projection covers core intent values',
+      name: 'HTTP method rendering covers core intent values',
     },
   ],
-  rule: ownerProjectionParity,
+  rule: ownerRenderParity,
 });

package/src/trails/public-output-schema.trail.ts

@@ -39,7 +39,7 @@ export const publicOutputSchemaTrail = wrapTopoRule({
             filePath: '<topo>',
             line: 1,
             message:
-              'Trail "report.missing" is visible to public MCP/HTTP surface projection but does not declare an output schema. Add an explicit output schema, or mark the trail visibility as internal if it is composition-only.',
+              'Trail "report.missing" is visible to public MCP/HTTP surface rendering but does not declare an output schema. Add an explicit output schema, or mark the trail visibility as internal if it is composition-only.',
             rule: 'public-output-schema',
             severity: 'error',
           },

package/src/trails/run.ts

@@ -9,12 +9,20 @@
 import type { Intent, Topo } from '@ontrails/core';
 import { run } from '@ontrails/core';
 
-import { wardenTopoRules } from '../rules/index.js';
-import type { WardenDiagnostic } from '../rules/types.js';
+import { wardenRules, wardenTopoRules } from '../rules/index.js';
+import type {
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryIssue,
+  ProjectAwareWardenRule,
+  WardenDiagnostic,
+  WardenRule,
+} from '../rules/types.js';
 import type { WardenImportResolution } from '../resolve.js';
 import type { WardenPublicWorkspace } from '../workspaces.js';
+import { projectAwareRuleInput } from './schema.js';
 import type { RuleOutput } from './schema.js';
 import { wardenTopo } from './topo.js';
+import { buildProjectContext } from './wrap-rule.js';
 
 /**
  * Run all file-scoped warden rule trails for a given file and collect diagnostics.
@@ -34,6 +42,9 @@ const appendDiagnostics = (
 type TrailIntentMap = Readonly<Record<string, Intent>>;
 
 interface ProjectRuleOptions {
+  readonly governedVocabularyHistories?: readonly GovernedVocabularyHistoryEvidence[];
+  readonly governedVocabularyHistoryIssues?: readonly GovernedVocabularyHistoryIssue[];
+  readonly governedVocabularyHistoryRequired?: boolean;
   readonly entityReferencesByName?: Readonly<Record<string, readonly string[]>>;
   readonly composeTargetTrailIds?: readonly string[];
   readonly crudTableIds?: readonly string[];
@@ -55,6 +66,9 @@ interface ProjectRuleOptions {
 }
 
 const PROJECT_OPTION_KEYS = [
+  'governedVocabularyHistories',
+  'governedVocabularyHistoryIssues',
+  'governedVocabularyHistoryRequired',
   'entityReferencesByName',
   'composeTargetTrailIds',
   'crudTableIds',
@@ -135,6 +149,34 @@ export const runWardenTrails = async (
   return allDiagnostics;
 };
 
+const isProjectAwareRule = (rule: WardenRule): rule is ProjectAwareWardenRule =>
+  'checkWithContext' in rule;
+
+/**
+ * Run project-wide built-in Warden diagnostics once for one project context.
+ *
+ * @example
+ * ```ts
+ * const diagnostics = runProjectWardenRules({
+ *   governedVocabularyHistories: histories,
+ * });
+ * ```
+ */
+export const runProjectWardenRules = (
+  options?: ProjectRuleOptions
+): readonly WardenDiagnostic[] => {
+  const context = buildProjectContext(
+    projectAwareRuleInput.parse(buildRuleInput('<project>', '', options))
+  );
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const rule of wardenRules.values()) {
+    if (isProjectAwareRule(rule) && rule.checkProject !== undefined) {
+      appendDiagnostics(diagnostics, rule.checkProject(context));
+    }
+  }
+  return diagnostics;
+};
+
 /**
  * Run the built-in topo-aware warden rule trails once against a resolved topo.
  *

package/src/trails/schema.ts

@@ -119,6 +119,27 @@ export const authoredMcpSurfaceBindingSetSchema = z.object({
     .describe('Trail ids registered in the owning app topo'),
 });
 
+const governedVocabularyHistoryObservationSchema = z.object({
+  disposition: z.string(),
+  form: z.string(),
+  line: z.number().int().positive(),
+  path: z.string(),
+  reason: z.string(),
+  scopeTier: z.enum(['in-scope', 'policy-classified']).optional(),
+  verdict: z.enum(['applied', 'deferred', 'modified', 'skipped']),
+});
+
+const governedVocabularyHistoryEvidenceSchema = z.object({
+  caseSensitive: z.boolean(),
+  id: z.string(),
+  latestFormObservations: z
+    .array(governedVocabularyHistoryObservationSchema)
+    .readonly(),
+  path: z.string(),
+  runCount: z.number().int().nonnegative(),
+  transitionId: z.string(),
+});
+
 export const projectAwareRuleInput = ruleInput.extend({
   authoredMcpSurfaceBindingSets: z
     .array(authoredMcpSurfaceBindingSetSchema)
@@ -153,6 +174,26 @@ export const projectAwareRuleInput = ruleInput.extend({
     .record(z.string(), z.array(exportedSymbolDefinitionSchema))
     .optional()
     .describe('Public exported symbol definitions grouped by exported name'),
+  governedVocabularyHistories: z
+    .array(governedVocabularyHistoryEvidenceSchema)
+    .readonly()
+    .optional()
+    .describe('Validated committed Regrade histories by governed transition'),
+  governedVocabularyHistoryIssues: z
+    .array(
+      z.object({
+        message: z.string(),
+        path: z.string(),
+        transitionId: z.string().optional(),
+      })
+    )
+    .readonly()
+    .optional()
+    .describe('Invalid committed Regrade history artifacts'),
+  governedVocabularyHistoryRequired: z
+    .boolean()
+    .optional()
+    .describe('Whether the project must prove completed governed migrations'),
   importResolutionsByFile: z
     .record(z.string(), z.array(importResolutionSchema))
     .optional()

package/src/trails/wrap-rule.ts

@@ -50,7 +50,47 @@ const buildRuleMeta = (rule: WardenRule | TopoAwareWardenRule) => {
   };
 };
 
-const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
+const buildGovernedHistoryContext = (
+  input: ProjectAwareRuleInput
+): Pick<
+  ProjectContext,
+  | 'governedVocabularyHistoryByTransitionId'
+  | 'governedVocabularyHistoryIssues'
+  | 'governedVocabularyHistoryRequired'
+> => ({
+  ...(input.governedVocabularyHistories
+    ? {
+        governedVocabularyHistoryByTransitionId: new Map(
+          input.governedVocabularyHistories.map((history) => [
+            history.transitionId,
+            history,
+          ])
+        ),
+      }
+    : {}),
+  ...(input.governedVocabularyHistoryIssues
+    ? {
+        governedVocabularyHistoryIssues:
+          input.governedVocabularyHistoryIssues.map((issue) => ({
+            message: issue.message,
+            path: issue.path,
+            ...(issue.transitionId === undefined
+              ? {}
+              : { transitionId: issue.transitionId }),
+          })),
+      }
+    : {}),
+  ...(input.governedVocabularyHistoryRequired === undefined
+    ? {}
+    : {
+        governedVocabularyHistoryRequired:
+          input.governedVocabularyHistoryRequired,
+      }),
+});
+
+export const buildProjectContext = (
+  input: ProjectAwareRuleInput
+): ProjectContext => ({
   ...(input.authoredMcpSurfaceBindingSets
     ? { authoredMcpSurfaceBindingSets: input.authoredMcpSurfaceBindingSets }
     : {}),
@@ -98,6 +138,7 @@ const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
         ),
       }
     : {}),
+  ...buildGovernedHistoryContext(input),
   ...(input.publicWorkspaces
     ? { publicWorkspaces: new Map(Object.entries(input.publicWorkspaces)) }
     : {}),
@@ -151,10 +192,11 @@ export function wrapRule(
         RuleOutput
       >['examples'],
       implementation: (input: ProjectAwareRuleInput) => {
+        const context = buildProjectContext(input);
         const diagnostics = projectAwareRule.checkWithContext(
           input.sourceCode,
           input.filePath,
-          buildProjectContext(input)
+          context
         );
         return Result.ok({ diagnostics: [...diagnostics] });
       },