@webpieces/nx-webpieces-rules 0.4.854 → 0.4.856

package/executors.json

@@ -109,6 +109,11 @@
             "implementation": "./src/executors/validate-nx-wiring/executor",
             "schema": "./src/executors/validate-nx-wiring/schema.json",
             "description": "Validate the webpieces validators are wired into the build via nx.json targetDefaults dependsOn"
+        },
+        "runtime-wiring-check": {
+            "implementation": "./src/executors/runtime-wiring-check/executor",
+            "schema": "./src/executors/runtime-wiring-check/schema.json",
+            "description": "Verify canonical per-project wiring; write candidates only to build output"
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.854",
+  "version": "0.4.856",
   "description": "Nx-specific webpieces validation rules, graph tooling, executors, and inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -20,12 +20,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/api-doc-model": "0.4.854",
-    "@webpieces/core-util": "0.4.854",
-    "@webpieces/eslint-rules": "0.4.854",
-    "@webpieces/rules-config": "0.4.854",
+    "@webpieces/api-doc-model": "0.4.856",
+    "@webpieces/core-util": "0.4.856",
+    "@webpieces/eslint-rules": "0.4.856",
+    "@webpieces/rules-config": "0.4.856",
     "madge": "8.0.0",
-    "@webpieces/rules-sdk": "0.4.854"
+    "@webpieces/rules-sdk": "0.4.856"
   },
   "peerDependencies": {
     "@nx/devkit": ">=18.0.0"
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@webpieces/tooling-testkit": "0.4.854"
+    "@webpieces/tooling-testkit": "0.4.856"
   },
   "types": "./src/index.d.ts",
   "bin": {

package/src/executors/generate/executor.js

@@ -1,29 +1,16 @@
 "use strict";
-/**
- * Generate Executor
- *
- * Generates the architecture dependency graph and saves it to architecture/dependencies.json, plus
- * one contract file per API under architecture/apis/ (stale ones are deleted).
- *
- * Usage:
- * nx run architecture:generate
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const approved_graph_1 = require("../../lib/runtime-wiring/approved-graph");
+const graph_loader_1 = require("../../lib/graph-loader");
 const rules_config_1 = require("@webpieces/rules-config");
 const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_cycles_1 = require("../../lib/graph-cycles");
-const graph_loader_1 = require("../../lib/graph-loader");
+const graph_loader_2 = require("../../lib/graph-loader");
 const api_contract_files_1 = require("../../lib/api-contract-files");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const tag_truth_1 = require("../../lib/tag-truth");
-const api_scanner_1 = require("../../lib/api-usage/api-scanner");
-// The unresolved-contract report moved beside the other contract reports when api-scanner.ts reached
-// its file-size limit.
-const api_contract_errors_1 = require("../../lib/api-usage/api-contract-errors");
-const external_systems_1 = require("../../lib/api-usage/external-systems");
-const runtime_config_1 = require("../../lib/runtime-config");
 const graph_visualizer_1 = require("../../lib/graph-visualizer");
 const runtime_graph_1 = require("../../lib/runtime-graph");
 const runtime_participant_resolver_1 = require("../../lib/runtime-participant-resolver");
@@ -71,32 +58,15 @@ function printRuntimeWarnings(warnings) {
  * a green run that quietly omits a service gets committed, rendered, and trusted.
  */
 // webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
-function scanApiRelations(workspaceRoot, graph, projectInfos) {
-    console.log('🔎 Scanning source for implements/uses API relations...');
-    const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
-    const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos, externalApiPaths);
-    if (scan.unresolvedApiCalls.length > 0)
-        console.warn((0, api_contract_errors_1.describeUnresolvedApiCalls)(scan.unresolvedApiCalls));
-    // #1014: restated on EVERY run, green or red. An exclusion announced once, at the moment
-    // somebody adds it, is read by the one person who already knows the decision.
-    if (scan.apiDocRules.mcpExclusions.length > 0) {
-        console.log((0, api_contract_errors_1.describeMcpExclusions)(scan.apiDocRules.mcpExclusions));
-    }
-    // A decorator argument we could not read costs the graph a basePath, a method, or a whole
-    // contract — none of which leaves a trace in the output. Name them before anything is written.
-    if (scan.nonLiteralDecoratorArgs.length > 0) {
-        console.warn((0, api_scanner_1.describeNonLiteralDecoratorArgs)(scan.nonLiteralDecoratorArgs));
-    }
-    const contracts = (0, api_scanner_1.buildApiContracts)(scan);
-    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a
-    // clock that nothing could ever fire — name it here, where the fix is one decorator away.
-    const mismatches = (0, api_scanner_1.describeMismatchedEndpointKinds)(contracts);
-    if (mismatches.length > 0) {
-        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);
-        for (const mismatch of mismatches)
-            console.error(`     • ${mismatch}`);
-    }
-    return new ScannedTables(contracts, (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
+function scanApiRelations(workspaceRoot, graph, projectInfos, graphPath = graph_loader_2.DEFAULT_GRAPH_PATH) {
+    console.log('📖 Assembling approved runtime-deps.json declarations (no source extraction)...');
+    new approved_graph_1.ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos, graphPath);
+    const saved = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
+    if (saved === null)
+        throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing approved API contract references.', undefined, undefined, [
+            new rules_config_1.Option('Migrate src/wiring.ts and review runtime-deps.json and API contract approvals before generation.', true),
+        ]);
+    return new ScannedTables(new api_contract_files_1.ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles), saved.externalSystems);
 }
 /** The two committed tables one scan produces, kept together so callers cannot persist just one. */
 class ScannedTables {
@@ -158,12 +128,25 @@ async function generateEverything(workspaceRoot, graphPath) {
     // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by
     // scanning source, so dependencies.json + the viz + the runtime graph all
     // read the same derived truth.
-    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);
+    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos, graphPath);
     const apiContracts = scanned.apiContracts;
