@ontrails/warden 1.0.0-beta.42 → 1.0.0-beta.45

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

@@ -1,12 +1,9 @@
 import { deriveTopoGraph } from '@ontrails/topography';
-import type {
-  TopoGraph,
-  TopoGraphLibraryProjection,
-} from '@ontrails/topography';
+import type { TopoGraph, TopoGraphLibraryDerived } from '@ontrails/topography';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
 
-const RULE_NAME = 'library-projection-coherence';
+const RULE_NAME = 'library-render-coherence';
 const TOPO_FILE = '<topo>';
 
 const resolveGraph = (
@@ -26,7 +23,7 @@ const collisionDiagnostic = (
 ): 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.`,
+  message: `Library rendering 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',
 });
@@ -37,7 +34,7 @@ const missingTargetDiagnostic = (
 ): 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.`,
+  message: `Library rendering export "${exportName}" targets unknown trail "${trailId}". Resolved library exports must stay attached to existing trail contracts.`,
   rule: RULE_NAME,
   severity: 'error',
 });
@@ -48,16 +45,16 @@ const duplicateExportDiagnostic = (
 ): 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.`,
+  message: `Library rendering contains duplicate export "${exportName}" for trails ${renderTrailIds(trailIds)}. The resolved rendering should record the collision and keep only one emitted export.`,
   rule: RULE_NAME,
   severity: 'error',
 });
 
 const collectDuplicateExportDiagnostics = (
-  projection: TopoGraphLibraryProjection
+  rendering: TopoGraphLibraryDerived
 ): readonly WardenDiagnostic[] => {
   const trailIdsByExport = new Map<string, string[]>();
-  for (const entry of projection.exports) {
+  for (const entry of rendering.exports) {
     const trailIds = trailIdsByExport.get(entry.exportName) ?? [];
     trailIds.push(entry.trailId);
     trailIdsByExport.set(entry.exportName, trailIds);
@@ -70,14 +67,14 @@ const collectDuplicateExportDiagnostics = (
 };
 
 const collectMissingTargetDiagnostics = (
-  projection: TopoGraphLibraryProjection,
+  rendering: TopoGraphLibraryDerived,
   knownTrailIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] =>
-  projection.exports
+  rendering.exports
     .filter((entry) => !knownTrailIds.has(entry.trailId))
     .map((entry) => missingTargetDiagnostic(entry.exportName, entry.trailId));
 
-export const libraryProjectionCoherence: TopoAwareWardenRule = {
+export const libraryRenderCoherence: TopoAwareWardenRule = {
   checkTopo(topo, context) {
     const graph = resolveGraph(topo, context?.graph);
     if (!graph.library) {
@@ -94,7 +91,7 @@ export const libraryProjectionCoherence: TopoAwareWardenRule = {
     ];
   },
   description:
-    'Ensure resolved library projection exports are collision-free and target existing trails.',
+    'Ensure resolved library rendering exports are collision-free and target existing trails.',
   name: RULE_NAME,
   severity: 'error',
 };

package/src/rules/metadata.ts

@@ -84,9 +84,10 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'fires-declarations': 'signals',
   'fork-without-preserved-implementation': 'lifecycle',
   'governed-symbol-residue': 'lifecycle',
+  'governed-vocabulary-permutation-watch': 'lifecycle',
   'implementation-returns-result': 'results',
   'intent-propagation': 'composition',
-  'library-projection-coherence': 'meta',
+  'library-render-coherence': 'meta',
   'marker-schema-unsupported': 'lifecycle',
   'missing-reconcile': 'resources',
   'missing-visibility': 'composition',
@@ -316,10 +317,46 @@ const builtinWardenRuleMetadataInput = {
   'governed-symbol-residue': {
     ...durableExternal,
     fix: { class: 'term-rewrite', safety: 'safe' },
+    guidance: {
+      docs: [
+        {
+          label: 'Vocabulary transition workflow',
+          path: 'docs/releases/v1-vocabulary-transition-workflow.md',
+        },
+      ],
+      steps: [
+        'Run the governed transition through Regrade so committed history proves the primary migration.',
+        'Use manual edits only for review or cleanup after Regrade exhausts the safe slice.',
+        'Keep the transition registry and committed history evidence aligned.',
+      ],
+      summary:
+        'Require committed Regrade evidence before completing a governed vocabulary migration.',
+    },
     invariant:
-      'Active governed vocabulary symbol renames do not leave retired identifiers in source.',
+      'Governed vocabulary transitions carry committed Regrade provenance and do not leave or reintroduce retired identifiers.',
     tier: 'source-static',
   },
+  'governed-vocabulary-permutation-watch': {
+    guidance: {
+      docs: [
+        {
+          label: 'Vocabulary transition workflow',
+          path: 'docs/releases/v1-vocabulary-transition-workflow.md',
+        },
+      ],
+      steps: [
+        'Add the unknown form to the governed vocabulary plan and run an incremental Regrade plan.',
+        'If the form is intentionally unrelated or preserved, classify it so later history suppresses the advisory.',
+      ],
+      summary:
+        'Classify unknown governed-stem permutations recorded by committed Regrade history.',
+    },
+    invariant:
+      'Committed Regrade history keeps unknown governed-stem permutations visible until they are classified.',
+    lifecycle: { state: 'durable' },
+    scope: 'advisory',
+    tier: 'project-static',
+  },
   'implementation-returns-result': {
     ...durableExternal,
     invariant: 'Implementations return Result values.',
@@ -343,10 +380,10 @@ const builtinWardenRuleMetadataInput = {
   'layer-field-name-drift': {
     ...durableExternal,
     invariant:
-      'Layer input field reserved names are shared across surface projections.',
+      'Layer input field reserved names are shared across surface renderings.',
     tier: 'source-static',
   },
-  'library-projection-coherence': {
+  'library-render-coherence': {
     ...durableExternal,
     guidance: {
       docs: [
@@ -361,20 +398,20 @@ const builtinWardenRuleMetadataInput = {
       ],
       steps: [
         'Rename one source trail or add an explicit library export override before generating a package.',
-        'Keep serialized library projection exports attached to existing trail IDs.',
-        'Run the generated-package smoke after repairing projection drift.',
+        'Keep serialized derived library exports attached to existing trail IDs.',
+        'Run the generated-package smoke after repairing rendering drift.',
       ],
       summary:
-        'Keep resolved library projection exports collision-free and attached to one trail contract.',
+        'Keep resolved derived library exports collision-free and attached to one trail contract.',
     },
     invariant:
-      'Resolved library projection exports are collision-free and target existing trails.',
+      'Resolved derived library exports are collision-free and target existing trails.',
     tier: 'topo-aware',
   },
   'marker-schema-unsupported': {
     ...durableExternal,
     invariant:
-      'Versioned schemas stay inside the supported marker projection subset.',
+      'Versioned schemas stay inside the supported marker derivation subset.',
     tier: 'source-static',
   },
   'missing-reconcile': {
@@ -503,8 +540,8 @@ const builtinWardenRuleMetadataInput = {
       'Derived store signals are consumed by matching trail on: consumers.',
     tier: 'project-static',
   },
-  'owner-projection-parity': {
-    invariant: 'Framework projections stay aligned with owner exports.',
+  'owner-render-parity': {
+    invariant: 'Framework renderings stay aligned with owner exports.',
     lifecycle: { state: 'durable' },
     scope: 'internal',
     tier: 'source-static',
@@ -565,11 +602,11 @@ const builtinWardenRuleMetadataInput = {
       docs: [trailContractDocs, wardenDocs],
       relatedRules: ['public-union-output-discriminants'],
       steps: [
-        'Add an explicit output schema to public trails that can be projected onto MCP or HTTP surfaces.',
+        'Add an explicit output schema to public trails that can be rendered onto MCP or HTTP surfaces.',
         'If the trail is composition-only, mark it visibility: "internal" instead of exposing it by default.',
       ],
       summary:
-        'Make public surface result contracts explicit before MCP/HTTP projection.',
+        'Make public surface result contracts explicit before MCP/HTTP rendering.',
     },
     invariant: 'Public MCP/HTTP surface trails declare output schemas.',
     tier: 'topo-aware',
@@ -709,7 +746,7 @@ const builtinWardenRuleMetadataInput = {
         'Record explicit visibility-widening acceptance and stable-description metadata when a trailhead intentionally widens visibility.',
       ],
       summary:
-        'Keep trailhead maps reviewable before they reach MCP projection.',
+        'Keep trailhead maps reviewable before they reach MCP rendering.',
     },
     invariant:
       'Trailhead maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',

package/src/rules/no-redundant-result-error-wrap.ts

@@ -23,11 +23,11 @@ import {
 import type { AstNode, AstParentContext } from '@ontrails/source';
 import {
   collectAllResultHelperNames,
+  collectDirectResultAssignments,
   collectNamespaceHelperImports,
   collectResultTypeNames,
   findNearestBindingScope,
-  isHelperCall,
-  isResultExpression,
+  isResultProducingExpression,
   trackScopedResultHelperDeclaration,
 } from './implementation-returns-result.js';
 import { isTestFile } from './scan.js';
@@ -82,16 +82,6 @@ const getErrorSourceVariable = (node: AstNode | null): string | null => {
   return identifierName(member?.object);
 };
 
-const isResultProducingExpression = (
-  node: AstNode,
-  helperNames: ReadonlySet<string>,
-  namespaceHelpers: NamespaceHelperMap,
-  scopes: readonly ReadonlySet<string>[],
-  scopedHelpers: ScopedHelperMap
-): boolean =>
-  isResultExpression(node) ||
-  isHelperCall(node, helperNames, namespaceHelpers, scopes, scopedHelpers);
-
 type ResultProvenance = Map<ReadonlySet<string>, Set<string>>;
 
 const markResultVariable = (
@@ -158,6 +148,7 @@ const trackVariableDeclarator = (
     isResultProducingExpression(
       init,
       helperNames,
+      provenance,
       namespaceHelpers,
       scopes,
       scopedHelpers
@@ -175,11 +166,10 @@ const trackAssignmentExpression = (
   helperNames: ReadonlySet<string>,
   namespaceHelpers: NamespaceHelperMap,
   scopedHelpers: ScopedHelperMap,
+  directAssignments: ReadonlySet<AstNode>,
   scopes: readonly ReadonlySet<string>[]
 ): void => {
   const left = getNodeLeft(node);
-  const operator = getNodeOperator(node);
-  const right = getNodeRight(node);
   const name = identifierName(left);
   if (!name) {
     return;
@@ -188,16 +178,22 @@ const trackAssignmentExpression = (
   if (!scope) {
     return;
   }
-  if (
-    operator === '=' &&
+  const right = getNodeRight(node);
+  const resultRhs =
+    getNodeOperator(node) === '=' &&
     right &&
     isResultProducingExpression(
       right,
       helperNames,
+      provenance,
       namespaceHelpers,
       scopes,
       scopedHelpers
-    )
+    );
+  if (
+    resultRhs &&
+    (hasResultProvenance(provenance, scope, name) ||
+      directAssignments.has(node))
   ) {
     markResultVariable(provenance, scope, name);
     return;
@@ -258,6 +254,7 @@ const checkFunctionBody = (
   const scopedHelpers: MutableScopedHelperMap = new Map();
   const implScope = collectScopeFrameBindings(owner);
   const initialScopes = implScope.size > 0 ? [implScope] : [];
+  const directAssignments = collectDirectResultAssignments(body);
 
   walkWithScopes(
     body,
@@ -287,6 +284,7 @@ const checkFunctionBody = (
           helperNames,
           namespaceHelpers,
           scopedHelpers,
+          directAssignments,
           scopes
         );
         return;

package/src/rules/no-retired-cross-vocabulary.ts

@@ -39,7 +39,6 @@ const ALLOWED_PATH_SUFFIXES: readonly string[] = [
   '/packages/warden/src/rules/retired-vocabulary.ts',
   '/packages/warden/src/trails/governed-symbol-residue.trail.ts',
   '/packages/warden/src/trails/no-retired-cross-vocabulary.trail.ts',
-  '/scripts/vocab-cutover-rewrite.ts',
 ];
 
 interface SafeRewriteMatch {

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

@@ -18,14 +18,14 @@ import {
 import type { AstNode } from '@ontrails/source';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
-const RULE_NAME = 'owner-projection-parity';
+const RULE_NAME = 'owner-render-parity';
 
-const HTTP_METHOD_PROJECTION_PATH = resolve(
+const HTTP_METHOD_DERIVATION_PATH = resolve(
   fileURLToPath(new URL('../../../http/src/method.ts', import.meta.url))
 );
 
 const isTargetFile = (filePath: string): boolean =>
-  resolve(filePath) === HTTP_METHOD_PROJECTION_PATH;
+  resolve(filePath) === HTTP_METHOD_DERIVATION_PATH;
 
 const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
   let current = node;
@@ -44,13 +44,13 @@ const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
   return current;
 };
 
-interface ProjectionMap {
+interface IntentKeyMap {
   readonly keys: ReadonlySet<string>;
   readonly node: AstNode;
 }
 
-const findHttpMethodByIntentMap = (ast: AstNode): ProjectionMap | null => {
-  let found: ProjectionMap | null = null;
+const findHttpMethodByIntentMap = (ast: AstNode): IntentKeyMap | null => {
+  let found: IntentKeyMap | null = null;
 
   walk(ast, (node) => {
     if (found || node.type !== 'VariableDeclarator') {
@@ -89,16 +89,16 @@ const findHttpMethodByIntentMap = (ast: AstNode): ProjectionMap | null => {
 const buildMessage = (missing: string[], extra: string[]): string => {
   const details = [
     missing.length > 0 ? `missing owner intents: ${missing.join(', ')}` : '',
-    extra.length > 0 ? `unknown projection keys: ${extra.join(', ')}` : '',
+    extra.length > 0 ? `unknown intentKeyMap keys: ${extra.join(', ')}` : '',
   ].filter(Boolean);
 
   return [
-    'owner-projection-parity: httpMethodByIntent must cover the core intentValues owner vocabulary.',
+    'owner-render-parity: httpMethodByIntent must cover the core intentValues owner vocabulary.',
     ...details,
   ].join(' ');
 };
 
-export const ownerProjectionParity: WardenRule = {
+export const ownerRenderParity: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     if (!isTargetFile(filePath)) {
       return [];
@@ -109,35 +109,35 @@ export const ownerProjectionParity: WardenRule = {
       return [];
     }
 
-    const projection = findHttpMethodByIntentMap(ast);
+    const intentKeyMap = findHttpMethodByIntentMap(ast);
     const ownerKeys = new Set<string>(intentValues);
-    const projectionKeys = projection?.keys ?? new Set<string>();
+    const derivedKeys = intentKeyMap?.keys ?? new Set<string>();
     const missing = [...ownerKeys]
-      .filter((key) => !projectionKeys.has(key))
+      .filter((key) => !derivedKeys.has(key))
       .toSorted();
-    const extra = [...projectionKeys]
+    const extra = [...derivedKeys]
       .filter((key) => !ownerKeys.has(key))
       .toSorted();
 
-    if (projection && missing.length === 0 && extra.length === 0) {
+    if (intentKeyMap && missing.length === 0 && extra.length === 0) {
       return [];
     }
 
-    const node = projection?.node ?? ast;
+    const node = intentKeyMap?.node ?? ast;
     return [
       {
         filePath,
         line: offsetToLine(sourceCode, node.start),
-        message: projection
+        message: intentKeyMap
           ? buildMessage(missing, extra)
-          : 'owner-projection-parity: expected httpMethodByIntent to project core intentValues.',
+          : 'owner-render-parity: expected httpMethodByIntent to render core intentValues.',
         rule: RULE_NAME,
         severity: 'error',
       },
     ];
   },
   description:
-    'Require owner-derived projection maps to cover their authoritative owner vocabulary.',
+    'Require owner-derived intentKeyMap maps to cover their authoritative owner vocabulary.',
   name: RULE_NAME,
   severity: 'error',
 };

package/src/rules/public-internal-deep-imports.ts

@@ -20,9 +20,7 @@ import type { WardenPublicWorkspace } from '../workspaces.js';
 
 const RULE_NAME = 'public-internal-deep-imports';
 const ONTRAILS_SPECIFIER_PATTERN = /^(@ontrails\/[^/]+)(?:\/(.+))?$/;
-const ROOT_BARREL_INTERNAL_RE_EXPORT_ALLOWLIST = new Set([
-  '@ontrails/tracing:./internal/dev-state.js',
-]);
+const ROOT_BARREL_INTERNAL_RE_EXPORT_ALLOWLIST = new Set<string>();
 
 interface ReExportSite {
   readonly importSource: string;

package/src/rules/public-output-schema.ts

@@ -10,7 +10,7 @@ const diagnosticForTrail = (trail: AnyTrail): WardenDiagnostic => ({
   filePath: TOPO_FILE,
   line: 1,
   message:
-    `Trail "${trail.id}" is visible to public MCP/HTTP surface projection but does not declare an output schema. ` +
+    `Trail "${trail.id}" 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: RULE_NAME,
   severity: 'error',

package/src/rules/registry-names.ts

@@ -23,12 +23,13 @@ import { errorMappingCompleteness } from './error-mapping-completeness.js';
 import { exampleValid } from './example-valid.js';
 import { firesDeclarations } from './fires-declarations.js';
 import { governedSymbolResidue } from './governed-symbol-residue.js';
+import { governedVocabularyPermutationWatch } from './governed-vocabulary-permutation-watch.js';
 import { implementationReturnsResult } from './implementation-returns-result.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 { libraryRenderCoherence } from './library-render-coherence.js';
 import { missingReconcile } from './missing-reconcile.js';
 import { missingVisibility } from './missing-visibility.js';
 import { noDevPermitInSource } from './no-dev-permit-in-source.js';
@@ -45,7 +46,7 @@ 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 { ownerRenderParity } from './owner-render-parity.js';
 import { permitGovernance } from './permit-governance.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
 import { publicExportExampleCoverage } from './public-export-example-coverage.js';
@@ -109,13 +110,14 @@ export const registeredRuleNames: readonly string[] = [
   exampleValid.name,
   firesDeclarations.name,
   governedSymbolResidue.name,
+  governedVocabularyPermutationWatch.name,
   forkWithoutPreservedImplementation.name,
   implementationReturnsResult.name,
   incompleteAccessorForStandardOp.name,
   incompleteCrud.name,
   intentPropagation.name,
   layerFieldNameDrift.name,
-  libraryProjectionCoherence.name,
+  libraryRenderCoherence.name,
   markerSchemaUnsupported.name,
   missingReconcile.name,
   missingVisibility.name,
@@ -133,7 +135,7 @@ export const registeredRuleNames: readonly string[] = [
   noTopLevelSurface.name,
   onReferencesExist.name,
   orphanedSignal.name,
-  ownerProjectionParity.name,
+  ownerRenderParity.name,
   pendingForce.name,
   permitGovernance.name,
   preferSchemaInference.name,