@webpieces/nx-webpieces-rules 0.4.460 → 0.4.462

package/src/lib/runtime-config.d.ts

@@ -7,7 +7,8 @@
  *   "runtime-architecture": {
  *     "mode": "ON",                          // "OFF" disables the whole feature
  *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
- *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
+ *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ],
+ *     "showExternalNodes": true               // draw firestore/gmail/... as terminal nodes
  *   }
  */
 import { SkipRuleResult } from '@webpieces/rules-config';
@@ -22,6 +23,8 @@ export interface RuntimeRuleConfig {
     ignoreModifiedUntilEpoch?: number;
     ignoreRuleWhileOnBranch?: string;
     allowedCycles: AllowedCycle[];
+    /** Render the dashed external terminal nodes in the runtime viz (default true). */
+    showExternalNodes: boolean;
 }
 /** Load the runtime-architecture rule config (with safe defaults). */
 export declare function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig;

package/src/lib/runtime-config.js

@@ -8,7 +8,8 @@
  *   "runtime-architecture": {
  *     "mode": "ON",                          // "OFF" disables the whole feature
  *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
- *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
+ *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ],
+ *     "showExternalNodes": true               // draw firestore/gmail/... as terminal nodes
  *   }
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -32,6 +33,9 @@ function loadRuntimeConfig(workspaceRoot) {
         ignoreModifiedUntilEpoch: typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,
         ignoreRuleWhileOnBranch: typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,
         allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],
+        // Opt-OUT: the external systems are the ones that page you at 3am, so they are drawn unless
+        // a repo explicitly says its external surface is too noisy to be useful.
+        showExternalNodes: raw.showExternalNodes !== false,
     };
 }
 /**

package/src/lib/runtime-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAmCH,8CAYC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AArED,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA0BxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,uBAAuB,EACnB,OAAO,GAAG,CAAC,uBAAuB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS;QAC7F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;KACjG,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"ignoreModifiedUntilEpoch\": 0,         // whole-rule punt (epoch seconds)\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ]\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles: AllowedCycle[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles?: AllowedCycle[];\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        ignoreModifiedUntilEpoch:\n            typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,\n        ignoreRuleWhileOnBranch:\n            typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (ignoreRuleWhileOnBranch) or until the epoch passes\n * (ignoreModifiedUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.ignoreModifiedUntilEpoch, config.ignoreRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAsCH,8CAeC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AA3ED,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA6BxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,uBAAuB,EACnB,OAAO,GAAG,CAAC,uBAAuB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS;QAC7F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;QAC9F,4FAA4F;QAC5F,yEAAyE;QACzE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,KAAK,KAAK;KACrD,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"ignoreModifiedUntilEpoch\": 0,         // whole-rule punt (epoch seconds)\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ],\n *     \"showExternalNodes\": true               // draw firestore/gmail/... as terminal nodes\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles: AllowedCycle[];\n    /** Render the dashed external terminal nodes in the runtime viz (default true). */\n    showExternalNodes: boolean;\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles?: AllowedCycle[];\n    showExternalNodes?: boolean;\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        ignoreModifiedUntilEpoch:\n            typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,\n        ignoreRuleWhileOnBranch:\n            typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n        // Opt-OUT: the external systems are the ones that page you at 3am, so they are drawn unless\n        // a repo explicitly says its external surface is too noisy to be useful.\n        showExternalNodes: raw.showExternalNodes !== false,\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (ignoreRuleWhileOnBranch) or until the epoch passes\n * (ignoreModifiedUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.ignoreModifiedUntilEpoch, config.ignoreRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}

package/src/lib/runtime-graph.d.ts

@@ -11,13 +11,35 @@
  * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api
  * Y and X `implements` api Y. This edge does not exist in the compile-time
  * dependencies.json (both Z and X only compile-depend on the api library Y).