+    saveApprovedGraph(workspaceRoot, graphPath ?? graph_loader_2.DEFAULT_GRAPH_PATH, enhancedGraph, scanned);
+    // Step 4b: Write the committed, clickable HTML view next to the JSON so
+    // dependencies.html regenerates in lock-step with dependencies.json.
+    const vizPaths = new graph_visualizer_1.GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);
+    console.log(`✅ Wrote ${vizPaths.htmlPath}`);
+    // Step 5: Generate the runtime microservice graph from the same scan.
+    // Projects tagged drawOnGraph:false are threaded through so the runtime
+    // graph hides them too (they stay flagged in runtime-dependencies.json).
+    generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts, scanned.externalSystems);
+    printGraphSummary(enhancedGraph);
+}
+// webpieces-disable no-function-outside-class -- persist the approved graph and contract tables together
+function saveApprovedGraph(workspaceRoot, effectiveGraphPath, enhancedGraph, scanned) {
     // Step 4: Write one contract file per API (architecture/apis/<Api>.json) and delete the files of
     // APIs that no longer exist. dependencies.json only LINKS to them, so an endpoint change rewrites
     // an api file and never the dependency graph. The runtime validator reads these files back.
-    const effectiveGraphPath = graphPath ?? graph_loader_1.DEFAULT_GRAPH_PATH;
+    const apiContracts = scanned.apiContracts;
     const contractFiles = new api_contract_files_1.ApiContractFiles();
     const written = contractFiles.write(workspaceRoot, effectiveGraphPath, apiContracts);
     console.log(`✅ Wrote ${written.written.length} api contract file(s)`);
@@ -174,17 +157,8 @@ async function generateEverything(workspaceRoot, graphPath) {
     // validate from the files, so anything not written here would make the two disagree.
     console.log('💾 Saving graph to architecture/dependencies.json...');
     const contractRefs = contractFiles.refsFor(apiContracts);
-    (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);
+    (0, graph_loader_2.saveGraph)(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);
     console.log('✅ Graph saved successfully');
-    // Step 4b: Write the committed, clickable HTML view next to the JSON so
-    // dependencies.html regenerates in lock-step with dependencies.json.
-    const vizPaths = new graph_visualizer_1.GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);
-    console.log(`✅ Wrote ${vizPaths.htmlPath}`);
-    // Step 5: Generate the runtime microservice graph from the same scan.
-    // Projects tagged drawOnGraph:false are threaded through so the runtime
-    // graph hides them too (they stay flagged in runtime-dependencies.json).
-    generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts, scanned.externalSystems);
-    printGraphSummary(enhancedGraph);
 }
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
@@ -205,7 +179,9 @@ async function runExecutor(options, context) {
         if (error instanceof graph_metadata_1.MetadataValidationError) {
             const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, 'webpieces.responsibilities.md');
             console.error('');
-            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');
+            console.error('⚠️  *** Refer to ' +
+                mdPath +
+                ' for how to author responsibilities.md files *** ⚠️');
         }
         return { success: false };
     }