+ *
+ * WHICH X is decided by the call site, not by "everyone who implements Y":
+ * `createRpcClient(Y, new ClientConfig('helper-fsdb'))` names its target, kept as
+ * `ApiRef.targetService`, and matched against each node's DECLARED `serviceName`
+ * (project.json metadata.webpieces.serviceName). Fanning an edge out to every
+ * implementer instead is catastrophic for a company-wide contract registered in a
+ * shared library — it manufactures calls that cannot happen, and cycles that do
+ * not exist. When a target cannot be resolved the old fan-out still happens, but
+ * a warning names the call site (see RuntimeGraphReport.warnings): a wrong-but-
+ * green graph is worse than a failing one, so it must never degrade silently.
  */
 import type { EnhancedGraph } from './graph-sorter';
 import type { ApiTransport } from './api-usage/api-relations';
 export declare const DEFAULT_RUNTIME_GRAPH_PATH = "architecture/runtime-dependencies.json";
 export interface RuntimeService {
     level: number;
+    /**
+     * The name clients address this service by (`new ClientConfig('helper-fsdb')`), declared in its
+     * project.json. Absent for a service nothing calls by name (e.g. a browser app).
+     */
+    serviceName?: string;
     implements: string[];
+    /**
+     * apiClassName -> the LIBRARY project whose apiRelations declared that implements, for the apis
+     * this service serves through an embedded library rather than its own source (e.g. a shared
+     * route-registration lib). Answers "who implements WarmupApi, and where did that come from?",
+     * which previously required walking the dependsOn closure by hand.
+     */
+    implementsVia?: Record<string, string>;
     uses: string[];
     dependsOn: string[];
     /**
@@ -34,6 +56,12 @@ export interface RuntimeApi {
     usedBy: string[];
     /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */
     type?: ApiTransport;
+    /**
+     * The api-lib project that OWNS this contract. For a contract nothing in-repo implements, this
+     * is the external library the calls leave the repo through (`lib-firestore`, `lib-gmail`), which
+     * is what the runtime viz labels its terminal external nodes with.
+     */
+    owner?: string;
 }
 export interface RuntimeEdge {
     from: string;
@@ -56,6 +84,35 @@ export interface RuntimeGraph {
     runtimeEdges: RuntimeEdge[];
     unresolvedUses: RuntimeUnresolved[];
 }
+/**
+ * The derived graph PLUS everything the derivation had to guess at. `warnings` is deliberately not
+ * part of RuntimeGraph: it is not committed data, it is the report that stops a guessed edge from
+ * passing for a derived one. Executors print it.
+ */
+export declare class RuntimeGraphReport {
+    readonly graph: RuntimeGraph;
+    /** Human-readable lines naming every call site whose target the graph could not pin down. */
+    readonly warnings: string[];
+    /**
+     * Call sites that name a target the repo does not contain. Unlike a warning these FAIL the
+     * build: the contract IS served in-repo, so the name is a typo or a stale rename, and the
+     * only reason it stayed invisible is that the graph quietly fanned the edge out instead.
+     * (A call to a service outside the repo never reaches here — nothing in-repo implements its
+     * contract, so it is `unresolvedUses`.)
+     */
+    readonly problems: string[];
+    constructor(graph: RuntimeGraph, 
+    /** Human-readable lines naming every call site whose target the graph could not pin down. */
+    warnings: string[], 
+    /**
+     * Call sites that name a target the repo does not contain. Unlike a warning these FAIL the
+     * build: the contract IS served in-repo, so the name is a typo or a stale rename, and the
+     * only reason it stayed invisible is that the graph quietly fanned the edge out instead.
+     * (A call to a service outside the repo never reaches here — nothing in-repo implements its
+     * contract, so it is `unresolvedUses`.)
+     */
+    problems?: string[]);
+}
 /** Adjacency (service -> [targets]) from a loaded runtime graph. */
 export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]>;
 /**
@@ -65,6 +122,13 @@ export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, st
  * runtime visualizer omits their nodes + edges.
  */
 export declare function deriveRuntimeGraph(projects: EnhancedGraph, hiddenProjects?: Set<string>): RuntimeGraph;
+/**
+ * The same derivation, plus the warnings it produced (every edge it had to GUESS at). Executors use
+ * this form and print the warnings; `deriveRuntimeGraph` is the convenience form for callers that
+ * only want the data. The warnings are deliberately kept OUT of runtime-dependencies.json — a graph
+ * file that records its own doubts would just get committed and stop being read.
+ */
+export declare function deriveRuntimeGraphReport(projects: EnhancedGraph, hiddenProjects?: Set<string>): RuntimeGraphReport;
 export declare function saveRuntimeGraph(graph: RuntimeGraph, workspaceRoot: string, graphPath?: string): void;
 export declare function runtimeGraphFileExists(workspaceRoot: string, graphPath?: string): boolean;
 export declare function loadRuntimeGraph(workspaceRoot: string, graphPath?: string): RuntimeGraph | null;

package/src/lib/runtime-graph.js

@@ -12,11 +12,22 @@
  * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api
  * Y and X `implements` api Y. This edge does not exist in the compile-time
  * dependencies.json (both Z and X only compile-depend on the api library Y).
+ *
+ * WHICH X is decided by the call site, not by "everyone who implements Y":
+ * `createRpcClient(Y, new ClientConfig('helper-fsdb'))` names its target, kept as
+ * `ApiRef.targetService`, and matched against each node's DECLARED `serviceName`
+ * (project.json metadata.webpieces.serviceName). Fanning an edge out to every
+ * implementer instead is catastrophic for a company-wide contract registered in a
+ * shared library — it manufactures calls that cannot happen, and cycles that do
+ * not exist. When a target cannot be resolved the old fan-out still happens, but
+ * a warning names the call site (see RuntimeGraphReport.warnings): a wrong-but-
+ * green graph is worse than a failing one, so it must never degrade silently.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RUNTIME_GRAPH_PATH = void 0;
+exports.RuntimeGraphReport = exports.DEFAULT_RUNTIME_GRAPH_PATH = void 0;
 exports.runtimeAdjacency = runtimeAdjacency;
 exports.deriveRuntimeGraph = deriveRuntimeGraph;
+exports.deriveRuntimeGraphReport = deriveRuntimeGraphReport;
 exports.saveRuntimeGraph = saveRuntimeGraph;
 exports.runtimeGraphFileExists = runtimeGraphFileExists;
 exports.loadRuntimeGraph = loadRuntimeGraph;
@@ -28,6 +39,32 @@ const graph_sorter_1 = require("./graph-sorter");
 const api_relations_1 = require("./api-usage/api-relations");
 const toError_1 = require("../toError");
 exports.DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';
+/**
+ * The derived graph PLUS everything the derivation had to guess at. `warnings` is deliberately not
+ * part of RuntimeGraph: it is not committed data, it is the report that stops a guessed edge from
+ * passing for a derived one. Executors print it.
+ */
+class RuntimeGraphReport {
+    graph;
+    warnings;
+    problems;
+    constructor(graph, 
+    /** Human-readable lines naming every call site whose target the graph could not pin down. */
+    warnings, 
+    /**
+     * Call sites that name a target the repo does not contain. Unlike a warning these FAIL the
+     * build: the contract IS served in-repo, so the name is a typo or a stale rename, and the
+     * only reason it stayed invisible is that the graph quietly fanned the edge out instead.
+     * (A call to a service outside the repo never reaches here — nothing in-repo implements its
+     * contract, so it is `unresolvedUses`.)
+     */
+    problems = []) {
+        this.graph = graph;
+        this.warnings = warnings;
+        this.problems = problems;
+    }
+}
+exports.RuntimeGraphReport = RuntimeGraphReport;
 /** Adjacency (service -> [targets]) used for leveling + cycle checks. */
 function adjacencyFromEdges(serviceNames, edges) {
     const adj = {};
@@ -61,6 +98,32 @@ function assignLevels(adjacency) {
     }
     return levels;
 }