package/src/executors/generate/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, plus\n * one contract file per API under architecture/apis/ (stale ones are deleted).\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { ProjectCycleDetector } from '../../lib/graph-cycles';\nimport { saveGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { ProjectInfo } from '../../lib/project-info';\nimport {\n    scanAndAttachApiRelations,\n    describeNonLiteralDecoratorArgs,\n    buildApiContracts,\n    describeMismatchedEndpointKinds,\n} from '../../lib/api-usage/api-scanner';\n// The unresolved-contract report moved beside the other contract reports when api-scanner.ts reached\n// its file-size limit.\nimport {\n    describeMcpExclusions,\n    describeUnresolvedApiCalls,\n} from '../../lib/api-usage/api-contract-errors';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, DERIVED from the same\n * dependencies.json (its per-project apiRelations) — one regenerate produces both committed files, and\n * validate derives from the SAME source so they can't diverge. rpc APIs become direct runtime edges;\n * pubsub APIs become edges the viz draws through a queue.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction generateRuntimeGraph(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    apiContracts: ApiContracts,\n    externalSystems: ExternalSystemDecls,\n): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(graph, hiddenProjects, apiContracts, externalSystems);\n    saveRuntimeGraph(report.graph, workspaceRoot);\n    const serviceCount = Object.keys(report.graph.services).length;\n    const queueCount = Object.keys(report.graph.queues).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges, ` +\n            `${queueCount} queues, ${report.graph.triggers.length} cron/external triggers)`,\n    );\n    // Every edge the derivation had to GUESS at. Loud on purpose: a fanned-out edge is committed and\n    // then reasoned about as if it were derived, which is how a fictional call survives for months.\n    printRuntimeWarnings(report.warnings);\n    printAutoHiddenServers(report.autoHidden);\n    // Printed here, FAILED by validate-runtime-architecture: generate must still write the graph,\n    // or the validator would have nothing to compare against and the error would be unfixable.\n    if (report.problems.length > 0) {\n        console.error(`❌ ${report.problems.length} client call(s) name a service no module answers to:`);\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n): ScannedTables {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\n    // #1014: restated on EVERY run, green or red. An exclusion announced once, at the moment\n    // somebody adds it, is read by the one person who already knows the decision.\n    if (scan.apiDocRules.mcpExclusions.length > 0) {\n        console.log(describeMcpExclusions(scan.apiDocRules.mcpExclusions));\n    }\n    // A decorator argument we could not read costs the graph a basePath, a method, or a whole\n    // contract — none of which leaves a trace in the output. Name them before anything is written.\n    if (scan.nonLiteralDecoratorArgs.length > 0) {\n        console.warn(describeNonLiteralDecoratorArgs(scan.nonLiteralDecoratorArgs));\n    }\n    const contracts = buildApiContracts(scan);\n    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a\n    // clock that nothing could ever fire — name it here, where the fix is one decorator away.\n    const mismatches = describeMismatchedEndpointKinds(contracts);\n    if (mismatches.length > 0) {\n        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);\n        for (const mismatch of mismatches) console.error(`     • ${mismatch}`);\n    }\n    return new ScannedTables(contracts, buildExternalSystems(scan.apiIndex, projectInfos));\n}\n\n/** The two committed tables one scan produces, kept together so callers cannot persist just one. */\nclass ScannedTables {\n    constructor(\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\n/**\n * The whole generation pipeline. Split out of runExecutor so that function stays a thin\n * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should\n * not be separated from the throw by fifty lines of steps.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nasync function generateEverything(workspaceRoot: string, graphPath: string | undefined): Promise<void> {\n    // Step 1: Build the full graph from nx, then transitively reduce it to the view\n    console.log(\"📊 Generating dependency graph from nx's project graph...\");\n    const reducedGraph = await generateReducedGraph();\n\n    // Step 1b: The graph is a BUILD graph — refuse a cyclic one, naming EVERY cycle. This runs\n    // before the sort deliberately: the sort also refuses, but reports one cycle and an\n    // undifferentiated list of everything tangled with it, so a repo with several cycles pays one\n    // full regeneration per cycle to discover them.\n    console.log('🔄 Checking the project graph is acyclic...');\n    const cycles = new ProjectCycleDetector();\n    cycles.assertAcyclic(reducedGraph, 'the nx project graph');\n\n    // Step 2: Topological sort (to assign levels for visualization)\n    console.log('🔄 Computing topological layers...');\n    const enhancedGraph = sortGraphTopologically(reducedGraph);\n    // ...and assert the stratification it just produced actually holds: every dependency strictly\n    // below its dependent. Safe to assert only because the graph was sorted a line ago — a stale\n    // committed file is never checked this way.\n    cycles.assertLevelsDescend(reducedGraph, cycles.levelsOf(enhancedGraph), 'the freshly sorted graph');\n\n    // Step 3: Enrich with AI metadata (framework, shortDescription, file\n    // pointers). This VALIDATES (responsibilities.md required per project)\n    // and throws before any write, so a failure never clobbers the file.\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n    new TagTruthCheck().assertTrue(enhancedGraph, projectInfos, workspaceRoot); // #1064, before any write\n\n    // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by\n    // scanning source, so dependencies.json + the viz + the runtime graph all\n    // read the same derived truth.\n    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);\n    const apiContracts = scanned.apiContracts;\n\n    // Step 4: Write one contract file per API (architecture/apis/<Api>.json) and delete the files of\n    // APIs that no longer exist. dependencies.json only LINKS to them, so an endpoint change rewrites\n    // an api file and never the dependency graph. The runtime validator reads these files back.\n    const effectiveGraphPath = graphPath ?? DEFAULT_GRAPH_PATH;\n    const contractFiles = new ApiContractFiles();\n    const written = contractFiles.write(workspaceRoot, effectiveGraphPath, apiContracts);\n    console.log(`✅ Wrote ${written.written.length} api contract file(s)`);\n    for (const deleted of written.deleted) console.log(`🗑️  Deleted stale api contract file ${deleted}`);\n\n    // Step 4a: Save the graph, INCLUDING the contract-file links and the external-system\n    // declarations the runtime derivation reads back — generate derives from the in-memory graph,\n    // validate from the files, so anything not written here would make the two disagree.\n    console.log('💾 Saving graph to architecture/dependencies.json...');\n    const contractRefs = contractFiles.refsFor(apiContracts);\n    saveGraph(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);\n    console.log('✅ Graph saved successfully');\n\n    // Step 4b: Write the committed, clickable HTML view next to the JSON so\n    // dependencies.html regenerates in lock-step with dependencies.json.\n    const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n    console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n    // Step 5: Generate the runtime microservice graph from the same scan.\n    // Projects tagged drawOnGraph:false are threaded through so the runtime\n    // graph hides them too (they stay flagged in runtime-dependencies.json).\n    generateRuntimeGraph(\n        workspaceRoot,\n        enhancedGraph,\n        hiddenProjectsIn(enhancedGraph),\n        apiContracts,\n        scanned.externalSystems,\n    );\n\n    printGraphSummary(enhancedGraph);\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        await generateEverything(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError carries its cures as Option[]; `Error.message` is only the aiMessage, so\n        // printing that alone silently drops them. renderRuleFailForHuman is the ONE renderer that\n        // numbers them, and this catch is the top-level handler for the nx target.\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Graph generation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\n/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, plus\n * one contract file per API under architecture/apis/ (stale ones are deleted).\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { ProjectCycleDetector } from '../../lib/graph-cycles';\nimport { saveGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { ProjectInfo } from '../../lib/project-info';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, DERIVED from the same\n * dependencies.json (its per-project apiRelations) — one regenerate produces both committed files, and\n * validate derives from the SAME source so they can't diverge. rpc APIs become direct runtime edges;\n * pubsub APIs become edges the viz draws through a queue.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction generateRuntimeGraph(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    apiContracts: ApiContracts,\n    externalSystems: ExternalSystemDecls,\n): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(graph, hiddenProjects, apiContracts, externalSystems);\n    saveRuntimeGraph(report.graph, workspaceRoot);\n    const serviceCount = Object.keys(report.graph.services).length;\n    const queueCount = Object.keys(report.graph.queues).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges, ` +\n            `${queueCount} queues, ${report.graph.triggers.length} cron/external triggers)`,\n    );\n    // Every edge the derivation had to GUESS at. Loud on purpose: a fanned-out edge is committed and\n    // then reasoned about as if it were derived, which is how a fictional call survives for months.\n    printRuntimeWarnings(report.warnings);\n    printAutoHiddenServers(report.autoHidden);\n    // Printed here, FAILED by validate-runtime-architecture: generate must still write the graph,\n    // or the validator would have nothing to compare against and the error would be unfixable.\n    if (report.problems.length > 0) {\n        console.error(\n            `❌ ${report.problems.length} client call(s) name a service no module answers to:`,\n        );\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n): ScannedTables {\n    console.log('📖 Assembling approved runtime-deps.json declarations (no source extraction)...');\n    new ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos, graphPath);\n    const saved = loadBlessedGraph(workspaceRoot, graphPath);\n    if (saved === null)\n        throw new RuleFailError(\n            'validate-runtime-architecture',\n            'Missing approved API contract references.',\n            undefined,\n            undefined,\n            [\n                new Option(\n                    'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals before generation.',\n                    true,\n                ),\n            ],\n        );\n    return new ScannedTables(\n        new ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles),\n        saved.externalSystems,\n    );\n}\n\n/** The two committed tables one scan produces, kept together so callers cannot persist just one. */\nclass ScannedTables {\n    constructor(\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\n/**\n * The whole generation pipeline. Split out of runExecutor so that function stays a thin\n * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should\n * not be separated from the throw by fifty lines of steps.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nasync function generateEverything(\n    workspaceRoot: string,\n    graphPath: string | undefined,\n): Promise<void> {\n    // Step 1: Build the full graph from nx, then transitively reduce it to the view\n    console.log(\"📊 Generating dependency graph from nx's project graph...\");\n    const reducedGraph = await generateReducedGraph();\n\n    // Step 1b: The graph is a BUILD graph — refuse a cyclic one, naming EVERY cycle. This runs\n    // before the sort deliberately: the sort also refuses, but reports one cycle and an\n    // undifferentiated list of everything tangled with it, so a repo with several cycles pays one\n    // full regeneration per cycle to discover them.\n    console.log('🔄 Checking the project graph is acyclic...');\n    const cycles = new ProjectCycleDetector();\n    cycles.assertAcyclic(reducedGraph, 'the nx project graph');\n\n    // Step 2: Topological sort (to assign levels for visualization)\n    console.log('🔄 Computing topological layers...');\n    const enhancedGraph = sortGraphTopologically(reducedGraph);\n    // ...and assert the stratification it just produced actually holds: every dependency strictly\n    // below its dependent. Safe to assert only because the graph was sorted a line ago — a stale\n    // committed file is never checked this way.\n    cycles.assertLevelsDescend(\n        reducedGraph,\n        cycles.levelsOf(enhancedGraph),\n        'the freshly sorted graph',\n    );\n\n    // Step 3: Enrich with AI metadata (framework, shortDescription, file\n    // pointers). This VALIDATES (responsibilities.md required per project)\n    // and throws before any write, so a failure never clobbers the file.\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n    new TagTruthCheck().assertTrue(enhancedGraph, projectInfos, workspaceRoot); // #1064, before any write\n\n    // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by\n    // scanning source, so dependencies.json + the viz + the runtime graph all\n    // read the same derived truth.\n    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos, graphPath);\n    const apiContracts = scanned.apiContracts;\n\n    saveApprovedGraph(workspaceRoot, graphPath ?? DEFAULT_GRAPH_PATH, enhancedGraph, scanned);\n\n    // Step 4b: Write the committed, clickable HTML view next to the JSON so\n    // dependencies.html regenerates in lock-step with dependencies.json.\n    const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n    console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n    // Step 5: Generate the runtime microservice graph from the same scan.\n    // Projects tagged drawOnGraph:false are threaded through so the runtime\n    // graph hides them too (they stay flagged in runtime-dependencies.json).\n    generateRuntimeGraph(\n        workspaceRoot,\n        enhancedGraph,\n        hiddenProjectsIn(enhancedGraph),\n        apiContracts,\n        scanned.externalSystems,\n    );\n\n    printGraphSummary(enhancedGraph);\n}\n\n// webpieces-disable no-function-outside-class -- persist the approved graph and contract tables together\nfunction saveApprovedGraph(\n    workspaceRoot: string,\n    effectiveGraphPath: string,\n    enhancedGraph: EnhancedGraph,\n    scanned: ScannedTables,\n): void {\n    // Step 4: Write one contract file per API (architecture/apis/<Api>.json) and delete the files of\n    // APIs that no longer exist. dependencies.json only LINKS to them, so an endpoint change rewrites\n    // an api file and never the dependency graph. The runtime validator reads these files back.\n    const apiContracts = scanned.apiContracts;\n    const contractFiles = new ApiContractFiles();\n    const written = contractFiles.write(workspaceRoot, effectiveGraphPath, apiContracts);\n    console.log(`✅ Wrote ${written.written.length} api contract file(s)`);\n    for (const deleted of written.deleted)\n        console.log(`🗑️  Deleted stale api contract file ${deleted}`);\n\n    // Step 4a: Save the graph, INCLUDING the contract-file links and the external-system\n    // declarations the runtime derivation reads back — generate derives from the in-memory graph,\n    // validate from the files, so anything not written here would make the two disagree.\n    console.log('💾 Saving graph to architecture/dependencies.json...');\n    const contractRefs = contractFiles.refsFor(apiContracts);\n    saveGraph(\n        enhancedGraph,\n        workspaceRoot,\n        effectiveGraphPath,\n        contractRefs,\n        scanned.externalSystems,\n    );\n    console.log('✅ Graph saved successfully');\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        await generateEverything(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError carries its cures as Option[]; `Error.message` is only the aiMessage, so\n        // printing that alone silently drops them. renderRuleFailForHuman is the ONE renderer that\n        // numbers them, and this catch is the top-level handler for the nx target.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Graph generation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error(\n                '⚠️  *** Refer to ' +\n                    mdPath +\n                    ' for how to author responsibilities.md files *** ⚠️',\n            );\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/runtime-wiring-check/executor.d.ts

@@ -0,0 +1,10 @@
+import type { ExecutorContext } from '@nx/devkit';
+export declare class RuntimeWiringCheckOptions {
+    readonly outputPath: string;
+    constructor(outputPath: string);
+}
+export declare class RuntimeWiringCheckResult {
+    readonly success: boolean;
+    constructor(success: boolean);
+}
+export default function executor(options: RuntimeWiringCheckOptions, context: ExecutorContext): Promise<RuntimeWiringCheckResult>;

package/src/executors/runtime-wiring-check/executor.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeWiringCheckResult = exports.RuntimeWiringCheckOptions = void 0;
+exports.default = executor;
+const rules_config_1 = require("@webpieces/rules-config");
+const graph_metadata_1 = require("../../lib/graph-metadata");
+const verification_1 = require("../../lib/runtime-wiring/verification");
+const toError_1 = require("../../toError");
+class RuntimeWiringCheckOptions {
+    outputPath;
+    constructor(outputPath) {
+        this.outputPath = outputPath;
+    }
+}
+exports.RuntimeWiringCheckOptions = RuntimeWiringCheckOptions;
+class RuntimeWiringCheckResult {
+    success;
+    constructor(success) {
+        this.success = success;
+    }
+}
+exports.RuntimeWiringCheckResult = RuntimeWiringCheckResult;
+// webpieces-disable no-function-outside-class -- Nx executor process entry point
+async function executor(options, context) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const infos = await (0, graph_metadata_1.collectProjectInfo)();
+        const info = context.projectName === undefined ? undefined : infos.get(context.projectName);
+        if (info === undefined)
+            throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'runtime-wiring-check requires a named project.', undefined, undefined, [
+                new rules_config_1.Option('Run nx run <project>:runtime-wiring-check on a tagged project.', true),
+            ]);
+        new verification_1.RuntimeWiringVerification().verify(context.root, info, infos, options.outputPath);
+        return { success: true };
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.error(error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/src/executors/runtime-wiring-check/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/runtime-wiring-check/executor.ts"],"names":[],"mappings":";;;AAeA,2BA8BC;AA5CD,0DAAwF;AACxF,6DAA8D;AAC9D,wEAAkF;AAClF,2CAAwC;AAExC,MAAa,yBAAyB;IACN;IAA5B,YAA4B,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;IAAG,CAAC;CACrD;AAFD,8DAEC;AAED,MAAa,wBAAwB;IACL;IAA5B,YAA4B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;CACnD;AAFD,4DAEC;AAED,iFAAiF;AAClE,KAAK,UAAU,QAAQ,CAClC,OAAkC,EAClC,OAAwB;IAExB,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5F,IAAI,IAAI,KAAK,SAAS;YAClB,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,gDAAgD,EAChD,SAAS,EACT,SAAS,EACT;gBACI,IAAI,qBAAM,CACN,gEAAgE,EAChE,IAAI,CACP;aACJ,CACJ,CAAC;QACN,IAAI,wCAAyB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACtF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CACT,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CACjF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\nimport { renderRuleFailForHuman, Option, RuleFailError } from '@webpieces/rules-config';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { RuntimeWiringVerification } from '../../lib/runtime-wiring/verification';\nimport { toError } from '../../toError';\n\nexport class RuntimeWiringCheckOptions {\n    constructor(public readonly outputPath: string) {}\n}\n\nexport class RuntimeWiringCheckResult {\n    constructor(public readonly success: boolean) {}\n}\n\n// webpieces-disable no-function-outside-class -- Nx executor process entry point\nexport default async function executor(\n    options: RuntimeWiringCheckOptions,\n    context: ExecutorContext,\n): Promise<RuntimeWiringCheckResult> {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const infos = await collectProjectInfo();\n        const info = context.projectName === undefined ? undefined : infos.get(context.projectName);\n        if (info === undefined)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'runtime-wiring-check requires a named project.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Run nx run <project>:runtime-wiring-check on a tagged project.',\n                        true,\n                    ),\n                ],\n            );\n        new RuntimeWiringVerification().verify(context.root, info, infos, options.outputPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message,\n        );\n        return { success: false };\n    }\n}\n"]}

package/src/executors/runtime-wiring-check/schema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "version": 1,
+    "title": "Verify canonical runtime wiring against approved declarations",
+    "type": "object",
+    "properties": {
+        "outputPath": {
+            "type": "string",
+            "description": "Configured project build output directory for candidates"
+        }
+    },
+    "required": ["outputPath"],
+    "additionalProperties": false
+}

package/src/executors/validate-api-lib-tag/executor.js

@@ -13,8 +13,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const rules_config_1 = require("@webpieces/rules-config");
 const graph_metadata_1 = require("../../lib/graph-metadata");
-const api_scanner_1 = require("../../lib/api-usage/api-scanner");
+const api_contract_evidence_1 = require("../../lib/api-usage/api-contract-evidence");
+const runtime_config_1 = require("../../lib/runtime-config");
 const api_lib_tag_validator_1 = require("../../lib/api-usage/api-lib-tag-validator");
 const toError_1 = require("../../toError");
 // webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor
@@ -24,7 +26,7 @@ async function runExecutor(_options, context) {
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
-        const scan = new api_scanner_1.ApiUsageScanner(workspaceRoot, projectInfos).scan();
+        const scan = new api_contract_evidence_1.ApiContractEvidence().collect(workspaceRoot, projectInfos, (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths);
         const violations = (0, api_lib_tag_validator_1.findApiLibTagViolations)(projectInfos, scan, workspaceRoot);
         if (violations.length === 0) {
             console.log('✅ role:api-lib / role:api-client match the code (every api library exports a contract or only wire types, and vice-versa).');
@@ -39,7 +41,7 @@ async function runExecutor(_options, context) {
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
-        console.error('❌ api-lib tag validation failed:', error.message);
+        console.error('❌ api-lib tag validation failed:', error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message);
         return { success: false };
     }
 }

package/src/executors/validate-api-lib-tag/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-lib-tag/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAiBH,8BA8BC;AA5CD,6DAA8D;AAC9D,iEAAkE;AAClE,qFAAgH;AAChH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAkC,EAClC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;IAE3E,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,6BAAe,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,MAAM,UAAU,GAAG,IAAA,+CAAuB,EAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,4HAA4H,CAAC,CAAC;YAC1I,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,kDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API-lib Tag Executor\n *\n * Fails when the api roles and the code disagree, in either direction: a project\n * tagged role:api-lib that exports neither a contract (@ApiPath/@Rpc/@PubSub,\n * @WpInternal/@WpIpcEndpoint, or an in-process abstract …Api) nor only wire types,\n * a role:api-client that exports no contract, or a project that exports an\n * @ApiPath/@Rpc/@PubSub abstract class but carries neither api role (#1064, D3).\n *\n * Usage:\n * nx run architecture:validate-api-lib-tag\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { ApiUsageScanner } from '../../lib/api-usage/api-scanner';\nimport { findApiLibTagViolations, describeApiLibTagViolation } from '../../lib/api-usage/api-lib-tag-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiLibTagOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiLibTagOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🏷️  Validating role:api-lib tag ⇔ API contract exports\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const projectInfos = await collectProjectInfo();\n        const scan = new ApiUsageScanner(workspaceRoot, projectInfos).scan();\n        const violations = findApiLibTagViolations(projectInfos, scan, workspaceRoot);\n\n        if (violations.length === 0) {\n            console.log('✅ role:api-lib / role:api-client match the code (every api library exports a contract or only wire types, and vice-versa).');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} role:api-lib tag/code mismatch(es):\\n`);\n        for (const violation of violations) {\n            console.error(describeApiLibTagViolation(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ api-lib tag validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-lib-tag/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAsBH,8BAuCC;AA3DD,0DAAgF;AAEhF,6DAA8D;AAC9D,qFAAgF;AAChF,6DAA6D;AAC7D,qFAGmD;AACnD,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAkC,EAClC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;IAE3E,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,2CAAmB,EAAE,CAAC,OAAO,CAC1C,aAAa,EACb,YAAY,EACZ,IAAA,kCAAiB,EAAC,aAAa,CAAC,CAAC,gBAAgB,CACpD,CAAC;QACF,MAAM,UAAU,GAAG,IAAA,+CAAuB,EAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CACP,4HAA4H,CAC/H,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,kDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CACT,kCAAkC,EAClC,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CACjF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API-lib Tag Executor\n *\n * Fails when the api roles and the code disagree, in either direction: a project\n * tagged role:api-lib that exports neither a contract (@ApiPath/@Rpc/@PubSub,\n * @WpInternal/@WpIpcEndpoint, or an in-process abstract …Api) nor only wire types,\n * a role:api-client that exports no contract, or a project that exports an\n * @ApiPath/@Rpc/@PubSub abstract class but carries neither api role (#1064, D3).\n *\n * Usage:\n * nx run architecture:validate-api-lib-tag\n */\n\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport type { ExecutorContext } from '@nx/devkit';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { ApiContractEvidence } from '../../lib/api-usage/api-contract-evidence';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport {\n    findApiLibTagViolations,\n    describeApiLibTagViolation,\n} from '../../lib/api-usage/api-lib-tag-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiLibTagOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiLibTagOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🏷️  Validating role:api-lib tag ⇔ API contract exports\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const projectInfos = await collectProjectInfo();\n        const scan = new ApiContractEvidence().collect(\n            workspaceRoot,\n            projectInfos,\n            loadRuntimeConfig(workspaceRoot).externalApiPaths,\n        );\n        const violations = findApiLibTagViolations(projectInfos, scan, workspaceRoot);\n\n        if (violations.length === 0) {\n            console.log(\n                '✅ role:api-lib / role:api-client match the code (every api library exports a contract or only wire types, and vice-versa).',\n            );\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} role:api-lib tag/code mismatch(es):\\n`);\n        for (const violation of violations) {\n            console.error(describeApiLibTagViolation(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(\n            '❌ api-lib tag validation failed:',\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message,\n        );\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-api-relations/executor.js

@@ -12,11 +12,13 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const rules_config_1 = require("@webpieces/rules-config");
 const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_metadata_1 = require("../../lib/graph-metadata");
-const api_scanner_1 = require("../../lib/api-usage/api-scanner");
-const runtime_config_1 = require("../../lib/runtime-config");
+const approved_graph_1 = require("../../lib/runtime-wiring/approved-graph");
+const graph_loader_1 = require("../../lib/graph-loader");
+const api_contract_files_1 = require("../../lib/api-contract-files");
 const api_relations_validator_1 = require("../../lib/api-usage/api-relations-validator");
 const toError_1 = require("../../toError");
 // webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor
@@ -30,11 +32,12 @@ async function runExecutor(_options, context) {
         const rawGraph = await (0, graph_generator_1.generateGraph)();
         const graph = (0, graph_sorter_1.sortGraphTopologically)(rawGraph);
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
-        // Same externalApiPaths as generate: a vendor lib must be classified by the SAME rules here,
-        // or a server depending on one would be reported unclassified purely because this scan was
-        // configured differently from the one that wrote the graph.
-        const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
-        const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos, externalApiPaths);
+        new approved_graph_1.ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos);
+        const saved = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot);
+        if (saved === null)
+            return { success: false };
+        const contracts = new api_contract_files_1.ApiContractFiles().load(workspaceRoot, 'architecture/dependencies.json', saved.apiContractFiles);
+        const scan = new api_relations_validator_1.ApiRelationEvidence(new Set(Object.keys(graph).filter((name) => graph[name].runtimeComposition)), new Set(Object.values(contracts).map((contract) => contract.owner)), [], new Map(Object.entries(contracts).map((entry) => [entry[0], new api_relations_validator_1.ApiOwnerIdentity(entry[0], entry[1].owner)])));
         const violations = (0, api_relations_validator_1.findUnclassifiedApiDeps)(graph, projectInfos, scan);
         if (violations.length === 0) {
             console.log('✅ Every server/client api-lib dependency is implemented or used.');
@@ -49,7 +52,7 @@ async function runExecutor(_options, context) {
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
-        console.error('❌ API relations validation failed:', error.message);
+        console.error('❌ API relations validation failed:', error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message);
         return { success: false };
     }
 }

package/src/executors/validate-api-relations/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-relations/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAoBH,8BAsCC;AAvDD,+DAA0D;AAC1D,yDAAgE;AAChE,6DAA8D;AAC9D,iEAA4E;AAC5E,6DAA6D;AAC7D,yFAAkH;AAClH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAqC,EACrC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,0EAA0E,CAAC,CAAC;IAExF,8DAA8D;IAC9D,IAAI,CAAC;QACD,4EAA4E;QAC5E,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,MAAM,IAAA,+BAAa,GAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAA,qCAAsB,EAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,6FAA6F;QAC7F,2FAA2F;QAC3F,4DAA4D;QAC5D,MAAM,gBAAgB,GAAG,IAAA,kCAAiB,EAAC,aAAa,CAAC,CAAC,gBAAgB,CAAC;QAC3E,MAAM,IAAI,GAAG,IAAA,uCAAyB,EAAC,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,gBAAgB,CAAC,CAAC;QAE7F,MAAM,UAAU,GAAG,IAAA,iDAAuB,EAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,oDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API Relations Executor\n *\n * Fails when a runnable project (role:server / role:client) depends on an api-lib\n * but the source scan finds it neither IMPLEMENTS (serves via addRoutes) nor USES\n * (calls via createRpcClient/createPubSubClient) any of that api-lib's contracts.\n * Such an edge is an unexplained dependency — a dead import or forgotten wiring.\n *\n * Usage:\n * nx run architecture:validate-api-relations\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations } from '../../lib/api-usage/api-scanner';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { findUnclassifiedApiDeps, describeUnclassifiedApiDep } from '../../lib/api-usage/api-relations-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiRelationsOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiRelationsOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔗 Validating API Relations (implements/uses per api-lib dependency)\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Full (un-reduced) graph so a direct api-lib dependency is never hidden by\n        // transitive reduction, then attach the derived apiRelations.\n        const rawGraph = await generateGraph();\n        const graph = sortGraphTopologically(rawGraph);\n        const projectInfos = await collectProjectInfo();\n        // Same externalApiPaths as generate: a vendor lib must be classified by the SAME rules here,\n        // or a server depending on one would be reported unclassified purely because this scan was\n        // configured differently from the one that wrote the graph.\n        const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n        const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n\n        const violations = findUnclassifiedApiDeps(graph, projectInfos, scan);\n        if (violations.length === 0) {\n            console.log('✅ Every server/client api-lib dependency is implemented or used.');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} unexplained api-lib dependenc(ies):\\n`);\n        for (const violation of violations) {\n            console.error(describeUnclassifiedApiDep(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ API relations validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-relations/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate API Relations Executor\n *\n * Fails when a runnable project (role:server / role:client) depends on an api-lib\n * but the source scan finds it neither IMPLEMENTS (serves via addRoutes) nor USES\n * (calls via createRpcClient/createPubSubClient) any of that api-lib's contracts.\n * Such an edge is an unexplained dependency — a dead import or forgotten wiring.\n *\n * Usage:\n * nx run architecture:validate-api-relations\n */\n\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport {\n    ApiRelationEvidence,\n    ApiOwnerIdentity,\n    findUnclassifiedApiDeps,\n    describeUnclassifiedApiDep,\n} from '../../lib/api-usage/api-relations-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiRelationsOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiRelationsOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔗 Validating API Relations (implements/uses per api-lib dependency)\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Full (un-reduced) graph so a direct api-lib dependency is never hidden by\n        // transitive reduction, then attach the derived apiRelations.\n        const rawGraph = await generateGraph();\n        const graph = sortGraphTopologically(rawGraph);\n        const projectInfos = await collectProjectInfo();\n        new ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos);\n        const saved = loadBlessedGraph(workspaceRoot);\n        if (saved === null) return { success: false };\n        const contracts = new ApiContractFiles().load(\n            workspaceRoot,\n            'architecture/dependencies.json',\n            saved.apiContractFiles,\n        );\n        const scan = new ApiRelationEvidence(\n            new Set(Object.keys(graph).filter((name) => graph[name].runtimeComposition)),\n            new Set(Object.values(contracts).map((contract) => contract.owner)),\n            [],\n            new Map(\n                Object.entries(contracts).map(\n                    (entry) => [entry[0], new ApiOwnerIdentity(entry[0], entry[1].owner)] as const,\n                ),\n            ),\n        );\n        const violations = findUnclassifiedApiDeps(graph, projectInfos, scan);\n        if (violations.length === 0) {\n            console.log('✅ Every server/client api-lib dependency is implemented or used.');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} unexplained api-lib dependenc(ies):\\n`);\n        for (const violation of violations) {\n            console.error(describeUnclassifiedApiDep(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(\n            '❌ API relations validation failed:',\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message,\n        );\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-architecture-unchanged/executor.d.ts

@@ -30,7 +30,7 @@ export declare function describeTableDrift(current: CurrentArchitecture, saved:
  * apiRelations — so this validator compares like-for-like against the committed file.
  */
 export declare class CurrentGraphBuilder {
-    build(workspaceRoot: string): Promise<CurrentArchitecture>;
+    build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture>;
 }
 /** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
 export declare class CurrentArchitecture {

package/src/executors/validate-architecture-unchanged/executor.js

@@ -19,10 +19,7 @@ const graph_comparator_1 = require("../../lib/graph-comparator");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const tag_truth_1 = require("../../lib/tag-truth");
-const api_scanner_1 = require("../../lib/api-usage/api-scanner");
-const external_systems_1 = require("../../lib/api-usage/external-systems");
-const api_contract_files_1 = require("../../lib/api-contract-files");
-const runtime_config_1 = require("../../lib/runtime-config");
+const approved_graph_1 = require("../../lib/runtime-wiring/approved-graph");
 const rule_gate_1 = require("../../lib/rule-gate");
 const toError_1 = require("../../toError");
 const TMP_MD_FILE = 'webpieces.dependencies.md';
@@ -113,7 +110,7 @@ function describeExternalSystemDrift(current, saved) {
  * apiRelations — so this validator compares like-for-like against the committed file.
  */
 class CurrentGraphBuilder {
-    async build(workspaceRoot) {
+    async build(workspaceRoot, graphPath) {
         console.log('📊 Generating current dependency graph...');
         const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
         console.log('🔄 Computing topological layers...');
@@ -122,12 +119,13 @@ class CurrentGraphBuilder {
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
         (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
         new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
-        console.log('🔎 Scanning source for implements/uses API relations...');
-        // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor
-        // relation from the regenerated graph and report drift against a perfectly fresh file.
-        const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
-        const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, currentGraph, projectInfos, externalApiPaths);
-        return new CurrentArchitecture(currentGraph, new api_contract_files_1.ApiContractFiles().refsFor((0, api_scanner_1.buildApiContracts)(scan)), (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
+        new approved_graph_1.ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);
+        const saved = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
+        if (saved === null)
+            throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing approved graph.', undefined, undefined, [
+                new rules_config_1.Option('Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.', true),
+            ]);
+        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems);
     }
 }
 exports.CurrentGraphBuilder = CurrentGraphBuilder;
@@ -146,13 +144,9 @@ exports.CurrentArchitecture = CurrentArchitecture;
 /** The bootstrap path: there is nothing to diff against yet, so say how to create it. */
 // webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file
 function reportMissingGraph() {
-    console.error('❌ No saved graph found at architecture/dependencies.json');
-    console.error('');
-    console.error('To initialize:');
-    console.error('  1. Run: nx run architecture:generate');
-    console.error('  2. Run: nx run architecture:visualize');
-    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');
-    console.error('  4. Commit architecture/dependencies.json');
+    throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing reviewed architecture/dependencies.json.', undefined, undefined, [
+        new rules_config_1.Option('Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{"<ApiName>":"apis/<ApiName>.json"}, and reviewed externalSystems. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.', true),
+    ]);
 }
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
@@ -172,7 +166,7 @@ async function runExecutor(options, context) {
         }
         // Steps 1-3: build + enrich + scan the current graph (same pipeline the
         // generator runs, so any drift is caught).
-        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot);
+        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot, graphPath);
         // Step 4: Load saved graph
         console.log('📂 Loading saved graph...');
         const savedGraph = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
@@ -204,12 +198,16 @@ async function runExecutor(options, context) {
         // carries its cures in Option[]; render them rather than dropping them with `.message`.
         const rendered = error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message;
         console.error('❌ Architecture validation failed:', rendered);
-        if (error instanceof graph_metadata_1.MetadataValidationError) {
-            const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, 'webpieces.responsibilities.md');
-            console.error('');
-            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');
-        }
+        reportMetadataFailure(error, workspaceRoot);
         return { success: false };
     }
 }
+// webpieces-disable no-function-outside-class -- executor diagnostic formatting
+function reportMetadataFailure(error, workspaceRoot) {
+    if (error instanceof graph_metadata_1.MetadataValidationError) {
+        const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, 'webpieces.responsibilities.md');
+        console.error('');
+        console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');
+    }
+}
 //# sourceMappingURL=executor.js.map