+/**
+ * Accumulates one node's effective relations while its dependsOn closure is walked, keeping the
+ * PROVENANCE the walk would otherwise throw away: which library contributed an implements, and
+ * which api-lib owns each contract.
+ */
+class RelationSink {
+    node;
+    implementsApis = [];
+    usesApis = [];
+    implementsVia = new Map();
+    constructor(
+    /** The runtime node these relations are attributed to. */
+    node) {
+        this.node = node;
+    }
+    /** `from` is the project whose apiRelations declared this — the node itself, or a lib it embeds. */
+    addImplements(ref, from) {
+        this.implementsApis.push(ref);
+        // First contributor wins, matching dedupApiRefs' keep-the-first rule on the ref list.
+        if (from !== this.node && !this.implementsVia.has(ref.api))
+            this.implementsVia.set(ref.api, from);
+    }
+    addUses(ref) {
+        this.usesApis.push(ref);
+    }
+}
 /**
  * Derives the runtime microservice graph from architecture/dependencies.json `apiRelations`:
  * implementers × users per API, split by transport. An rpc edge is a direct call; a pubsub edge flows
@@ -73,11 +136,40 @@ function assignLevels(adjacency) {
 class RuntimeGraphDeriver {
     projects;
     hiddenProjects;
+    /** apiClassName -> the api-lib project that owns the contract (from the apiRelations key). */
+    apiOwners = new Map();
+    /** Addressable name -> the runtime node answering to it; how a targeted call resolves. */
+    nodeByServiceName = new Map();
+    warnings = [];
+    problems = [];
     constructor(projects, 
     /** Project names tagged drawOnGraph:false — kept in the JSON but flagged so the viz omits them. */
     hiddenProjects) {
         this.projects = projects;
         this.hiddenProjects = hiddenProjects;
+        // A node ALWAYS answers to its own module name, so a repo whose deployed names match its
+        // project names needs no declaration at all — and no alias can ever redirect 'ai-chat' away
+        // from the ai-chat module. Module names are therefore claimed FIRST and are unshadowable.
+        for (const name of Object.keys(projects).sort()) {
+            if (this.isNode(name))
+                this.nodeByServiceName.set(name, name);
+        }
+        // `serviceName` then adds the alias a repo needs when its deployed name is NOT its module
+        // name (helper-svr serving 'helper-portal'). Colliding with a module is a misconfiguration,
+        // not a precedence question: the alias is silently unreachable, so say so.
+        for (const name of Object.keys(projects).sort()) {
+            const declared = projects[name].serviceName;
+            if (!this.isNode(name) || declared === undefined)
+                continue;
+            const claimant = this.nodeByServiceName.get(declared);
+            if (claimant === undefined) {
+                this.nodeByServiceName.set(declared, name);
+            }
+            else if (claimant !== name) {
+                this.problems.push(`${name} declares serviceName '${declared}', but that is already the module name of ` +
+                    `${claimant} — the alias can never be reached. Rename one of them.`);
+            }
+        }
     }
     assemble() {
         const decls = this.collectDecls();
@@ -87,7 +179,13 @@ class RuntimeGraphDeriver {
         const apisObj = {};
         for (const api of Array.from(apis.keys()).sort())
             apisObj[api] = apis.get(api);
-        return { services, apis: apisObj, runtimeEdges: edgeResult.edges, unresolvedUses: edgeResult.unresolved };
+        const graph = {
+            services,
+            apis: apisObj,
+            runtimeEdges: edgeResult.edges,
+            unresolvedUses: edgeResult.unresolved,
+        };
+        return new RuntimeGraphReport(graph, this.warnings, this.problems);
     }
     /**
      * One ScanDecl per RUNTIME NODE (role:server / role:client). A node's effective
@@ -104,14 +202,14 @@ class RuntimeGraphDeriver {
         for (const name of Object.keys(this.projects).sort()) {
             if (!this.isNode(name))
                 continue;
-            const implementsApis = [];
-            const usesApis = [];
-            this.collectEffectiveRelations(name, implementsApis, usesApis, new Set([name]));
-            if (implementsApis.length > 0 || usesApis.length > 0) {
+            const sink = new RelationSink(name);
+            this.collectEffectiveRelations(name, sink, new Set([name]));
+            if (sink.implementsApis.length > 0 || sink.usesApis.length > 0) {
                 decls.push({
                     name,
-                    implementsApis: dedupApiRefs((0, api_relations_1.sortApiRefs)(implementsApis)),
-                    usesApis: dedupApiRefs((0, api_relations_1.sortApiRefs)(usesApis)),
+                    implementsApis: dedupApiRefs((0, api_relations_1.sortApiRefs)(sink.implementsApis)),
+                    usesApis: dedupApiRefs((0, api_relations_1.sortApiRefs)(sink.usesApis)),
+                    implementsVia: sink.implementsVia,
                 });
             }
         }
@@ -127,15 +225,21 @@ class RuntimeGraphDeriver {
      * (skipping other nodes, which own their own relations). `visited` guards against
      * re-walking a lib reachable by more than one path (and any cycle).
      */
-    collectEffectiveRelations(name, impl, uses, visited) {
+    collectEffectiveRelations(name, sink, visited) {
         const entry = this.projects[name];
         if (entry === undefined)
             return;
         const relations = entry.apiRelations;
         if (relations !== undefined) {
-            for (const owner of Object.keys(relations)) {
-                impl.push(...relations[owner].implements);
-                uses.push(...relations[owner].uses);
+            for (const owner of Object.keys(relations).sort()) {
+                for (const ref of relations[owner].implements) {
+                    this.apiOwners.set(ref.api, owner);
+                    sink.addImplements(ref, name);
+                }
+                for (const ref of relations[owner].uses) {
+                    this.apiOwners.set(ref.api, owner);
+                    sink.addUses(ref);
+                }
             }
         }
         for (const dep of entry.dependsOn) {
@@ -144,7 +248,7 @@ class RuntimeGraphDeriver {
             visited.add(dep);
             if (this.isNode(dep))
                 continue; // another server/client owns its own relations
-            this.collectEffectiveRelations(dep, impl, uses, visited);
+            this.collectEffectiveRelations(dep, sink, visited);
         }
     }
     /** apiClassName -> { implementedBy, usedBy, type }. */
@@ -164,9 +268,13 @@ class RuntimeGraphDeriver {
             for (const ref of decl.usesApis)
                 ensure(ref.api, ref.type).usedBy.push(decl.name);
         }
-        for (const entry of apis.values()) {
+        for (const api of apis.keys()) {
+            const entry = apis.get(api);
             entry.implementedBy.sort();
-            entry.usedBy.sort();
+            entry.usedBy = Array.from(new Set(entry.usedBy)).sort();
+            const owner = this.apiOwners.get(api);
+            if (owner !== undefined)
+                entry.owner = owner;
         }
         return apis;
     }
@@ -181,10 +289,10 @@ class RuntimeGraphDeriver {
                     unresolved.push({ service: decl.name, api: ref.api });
                     continue;
                 }
-                for (const target of implementers) {
+                for (const target of this.targetsFor(decl.name, ref, implementers)) {
                     if (target === decl.name)
                         continue;
-                    const key = `${decl.name}${target}${ref.type}`;
+                    const key = `${decl.name} ${target} ${ref.type}`;
                     if (!viaByKey.has(key))
                         viaByKey.set(key, new Set());
                     viaByKey.get(key).add(ref.api);
@@ -193,10 +301,47 @@ class RuntimeGraphDeriver {
         }
         return { edges: this.edgesFromKeys(viaByKey), unresolved: sortUnresolved(unresolved) };
     }
+    /**
+     * WHICH implementers this one `uses` reaches. A call site naming its target resolves to exactly
+     * ONE node; anything else falls back to the historical fan-out — the only safe superset — and
+     * records WHY, so a fanned-out (i.e. possibly fictional) edge can never pass for a derived one.
+     */
+    targetsFor(user, ref, implementers) {
+        const wanted = ref.targetService;
+        if (wanted === undefined)
+            return this.untargetedFanOut(user, ref, implementers);
+        const node = this.nodeByServiceName.get(wanted);
+        if (node === undefined) {
+            this.problems.push(`${user} calls "${ref.api}" at service '${wanted}', but NO module answers to that name. ` +
+                `${implementers.length} module(s) serve this contract (${implementers.join(', ')}). Either use ` +
+                `the module name, or declare metadata.webpieces.serviceName: '${wanted}' on the module that ` +
+                `serves it (and translate any environment prefix in ClientRegistry.setDeriver, not here).`);
+            return implementers;
+        }
+        if (!implementers.includes(node)) {
+            this.problems.push(`${user} calls "${ref.api}" at service '${wanted}' (module ${node}), but ${node} does NOT serve ` +
+                `that contract — ${implementers.join(', ')} do. At runtime that call has nothing to answer it.`);
+            return implementers;
+        }
+        return [node];
+    }
+    /**
+     * A use with no literal client config. One implementer is unambiguous, so it stays silent; more
+     * than one means every edge but one is fiction — exactly the failure this mechanism exists to
+     * stop — so it is reported even though the graph still (conservatively) draws them all.
+     */
+    untargetedFanOut(user, ref, implementers) {
+        if (implementers.length > 1) {
+            this.warnings.push(`${user} uses "${ref.api}" with no literal client config, and ${implementers.length} services ` +
+                `implement it (${implementers.join(', ')}) — an edge is drawn to EVERY one, so all but one ` +
+                `are fiction. Name the target: createRpcClient(${ref.api}, new ClientConfig('<serviceName>')).`);
+        }
+        return implementers;
+    }
     edgesFromKeys(viaByKey) {
         const edges = [];
         for (const key of viaByKey.keys()) {
-            const parts = key.split('');
+            const parts = key.split(' ');
             edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByKey.get(key)).sort(), type: parts[2] });
         }
         edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || (a.type ?? '').localeCompare(b.type ?? ''));
@@ -206,12 +351,18 @@ class RuntimeGraphDeriver {
         const services = {};
         for (const decl of decls) {
             const dependsOn = Array.from(new Set(edges.filter((e) => e.from === decl.name).map((e) => e.to))).sort();
-            services[decl.name] = {
+            // Keys are written in this order; an undefined value is omitted by JSON.stringify, so
+            // the committed JSON stays clean AND deterministic without conditional assembly.
+            const service = {
                 level: 0,
+                serviceName: this.projects[decl.name]?.serviceName,
                 implements: decl.implementsApis.map((r) => r.api),
-                uses: decl.usesApis.map((r) => r.api),
+                implementsVia: decl.implementsVia.size > 0 ? sortedRecord(decl.implementsVia) : undefined,
+                // One api used against two services is two refs but ONE api in this list.
+                uses: Array.from(new Set(decl.usesApis.map((r) => r.api))),
                 dependsOn,
             };
+            services[decl.name] = service;
             if (this.hiddenProjects.has(decl.name))
                 services[decl.name].drawOnGraph = false;
         }
@@ -229,26 +380,50 @@ class RuntimeGraphDeriver {
  */
 // webpieces-disable no-function-outside-class -- module entry point for the runtime graph derivation
 function deriveRuntimeGraph(projects, hiddenProjects = new Set()) {
+    return deriveRuntimeGraphReport(projects, hiddenProjects).graph;
+}
+/**
+ * The same derivation, plus the warnings it produced (every edge it had to GUESS at). Executors use
+ * this form and print the warnings; `deriveRuntimeGraph` is the convenience form for callers that
+ * only want the data. The warnings are deliberately kept OUT of runtime-dependencies.json — a graph
+ * file that records its own doubts would just get committed and stop being read.
+ */
+// webpieces-disable no-function-outside-class -- module entry point for the runtime graph derivation
+function deriveRuntimeGraphReport(projects, hiddenProjects = new Set()) {
     return new RuntimeGraphDeriver(projects, hiddenProjects).assemble();
 }
-/** Drop duplicate api refs (same api class), keeping the first — needed after a node absorbs the
- * same api from both its own relations and an embedded lib's. Input is pre-sorted, so output stays
- * deterministic. */
+/** Drop duplicate api refs, keeping the first — needed after a node absorbs the same api from both
+ * its own relations and an embedded lib's. Keyed by api AND target service: the same contract aimed
+ * at two different services is two distinct relations (two distinct edges), not a duplicate. Input
+ * is pre-sorted, so output stays deterministic. */
 // webpieces-disable no-function-outside-class -- pure list helper, matches the sibling helpers in this file
 function dedupApiRefs(refs) {
     const seen = new Set();
     const out = [];
     for (const ref of refs) {
-        if (seen.has(ref.api))
+        const key = (0, api_relations_1.apiRefKey)(ref);
+        if (seen.has(key))
             continue;
-        seen.add(ref.api);
+        seen.add(key);
         out.push(ref);
     }
     return out;
 }
+/** Sort a Map into a plain object with sorted keys, so the committed JSON is deterministic. */
+// webpieces-disable no-function-outside-class -- pure data helper, matches the sibling helpers in this file
+function sortedRecord(map) {
+    const out = {};
+    for (const key of [...map.keys()].sort())
+        out[key] = map.get(key);
+    return out;
+}
+/** Sort AND de-duplicate: one api used against two targets must not be reported unresolved twice. */
 // webpieces-disable no-function-outside-class -- pure sort helper, matches the sibling helpers in this file
 function sortUnresolved(unresolved) {
-    return [...unresolved].sort((a, b) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api));
+    const byKey = new Map();
+    for (const entry of unresolved)
+        byKey.set(`${entry.service} ${entry.api}`, entry);
+    return [...byKey.values()].sort((a, b) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api));
 }
 /** Deterministic JSON (sorted keys + arrays already sorted during assembly). */
 function formatRuntimeJson(graph) {