@webpieces/nx-webpieces-rules 0.4.700 → 0.4.702

package/src/lib/runtime-graph-levels.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.adjacencyFromEdges = adjacencyFromEdges;
+exports.applyCycleCuts = applyCycleCuts;
 exports.runtimeAdjacency = runtimeAdjacency;
 exports.assignLevels = assignLevels;
+const rules_config_1 = require("@webpieces/rules-config");
 const graph_sorter_1 = require("./graph-sorter");
-const toError_1 = require("../toError");
+const graph_cycles_1 = require("./graph-cycles");
+const cut_legacy_cycle_resolver_1 = require("./cut-legacy-cycle-resolver");
+const runtime_config_1 = require("./runtime-config");
 /**
  * LEVELS and ADJACENCY for the runtime graph — how deep each service sits, and who calls whom.
  *
@@ -16,11 +20,19 @@ const toError_1 = require("../toError");
 /**
  * Adjacency (service -> [targets]) used for leveling + cycle checks.
  *
- * PUBSUB EDGES ARE EXCLUDED. A queue is precisely the thing that decouples producer from consumer:
- * the producer returns as soon as the task is enqueued and never waits on the consumer, so a queued
- * hop is not a runtime dependency in the sense levels and cycle detection mean. Counting them would
- * make the common and correct `A → queue → A` (a service deferring its own work) an architecture
- * cycle, and would rank services by an ordering that does not constrain deploy or startup.
+ * TWO KINDS OF EDGE ARE EXCLUDED, and the second is modelled on the first:
+ *
+ * PUBSUB EDGES. A queue is precisely the thing that decouples producer from consumer: the producer
+ * returns as soon as the task is enqueued and never waits on the consumer, so a queued hop is not a
+ * runtime dependency in the sense levels and cycle detection mean. Counting them would make the
+ * common and correct `A → queue → A` (a service deferring its own work) an architecture cycle, and
+ * would rank services by an ordering that does not constrain deploy or startup.
+ *
+ * EDGES STAMPED `cutLegacyCycle`. The calling project carries a `cutLegacyCycle:<target>` nx tag
+ * (see cut-legacy-cycle-resolver.ts) ADMITTING that this hop closes a real cycle which is being
+ * tolerated as legacy debt. Unlike a queued hop the coupling is real, so the edge is still drawn —
+ * it is only kept out of leveling and cycle detection, which are the two things a cycle makes
+ * meaningless.
  */
 // webpieces-disable no-function-outside-class -- pure graph helper, matches the sibling helpers in this file
 function adjacencyFromEdges(serviceNames, edges) {
@@ -30,33 +42,120 @@ function adjacencyFromEdges(serviceNames, edges) {
     for (const edge of edges) {
         if (edge.type === 'pubsub')
             continue;
+        if (edge.cutLegacyCycle === true)
+            continue;
         if (!adj[edge.from])
             adj[edge.from] = [];
         adj[edge.from].push(edge.to);
     }
     return adj;
 }
+/**
+ * Stamp `cutLegacyCycle` on every runtime edge a project declared a cut for — the DECLARATION
+ * (`cutLegacyCycle:<targetService>` nx tags, resolved into `GraphEntry.cutLegacyCycle` and committed
+ * to dependencies.json) turned into the mark {@link adjacencyFromEdges} above reads.
+ *
+ * IT FAILS THE BUILD ON A TAG THAT CUTS NOTHING, in both directions:
+ *
+ *  - the tag names a service no runtime node answers to — a typo or a rename. Silently doing nothing
+ *    is the worst outcome available: the check would look exempted while no edge was in fact cut, or
+ *    the tag would keep reading as a live IOU after the service it named was deleted. `serviceName`
+ *    is validated against real module names for exactly this reason.
+ *  - the tag resolves, but there is no direct edge to cut. The debt is PAID — delete the tag, so
+ *    `grep -rn cutLegacyCycle` keeps enumerating only cycles still actually tolerated.
+ *
+ * Returned as problems (the deriver's `problems` list) rather than thrown, so one run names every
+ * bad tag instead of stopping at the first.
+ *
+ * @param edges       the derived runtime edges, mutated in place.
+ * @param projects    the committed project entries carrying `cutLegacyCycle`.
+ * @param nodeByServiceName addressable name -> runtime node, the SAME map that resolves a call
+ *                          target, so a tag may name a module name or a declared serviceName.
+ */
+// webpieces-disable no-function-outside-class -- pure pass over derived edges, sibling of the helpers here
+function applyCycleCuts(edges, projects, nodeByServiceName) {
+    const problems = [];
+    for (const name of Object.keys(projects).sort()) {
+        const entry = projects[name];
+        for (const target of entry.cutLegacyCycle ?? []) {
+            const node = nodeByServiceName.get(target);
+            if (node === undefined) {
+                problems.push(`${name} declares ${cut_legacy_cycle_resolver_1.CUT_LEGACY_CYCLE_TAG_PREFIX}${target}, but no runtime service ` +
+                    `answers to '${target}'. Fix the name or delete the tag — a cut that names ` +
+                    `nothing exempts nothing.`);
+                continue;
+            }
+            // A queued hop is already excluded from leveling, so it can never be part of a cycle and
+            // never needs cutting; only a direct call edge is cuttable.
+            const cut = edges.filter((e) => e.from === name && e.to === node && e.type !== 'pubsub');
+            if (cut.length === 0) {
+                problems.push(`${name} declares ${cut_legacy_cycle_resolver_1.CUT_LEGACY_CYCLE_TAG_PREFIX}${target}, but it has no direct ` +
+                    `runtime call edge to '${node}'. The debt is paid — delete the tag.`);
+                continue;
+            }
+            for (const e of cut)
+                e.cutLegacyCycle = true;
+        }
+    }
+    return problems;
+}
 /** Adjacency (service -> [targets]) from a loaded runtime graph. */
 // webpieces-disable no-function-outside-class -- pure graph helper, sibling of the one above
 function runtimeAdjacency(graph) {
     return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);
 }
-/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */
+/** The cures for a cyclic runtime graph, honest ones first and the IOU last. */
+// webpieces-disable no-function-outside-class -- cure list for the throw below, sibling of the helpers in this file
+function cycleCures() {
+    return [
+        new rules_config_1.Option('Retag a node that is not really a deployed service. A project tagged `role:server` in ' +
+            'its project.json that is in fact a library should carry `role:lib` instead, which ' +
+            'takes it out of the runtime graph entirely and removes every edge through it.', true),
+        new rules_config_1.Option('Make the hop asynchronous. A contract marked `@PubSub()` is delivered through a Cloud ' +
+            'Tasks queue, and queued edges are excluded from leveling and cycle detection ' +
+            'because the producer returns without waiting on the consumer.'),
+        new rules_config_1.Option('Extract the shared contract into a `role:api-lib` project that both sides depend on, ' +
+            'so the call runs in one direction only.'),
+        new rules_config_1.Option('Last resort — admit the debt. Add `' +
+            cut_legacy_cycle_resolver_1.CUT_LEGACY_CYCLE_TAG_PREFIX +
+            '<targetService>` to the CALLING project\'s project.json tags, naming the service on ' +
+            'the other end of the one edge you are cutting. This does NOT say the edge is ' +
+            'harmless; it records that the cycle is real and is being tolerated as legacy debt. ' +
+            'The edge stays on the drawing as a dashed "legacy cycle" arrow, and ' +
+            '`grep -rn cutLegacyCycle` enumerates every one still outstanding.'),
+    ];
+}
+/**
+ * Assign levels via topological sort — and THROW on a cycle rather than levelling one.
+ *
+ * This used to swallow the cycle and flatten EVERY service to level 0, which was the worst available
+ * outcome twice over: one bad edge anywhere silently restratified the whole graph, and the reason
+ * was discarded, so the diagram rendered as one legitimate-looking flat row.
+ *
+ * Cycles are not allowed. CD deploys services in dependency order, and a cyclic architecture has no
+ * such order — whichever member rolls out first is calling one that is not up yet — so the graph is
+ * not deployable and its level numbers mean nothing.
+ *
+ * Detection is {@link ProjectCycleDetector}, the ONE cycle detector in this package (it guards the
+ * compile-time project graph too); only the audience and the cures differ, so only the message is
+ * written here.
+ */
 // webpieces-disable no-function-outside-class -- pure graph helper, sibling of the two above
 function assignLevels(adjacency) {
-    const levels = {};
-    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-    try {
-        const sorted = (0, graph_sorter_1.sortGraphTopologically)(adjacency);
-        for (const name of Object.keys(sorted))
-            levels[name] = sorted[name].level;
-    }
-    catch (err) {
-        const error = (0, toError_1.toError)(err);
-        void error;
-        for (const name of Object.keys(adjacency))
-            levels[name] = 0;
+    const cycles = new graph_cycles_1.ProjectCycleDetector().find(adjacency);
+    if (cycles.length > 0) {
+        const listed = cycles.map((cycle) => `  ${cycle.describe()}`).join('\n');
+        const plural = cycles.length === 1 ? 'cycle' : 'cycles';
+        throw new rules_config_1.RuleFailError(runtime_config_1.RUNTIME_RULE_NAME, `The runtime service graph contains ${cycles.length} ${plural}:\n${listed}\n` +
+            'CD deploys services in dependency order and a cycle has no such order — whichever ' +
+            'service in the chain rolls out first calls one that is not up yet — so an ' +
+            'architecture with cycles cannot be deployed and its level numbers are meaningless. ' +
+            'Cut every chain above.', undefined, undefined, cycleCures());
     }
+    const levels = {};
+    const sorted = (0, graph_sorter_1.sortGraphTopologically)(adjacency);
+    for (const name of Object.keys(sorted))
+        levels[name] = sorted[name].level;
     return levels;
 }
 //# sourceMappingURL=runtime-graph-levels.js.map

package/src/lib/runtime-graph-levels.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-graph-levels.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-levels.ts"],"names":[],"mappings":";;AAsBA,gDAYC;AAID,4CAEC;AAID,oCAYC;AAxDD,iDAAwD;AACxD,wCAAqC;AAGrC;;;;;;;GAOG;AACH;;;;;;;;GAQG;AACH,6GAA6G;AAC7G,SAAgB,kBAAkB,CAC9B,YAAsB,EACtB,KAAoB;IAEpB,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,YAAY;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACrC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,6FAA6F;AAC7F,SAAgB,gBAAgB,CAAC,KAAmB;IAChD,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;AAC/E,CAAC;AAED,qFAAqF;AACrF,6FAA6F;AAC7F,SAAgB,YAAY,CAAC,SAAmC;IAC5D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,IAAA,qCAAsB,EAAC,SAAS,CAAC,CAAC;QACjD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;IAC9E,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["import { sortGraphTopologically } from './graph-sorter';\nimport { toError } from '../toError';\nimport type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';\n\n/**\n * LEVELS and ADJACENCY for the runtime graph — how deep each service sits, and who calls whom.\n *\n * Its own module rather than a block inside runtime-graph.ts: that file owns DERIVATION (turning\n * apiRelations into services, apis, edges, queues and triggers), and this is a pure graph\n * computation over the result, with no knowledge of contracts at all. Splitting it also keeps\n * runtime-graph.ts under the file-size limit, which is the visible symptom of the same thing.\n */\n/**\n * Adjacency (service -> [targets]) used for leveling + cycle checks.\n *\n * PUBSUB EDGES ARE EXCLUDED. A queue is precisely the thing that decouples producer from consumer:\n * the producer returns as soon as the task is enqueued and never waits on the consumer, so a queued\n * hop is not a runtime dependency in the sense levels and cycle detection mean. Counting them would\n * make the common and correct `A → queue → A` (a service deferring its own work) an architecture\n * cycle, and would rank services by an ordering that does not constrain deploy or startup.\n */\n// webpieces-disable no-function-outside-class -- pure graph helper, matches the sibling helpers in this file\nexport function adjacencyFromEdges(\n    serviceNames: string[],\n    edges: RuntimeEdge[],\n): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (edge.type === 'pubsub') continue;\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\n// webpieces-disable no-function-outside-class -- pure graph helper, sibling of the one above\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\n// webpieces-disable no-function-outside-class -- pure graph helper, sibling of the two above\nexport function assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n"]}
+{"version":3,"file":"runtime-graph-levels.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-levels.ts"],"names":[],"mappings":";;AAkCA,gDAaC;AAyBD,wCAkCC;AAID,4CAEC;AAiDD,oCAqBC;AAtLD,0DAAgE;AAChE,iDAAwD;AAExD,iDAAoE;AACpE,2EAA0E;AAC1E,qDAAqD;AAGrD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,6GAA6G;AAC7G,SAAgB,kBAAkB,CAC9B,YAAsB,EACtB,KAAoB;IAEpB,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,YAAY;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACrC,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI;YAAE,SAAS;QAC3C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,2GAA2G;AAC3G,SAAgB,cAAc,CAC1B,KAAoB,EACpB,QAAuB,EACvB,iBAAsC;IAEtC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAe,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACrB,QAAQ,CAAC,IAAI,CACT,GAAG,IAAI,aAAa,uDAA2B,GAAG,MAAM,2BAA2B;oBAC/E,eAAe,MAAM,uDAAuD;oBAC5E,0BAA0B,CACjC,CAAC;gBACF,SAAS;YACb,CAAC;YACD,yFAAyF;YACzF,4DAA4D;YAC5D,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CACpB,CAAC,CAAc,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,CAC9E,CAAC;YACF,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACnB,QAAQ,CAAC,IAAI,CACT,GAAG,IAAI,aAAa,uDAA2B,GAAG,MAAM,yBAAyB;oBAC7E,yBAAyB,IAAI,uCAAuC,CAC3E,CAAC;gBACF,SAAS;YACb,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,GAAG;gBAAE,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC;QACjD,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,oEAAoE;AACpE,6FAA6F;AAC7F,SAAgB,gBAAgB,CAAC,KAAmB;IAChD,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;AAC/E,CAAC;AAED,gFAAgF;AAChF,oHAAoH;AACpH,SAAS,UAAU;IACf,OAAO;QACH,IAAI,qBAAM,CACN,wFAAwF;YACpF,oFAAoF;YACpF,+EAA+E,EACnF,IAAI,CACP;QACD,IAAI,qBAAM,CACN,wFAAwF;YACpF,+EAA+E;YAC/E,+DAA+D,CACtE;QACD,IAAI,qBAAM,CACN,uFAAuF;YACnF,yCAAyC,CAChD;QACD,IAAI,qBAAM,CACN,qCAAqC;YACjC,uDAA2B;YAC3B,sFAAsF;YACtF,+EAA+E;YAC/E,qFAAqF;YACrF,sEAAsE;YACtE,mEAAmE,CAC1E;KACJ,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,6FAA6F;AAC7F,SAAgB,YAAY,CAAC,SAAmC;IAC5D,MAAM,MAAM,GAAG,IAAI,mCAAoB,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAmB,EAAU,EAAE,CAAC,KAAK,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/F,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;QACxD,MAAM,IAAI,4BAAa,CACnB,kCAAiB,EACjB,sCAAsC,MAAM,CAAC,MAAM,IAAI,MAAM,MAAM,MAAM,IAAI;YACzE,oFAAoF;YACpF,4EAA4E;YAC5E,qFAAqF;YACrF,wBAAwB,EAC5B,SAAS,EACT,SAAS,EACT,UAAU,EAAE,CACf,CAAC;IACN,CAAC;IACD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAA,qCAAsB,EAAC,SAAS,CAAC,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;IAC1E,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["import { RuleFailError, Option } from '@webpieces/rules-config';\nimport { sortGraphTopologically } from './graph-sorter';\nimport type { GraphEntry, EnhancedGraph } from './graph-sorter';\nimport { ProjectCycleDetector, ProjectCycle } from './graph-cycles';\nimport { CUT_LEGACY_CYCLE_TAG_PREFIX } from './cut-legacy-cycle-resolver';\nimport { RUNTIME_RULE_NAME } from './runtime-config';\nimport type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';\n\n/**\n * LEVELS and ADJACENCY for the runtime graph — how deep each service sits, and who calls whom.\n *\n * Its own module rather than a block inside runtime-graph.ts: that file owns DERIVATION (turning\n * apiRelations into services, apis, edges, queues and triggers), and this is a pure graph\n * computation over the result, with no knowledge of contracts at all. Splitting it also keeps\n * runtime-graph.ts under the file-size limit, which is the visible symptom of the same thing.\n */\n/**\n * Adjacency (service -> [targets]) used for leveling + cycle checks.\n *\n * TWO KINDS OF EDGE ARE EXCLUDED, and the second is modelled on the first:\n *\n * PUBSUB EDGES. A queue is precisely the thing that decouples producer from consumer: the producer\n * returns as soon as the task is enqueued and never waits on the consumer, so a queued hop is not a\n * runtime dependency in the sense levels and cycle detection mean. Counting them would make the\n * common and correct `A → queue → A` (a service deferring its own work) an architecture cycle, and\n * would rank services by an ordering that does not constrain deploy or startup.\n *\n * EDGES STAMPED `cutLegacyCycle`. The calling project carries a `cutLegacyCycle:<target>` nx tag\n * (see cut-legacy-cycle-resolver.ts) ADMITTING that this hop closes a real cycle which is being\n * tolerated as legacy debt. Unlike a queued hop the coupling is real, so the edge is still drawn —\n * it is only kept out of leveling and cycle detection, which are the two things a cycle makes\n * meaningless.\n */\n// webpieces-disable no-function-outside-class -- pure graph helper, matches the sibling helpers in this file\nexport function adjacencyFromEdges(\n    serviceNames: string[],\n    edges: RuntimeEdge[],\n): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (edge.type === 'pubsub') continue;\n        if (edge.cutLegacyCycle === true) continue;\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/**\n * Stamp `cutLegacyCycle` on every runtime edge a project declared a cut for — the DECLARATION\n * (`cutLegacyCycle:<targetService>` nx tags, resolved into `GraphEntry.cutLegacyCycle` and committed\n * to dependencies.json) turned into the mark {@link adjacencyFromEdges} above reads.\n *\n * IT FAILS THE BUILD ON A TAG THAT CUTS NOTHING, in both directions:\n *\n *  - the tag names a service no runtime node answers to — a typo or a rename. Silently doing nothing\n *    is the worst outcome available: the check would look exempted while no edge was in fact cut, or\n *    the tag would keep reading as a live IOU after the service it named was deleted. `serviceName`\n *    is validated against real module names for exactly this reason.\n *  - the tag resolves, but there is no direct edge to cut. The debt is PAID — delete the tag, so\n *    `grep -rn cutLegacyCycle` keeps enumerating only cycles still actually tolerated.\n *\n * Returned as problems (the deriver's `problems` list) rather than thrown, so one run names every\n * bad tag instead of stopping at the first.\n *\n * @param edges       the derived runtime edges, mutated in place.\n * @param projects    the committed project entries carrying `cutLegacyCycle`.\n * @param nodeByServiceName addressable name -> runtime node, the SAME map that resolves a call\n *                          target, so a tag may name a module name or a declared serviceName.\n */\n// webpieces-disable no-function-outside-class -- pure pass over derived edges, sibling of the helpers here\nexport function applyCycleCuts(\n    edges: RuntimeEdge[],\n    projects: EnhancedGraph,\n    nodeByServiceName: Map<string, string>,\n): string[] {\n    const problems: string[] = [];\n    for (const name of Object.keys(projects).sort()) {\n        const entry: GraphEntry = projects[name];\n        for (const target of entry.cutLegacyCycle ?? []) {\n            const node = nodeByServiceName.get(target);\n            if (node === undefined) {\n                problems.push(\n                    `${name} declares ${CUT_LEGACY_CYCLE_TAG_PREFIX}${target}, but no runtime service ` +\n                        `answers to '${target}'. Fix the name or delete the tag — a cut that names ` +\n                        `nothing exempts nothing.`,\n                );\n                continue;\n            }\n            // A queued hop is already excluded from leveling, so it can never be part of a cycle and\n            // never needs cutting; only a direct call edge is cuttable.\n            const cut = edges.filter(\n                (e: RuntimeEdge) => e.from === name && e.to === node && e.type !== 'pubsub',\n            );\n            if (cut.length === 0) {\n                problems.push(\n                    `${name} declares ${CUT_LEGACY_CYCLE_TAG_PREFIX}${target}, but it has no direct ` +\n                        `runtime call edge to '${node}'. The debt is paid — delete the tag.`,\n                );\n                continue;\n            }\n            for (const e of cut) e.cutLegacyCycle = true;\n        }\n    }\n    return problems;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\n// webpieces-disable no-function-outside-class -- pure graph helper, sibling of the one above\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** The cures for a cyclic runtime graph, honest ones first and the IOU last. */\n// webpieces-disable no-function-outside-class -- cure list for the throw below, sibling of the helpers in this file\nfunction cycleCures(): Option[] {\n    return [\n        new Option(\n            'Retag a node that is not really a deployed service. A project tagged `role:server` in ' +\n                'its project.json that is in fact a library should carry `role:lib` instead, which ' +\n                'takes it out of the runtime graph entirely and removes every edge through it.',\n            true,\n        ),\n        new Option(\n            'Make the hop asynchronous. A contract marked `@PubSub()` is delivered through a Cloud ' +\n                'Tasks queue, and queued edges are excluded from leveling and cycle detection ' +\n                'because the producer returns without waiting on the consumer.',\n        ),\n        new Option(\n            'Extract the shared contract into a `role:api-lib` project that both sides depend on, ' +\n                'so the call runs in one direction only.',\n        ),\n        new Option(\n            'Last resort — admit the debt. Add `' +\n                CUT_LEGACY_CYCLE_TAG_PREFIX +\n                '<targetService>` to the CALLING project\\'s project.json tags, naming the service on ' +\n                'the other end of the one edge you are cutting. This does NOT say the edge is ' +\n                'harmless; it records that the cycle is real and is being tolerated as legacy debt. ' +\n                'The edge stays on the drawing as a dashed \"legacy cycle\" arrow, and ' +\n                '`grep -rn cutLegacyCycle` enumerates every one still outstanding.',\n        ),\n    ];\n}\n\n/**\n * Assign levels via topological sort — and THROW on a cycle rather than levelling one.\n *\n * This used to swallow the cycle and flatten EVERY service to level 0, which was the worst available\n * outcome twice over: one bad edge anywhere silently restratified the whole graph, and the reason\n * was discarded, so the diagram rendered as one legitimate-looking flat row.\n *\n * Cycles are not allowed. CD deploys services in dependency order, and a cyclic architecture has no\n * such order — whichever member rolls out first is calling one that is not up yet — so the graph is\n * not deployable and its level numbers mean nothing.\n *\n * Detection is {@link ProjectCycleDetector}, the ONE cycle detector in this package (it guards the\n * compile-time project graph too); only the audience and the cures differ, so only the message is\n * written here.\n */\n// webpieces-disable no-function-outside-class -- pure graph helper, sibling of the two above\nexport function assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const cycles = new ProjectCycleDetector().find(adjacency);\n    if (cycles.length > 0) {\n        const listed = cycles.map((cycle: ProjectCycle): string => `  ${cycle.describe()}`).join('\\n');\n        const plural = cycles.length === 1 ? 'cycle' : 'cycles';\n        throw new RuleFailError(\n            RUNTIME_RULE_NAME,\n            `The runtime service graph contains ${cycles.length} ${plural}:\\n${listed}\\n` +\n                'CD deploys services in dependency order and a cycle has no such order — whichever ' +\n                'service in the chain rolls out first calls one that is not up yet — so an ' +\n                'architecture with cycles cannot be deployed and its level numbers are meaningless. ' +\n                'Cut every chain above.',\n            undefined,\n            undefined,\n            cycleCures(),\n        );\n    }\n    const levels: Record<string, number> = {};\n    const sorted = sortGraphTopologically(adjacency);\n    for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    return levels;\n}\n"]}

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

@@ -21,7 +21,7 @@ export interface RuntimeService {
      */
     role?: string;
     /**
-     * The name clients address this service by (`new ClientConfig('helper-fsdb', new DeployedServiceHost())`), declared in its
+     * 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;
@@ -86,6 +86,13 @@ export interface RuntimeEdge {
      * queues rather than one arrow.
      */
     queue?: string;
+    /**
+     * True when the CALLING project carries a `cutLegacyCycle:<target>` nx tag naming this edge's
+     * target — an admission that this hop closes a REAL cycle that is being tolerated as legacy
+     * debt, not a claim that it is harmless. The edge is still drawn (dashed, labelled "legacy
+     * cycle"); it is only excluded from leveling and cycle detection. Absent on every other edge.
+     */
+    cutLegacyCycle?: boolean;
 }
 /**
  * One Cloud Tasks queue: the async seam between a producer and a consumer, at METHOD granularity.

package/src/lib/runtime-graph-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-graph-model.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG","sourcesContent":["/**\n * Runtime Graph model\n *\n * The serialization DTOs for architecture/runtime-dependencies.json. Split out of runtime-graph.ts,\n * which owns the DERIVATION (and had grown past the file-size limit), so the committed data shape\n * can be read on its own — it is what every consumer of the file, and any future Terraform\n * cross-check, actually programs against.\n *\n * Interfaces rather than classes: these are parsed straight out of JSON with `JSON.parse`, so a\n * class would only ever be a shape assertion over a plain object, never a constructed instance.\n */\n\nimport type { ApiTransport, ExternalSystemDeclaration, ExternalSystemKind } from './api-usage/api-relations';\n\nexport interface RuntimeService {\n    level: number;\n    /**\n     * The project's declared nx role — 'server' or 'client' (a library is never a node). Carried so\n     * the viz can LABEL the node with what it actually is: it used to infer the role from\n     * `implements.length > 0`, which labelled every relation-less server \"client\". Optional so a\n     * runtime-dependencies.json written before this field existed still parses and still renders\n     * exactly as it did (the visualizer falls back to the old inference).\n     */\n    role?: string;\n    /**\n     * The name clients address this service by (`new ClientConfig('helper-fsdb', new DeployedServiceHost())`), declared in its\n     * project.json. Absent for a service nothing calls by name (e.g. a browser app).\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this node's clients call when the call site carries no literal `ClientConfig`,\n     * declared in its project.json (metadata.webpieces.callsService). A single name, or an\n     * `{ apiClassName: serviceName }` map. Absent when the node declares no target. Mirrors\n     * GraphEntry.callsService; it is the CALLING-side counterpart of `serviceName`.\n     */\n    callsService?: string | Record<string, string>;\n    implements: string[];\n    /**\n     * apiClassName -> the LIBRARY project whose apiRelations declared that implements, for the apis\n     * this service serves through an embedded library rather than its own source (e.g. a shared\n     * route-registration lib). Answers \"who implements WarmupApi, and where did that come from?\",\n     * which previously required walking the dependsOn closure by hand.\n     */\n    implementsVia?: Record<string, string>;\n    uses: string[];\n    dependsOn: string[];\n    /**\n     * When false, this service is hidden from the rendered runtime graph (its\n     * node AND every edge touching it are omitted from the HTML/DOT). It stays\n     * in runtime-dependencies.json so the data view is complete. Absent means\n     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`\n     * nx tag.\n     */\n    drawOnGraph?: boolean;\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n    /**\n     * The api-lib project that OWNS this contract. For a contract nothing in-repo implements, this\n     * is the external library the calls leave the repo through (`lib-firestore`, `lib-gmail`), which\n     * is what the runtime viz labels its terminal external nodes with.\n     */\n    owner?: string;\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — the vendor seam\n     * declaring WHAT it is a seam to, so the viz can draw firestore as a database rather than as the\n     * same grey box as every other external. Absent on everything else.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n    /**\n     * `\"ApiClassName.methodName\"` — the queue this edge flows through. Present iff `type` is\n     * 'pubsub'. Queues are per METHOD, not per service pair, because that is the unit Cloud Tasks\n     * (and Terraform) actually create, so two services exchanging three queued methods are three\n     * queues rather than one arrow.\n     */\n    queue?: string;\n}\n\n/**\n * One Cloud Tasks queue: the async seam between a producer and a consumer, at METHOD granularity.\n *\n * `producedBy` and `consumedBy` are deliberately not symmetric in confidence — see\n * {@link ApiRef.methodsInferred}. The consumer is derived from `addRoutes` plus the contract's\n * method table and is exact; the producer is attributed to every queued method of the contract it\n * built a client for, because which methods it enqueues is not statically recoverable.\n */\nexport interface RuntimeQueue {\n    api: string;\n    method: string;\n    /** `@Queue(...)` override, else `${Api}-${method}` — the name Terraform must match 1:1. */\n    queueName: string;\n    producedBy: string[];\n    consumedBy: string[];\n}\n\n/**\n * An endpoint driven by something that is NOT an in-repo caller — a clock or an outside system.\n * These never appear as runtime EDGES (there is no in-repo `from`), which is exactly why they were\n * invisible until now: a nightly sweep and a GCP push subscription are real runtime entry points\n * with real Terraform behind them, and the graph showed neither.\n */\nexport interface RuntimeTrigger {\n    /** 'cron' → a scheduler fires it; 'external' → a system outside this repo posts to it. */\n    kind: 'cron' | 'external';\n    api: string;\n    method: string;\n    /** The service that SERVES the endpoint (the arrow's head). */\n    service: string;\n    /** Present for 'cron': the Cloud Scheduler job / queue name Terraform must match. */\n    queueName?: string;\n    /**\n     * Present for 'external': WHO outside this repo posts to it, declared as\n     * `@Endpoint(p, 'external', { calledBy: 'twilio' })`.\n     *\n     * The SAME `(kind,label)` an OUTBOUND {@link RuntimeExternalSystem} carries, so an inbound\n     * `saas twilio` and an outbound `saas twilio` share a node identity and converge on ONE box —\n     * `label` is the identity here too, not display text.\n     *\n     * Optional only for graphs generated BEFORE the caller was required; generation now fails rather\n     * than emitting an `external` method without one.\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\n/**\n * A system outside this repo that a service TALKS TO, drawn with a shape that says what it is\n * (a database as a cylinder, a bucket as a folder) instead of the one grey box every external\n * used to collapse into.\n *\n * Two declaration sites feed this, because the two real cases differ in whether a contract exists:\n *\n * - **Wrapped** — the repo has a vendor seam (`FirestoreAdminApi`), so the kind is declared with an\n *   `@externalSystem <kind> [label]` JSDoc tag on the contract. A decorator cannot go on a TS\n *   `interface`, and these seams are interfaces, so JSDoc is the only marker that fits in place.\n * - **Unwrapped** — the service opens the connection itself with no contract to mark (a `pg.Pool`,\n *   a TypeORM `DataSource`), so the declaration is an `external:<kind>:<identity>` nx tag on that\n *   project's project.json.\n *\n * `label` is the node IDENTITY, not just display text: two services declaring `postgres` converge on\n * ONE node with two arrows into it, rather than drawing a database each.\n */\nexport interface RuntimeExternalSystem {\n    kind: ExternalSystemKind;\n    /** Display name AND node identity — declarations sharing a label share a node. */\n    label: string;\n    /** Services with a direct arrow to it. No transitive fan-out: a tag speaks only for its project. */\n    usedBy: string[];\n    /** Contracts flowing over it. Empty for the unwrapped (tag-declared) case — there are none. */\n    apis: string[];\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n    /** `\"Api.method\"` -> the queue between its producers and its consumers. */\n    queues: Record<string, RuntimeQueue>;\n    /** Clock- and outside-driven entry points, sorted for determinism. */\n    triggers: RuntimeTrigger[];\n    /**\n     * Declared external systems, keyed by identity. Optional so every graph written before this\n     * existed still parses — an absent map means \"nothing declared\", which renders exactly as before.\n     */\n    externalSystems?: Record<string, RuntimeExternalSystem>;\n}\n"]}
+{"version":3,"file":"runtime-graph-model.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG","sourcesContent":["/**\n * Runtime Graph model\n *\n * The serialization DTOs for architecture/runtime-dependencies.json. Split out of runtime-graph.ts,\n * which owns the DERIVATION (and had grown past the file-size limit), so the committed data shape\n * can be read on its own — it is what every consumer of the file, and any future Terraform\n * cross-check, actually programs against.\n *\n * Interfaces rather than classes: these are parsed straight out of JSON with `JSON.parse`, so a\n * class would only ever be a shape assertion over a plain object, never a constructed instance.\n */\n\nimport type { ApiTransport, ExternalSystemDeclaration, ExternalSystemKind } from './api-usage/api-relations';\n\nexport interface RuntimeService {\n    level: number;\n    /**\n     * The project's declared nx role — 'server' or 'client' (a library is never a node). Carried so\n     * the viz can LABEL the node with what it actually is: it used to infer the role from\n     * `implements.length > 0`, which labelled every relation-less server \"client\". Optional so a\n     * runtime-dependencies.json written before this field existed still parses and still renders\n     * exactly as it did (the visualizer falls back to the old inference).\n     */\n    role?: string;\n    /**\n     * The name clients address this service by (`new ClientConfig('helper-fsdb')`), declared in its\n     * project.json. Absent for a service nothing calls by name (e.g. a browser app).\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this node's clients call when the call site carries no literal `ClientConfig`,\n     * declared in its project.json (metadata.webpieces.callsService). A single name, or an\n     * `{ apiClassName: serviceName }` map. Absent when the node declares no target. Mirrors\n     * GraphEntry.callsService; it is the CALLING-side counterpart of `serviceName`.\n     */\n    callsService?: string | Record<string, string>;\n    implements: string[];\n    /**\n     * apiClassName -> the LIBRARY project whose apiRelations declared that implements, for the apis\n     * this service serves through an embedded library rather than its own source (e.g. a shared\n     * route-registration lib). Answers \"who implements WarmupApi, and where did that come from?\",\n     * which previously required walking the dependsOn closure by hand.\n     */\n    implementsVia?: Record<string, string>;\n    uses: string[];\n    dependsOn: string[];\n    /**\n     * When false, this service is hidden from the rendered runtime graph (its\n     * node AND every edge touching it are omitted from the HTML/DOT). It stays\n     * in runtime-dependencies.json so the data view is complete. Absent means\n     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`\n     * nx tag.\n     */\n    drawOnGraph?: boolean;\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n    /**\n     * The api-lib project that OWNS this contract. For a contract nothing in-repo implements, this\n     * is the external library the calls leave the repo through (`lib-firestore`, `lib-gmail`), which\n     * is what the runtime viz labels its terminal external nodes with.\n     */\n    owner?: string;\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — the vendor seam\n     * declaring WHAT it is a seam to, so the viz can draw firestore as a database rather than as the\n     * same grey box as every other external. Absent on everything else.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n    /**\n     * `\"ApiClassName.methodName\"` — the queue this edge flows through. Present iff `type` is\n     * 'pubsub'. Queues are per METHOD, not per service pair, because that is the unit Cloud Tasks\n     * (and Terraform) actually create, so two services exchanging three queued methods are three\n     * queues rather than one arrow.\n     */\n    queue?: string;\n    /**\n     * True when the CALLING project carries a `cutLegacyCycle:<target>` nx tag naming this edge's\n     * target — an admission that this hop closes a REAL cycle that is being tolerated as legacy\n     * debt, not a claim that it is harmless. The edge is still drawn (dashed, labelled \"legacy\n     * cycle\"); it is only excluded from leveling and cycle detection. Absent on every other edge.\n     */\n    cutLegacyCycle?: boolean;\n}\n\n/**\n * One Cloud Tasks queue: the async seam between a producer and a consumer, at METHOD granularity.\n *\n * `producedBy` and `consumedBy` are deliberately not symmetric in confidence — see\n * {@link ApiRef.methodsInferred}. The consumer is derived from `addRoutes` plus the contract's\n * method table and is exact; the producer is attributed to every queued method of the contract it\n * built a client for, because which methods it enqueues is not statically recoverable.\n */\nexport interface RuntimeQueue {\n    api: string;\n    method: string;\n    /** `@Queue(...)` override, else `${Api}-${method}` — the name Terraform must match 1:1. */\n    queueName: string;\n    producedBy: string[];\n    consumedBy: string[];\n}\n\n/**\n * An endpoint driven by something that is NOT an in-repo caller — a clock or an outside system.\n * These never appear as runtime EDGES (there is no in-repo `from`), which is exactly why they were\n * invisible until now: a nightly sweep and a GCP push subscription are real runtime entry points\n * with real Terraform behind them, and the graph showed neither.\n */\nexport interface RuntimeTrigger {\n    /** 'cron' → a scheduler fires it; 'external' → a system outside this repo posts to it. */\n    kind: 'cron' | 'external';\n    api: string;\n    method: string;\n    /** The service that SERVES the endpoint (the arrow's head). */\n    service: string;\n    /** Present for 'cron': the Cloud Scheduler job / queue name Terraform must match. */\n    queueName?: string;\n    /**\n     * Present for 'external': WHO outside this repo posts to it, declared as\n     * `@Endpoint(p, 'external', { calledBy: 'twilio' })`.\n     *\n     * The SAME `(kind,label)` an OUTBOUND {@link RuntimeExternalSystem} carries, so an inbound\n     * `saas twilio` and an outbound `saas twilio` share a node identity and converge on ONE box —\n     * `label` is the identity here too, not display text.\n     *\n     * Optional only for graphs generated BEFORE the caller was required; generation now fails rather\n     * than emitting an `external` method without one.\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\n/**\n * A system outside this repo that a service TALKS TO, drawn with a shape that says what it is\n * (a database as a cylinder, a bucket as a folder) instead of the one grey box every external\n * used to collapse into.\n *\n * Two declaration sites feed this, because the two real cases differ in whether a contract exists:\n *\n * - **Wrapped** — the repo has a vendor seam (`FirestoreAdminApi`), so the kind is declared with an\n *   `@externalSystem <kind> [label]` JSDoc tag on the contract. A decorator cannot go on a TS\n *   `interface`, and these seams are interfaces, so JSDoc is the only marker that fits in place.\n * - **Unwrapped** — the service opens the connection itself with no contract to mark (a `pg.Pool`,\n *   a TypeORM `DataSource`), so the declaration is an `external:<kind>:<identity>` nx tag on that\n *   project's project.json.\n *\n * `label` is the node IDENTITY, not just display text: two services declaring `postgres` converge on\n * ONE node with two arrows into it, rather than drawing a database each.\n */\nexport interface RuntimeExternalSystem {\n    kind: ExternalSystemKind;\n    /** Display name AND node identity — declarations sharing a label share a node. */\n    label: string;\n    /** Services with a direct arrow to it. No transitive fan-out: a tag speaks only for its project. */\n    usedBy: string[];\n    /** Contracts flowing over it. Empty for the unwrapped (tag-declared) case — there are none. */\n    apis: string[];\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n    /** `\"Api.method\"` -> the queue between its producers and its consumers. */\n    queues: Record<string, RuntimeQueue>;\n    /** Clock- and outside-driven entry points, sorted for determinism. */\n    triggers: RuntimeTrigger[];\n    /**\n     * Declared external systems, keyed by identity. Optional so every graph written before this\n     * existed still parses — an absent map means \"nothing declared\", which renders exactly as before.\n     */\n    externalSystems?: Record<string, RuntimeExternalSystem>;\n}\n"]}

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

@@ -14,7 +14,7 @@
  *
  * WHICH X is decided by the call site, not by "everyone who implements Y", in
  * priority order: (1) a literal at the call site —
- * `createRpcClient(Y, new ClientConfig('helper-fsdb', new DeployedServiceHost()))` — kept as
+ * `createRpcClient(Y, new ClientConfig('helper-fsdb'))` — kept as
  * `ApiRef.targetService`; else (2) the calling project's declared `callsService`
  * (project.json metadata.webpieces.callsService), the symmetric half of
  * `serviceName` for the shared-library case where the client is built once from a

package/src/lib/runtime-graph.js

@@ -15,7 +15,7 @@
  *
  * WHICH X is decided by the call site, not by "everyone who implements Y", in
  * priority order: (1) a literal at the call site —
- * `createRpcClient(Y, new ClientConfig('helper-fsdb', new DeployedServiceHost()))` — kept as
+ * `createRpcClient(Y, new ClientConfig('helper-fsdb'))` — kept as
  * `ApiRef.targetService`; else (2) the calling project's declared `callsService`
  * (project.json metadata.webpieces.callsService), the symmetric half of
  * `serviceName` for the shared-library case where the client is built once from a
@@ -37,7 +37,6 @@ const runtime_graph_decls_1 = require("./runtime-graph-decls");
 const runtime_graph_sorters_1 = require("./runtime-graph-sorters");
 const external_systems_1 = require("./api-usage/external-systems");
 const runtime_graph_levels_1 = require("./runtime-graph-levels");
-const runtime_host_nodes_1 = require("./runtime-host-nodes");
 // Persistence lives in runtime-graph-io.ts; re-exported for the same reason as the model types.
 var runtime_graph_io_1 = require("./runtime-graph-io");
 Object.defineProperty(exports, "DEFAULT_RUNTIME_GRAPH_PATH", { enumerable: true, get: function () { return runtime_graph_io_1.DEFAULT_RUNTIME_GRAPH_PATH; } });
@@ -104,13 +103,6 @@ class RuntimeGraphDeriver {
     problems = [];
     /** role:server nodes hidden by isNonParticipantServer, in the order buildServices met them. */
     autoHidden = [];
-    /**
-     * identity -> the services that dial it and the contracts they dial it with, for every client
-     * whose base URL arrives at RUNTIME. Accumulated while edges are built, then merged into the
-     * graph's `externalSystems` in {@link assemble} so a partner destination is drawn as the
-     * external node it is instead of vanishing between fan-out and `unresolvedUses`.
-     */
-    runtimeHosts = new Map();
     /**
      * False when NO project in the graph carries `webpiecesRuntime`, i.e. the file was written
      * before the field existed. Auto-hiding is then off ENTIRELY, so an old dependencies.json
@@ -166,6 +158,8 @@ class RuntimeGraphDeriver {
         const decls = this.collectDecls();
         const apis = this.buildApis(decls);
         const edgeResult = this.buildEdges(decls, apis);
+        // Cuts are stamped BEFORE buildServices, which is where leveling reads the edges.
+        this.problems.push(...(0, runtime_graph_levels_1.applyCycleCuts)(edgeResult.edges, this.projects, this.nodeByServiceName));
         const services = this.buildServices(decls, edgeResult.edges);
         const apisObj = {};
         for (const api of Array.from(apis.keys()).sort())
@@ -178,19 +172,11 @@ class RuntimeGraphDeriver {
             queues: edgeResult.queues,
             triggers: this.buildTriggers(decls),
         };
+        // A destination whose address arrives at RUNTIME is declared on its CONTRACT
+        // (`@externalSystem runtime partner-webhooks`), so it needs no branch of its own here: it is
+        // resolved by the same call every other declared system is, converges on one node when two
+        // services deliver over the same contract, and is watched by the same drift check.
         const systems = (0, external_systems_1.resolveExternalSystems)(this.externalSystemDecls, services);
-        // Runtime destinations join the SAME table the declared vendor systems live in, so two
-        // clients naming one identity converge on one node exactly as two `@externalSystem twilio`
-        // contracts do, and the drift check that already watches `externalSystems` watches these too.
-        for (const identity of Array.from(this.runtimeHosts.keys()).sort()) {
-            const usage = this.runtimeHosts.get(identity);
-            systems[identity] = {
-                kind: 'runtime',
-                label: identity,
-                usedBy: [...usage.usedBy].sort(),
-                apis: [...usage.apis].sort(),
-            };
-        }
         (0, external_systems_1.attachExternalSystems)(graph, systems);
         return new RuntimeGraphReport(graph, this.warnings, this.problems, [...this.autoHidden].sort());
     }
@@ -365,13 +351,6 @@ class RuntimeGraphDeriver {
         const queues = new Map();
         for (const decl of decls) {
             for (const ref of decl.usesApis) {
-                // A destination supplied at runtime is neither an in-repo implementer nor a missing
-                // one, so BOTH of the branches below would misreport it — fan-out invents edges to
-                // services we never call, `unresolvedUses` reads as a gap. It gets its own node.
-                if (ref.runtimeHost !== undefined) {
-                    this.recordRuntimeHost(decl.name, ref.runtimeHost, ref.api);
-                    continue;
-                }
                 const implementers = apis.get(ref.api)?.implementedBy ?? [];
                 if (implementers.length === 0) {
                     // Nobody in-repo serves it. For a vendor contract that is the ANSWER, not a gap:
@@ -446,16 +425,6 @@ class RuntimeGraphDeriver {
                 queue.consumedBy.push(to);
         }
     }
-    /** Remember that `user` dials the runtime destination `identity` through contract `api`. */
-    recordRuntimeHost(user, identity, api) {
-        let usage = this.runtimeHosts.get(identity);
-        if (usage === undefined) {
-            usage = new runtime_host_nodes_1.RuntimeHostUsage();
-            this.runtimeHosts.set(identity, usage);
-        }
-        usage.usedBy.add(user);
-        usage.apis.add(api);
-    }
     /**
      * WHICH implementers this one `uses` reaches. Resolution order (most specific wins):
      *   1. a literal `ClientConfig` at the call site (`ref.targetService`) — names ONE node;
@@ -525,7 +494,7 @@ class RuntimeGraphDeriver {
         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>', new DeployedServiceHost())); ` +
+                `are fiction. Name the target: createRpcClient(${ref.api}, new ClientConfig('<serviceName>')); ` +
                 `or, when the client is built in a shared library (no literal can sit at the call site), ` +
                 `declare metadata.webpieces.callsService: '<serviceName>' on ${user}'s project.json.`);
         }
@@ -614,8 +583,8 @@ function deriveRuntimeGraph(projects, hiddenProjects = new Set(), apiContracts =
 function deriveRuntimeGraphReport(projects, hiddenProjects = new Set(), apiContracts = {}, externalSystems = {}) {
     return new RuntimeGraphDeriver(projects, hiddenProjects, apiContracts, externalSystems).assemble();
 }
-// Levels + adjacency live in runtime-graph-levels.ts; re-exported for the same reason the model
-// types and the io helpers above are — one obvious place to import the runtime graph from.
+// Levels + adjacency live in runtime-graph-levels.ts; re-exported for the same reason the model types
+// and the io helpers above are — one obvious place to import the runtime graph from.
 var runtime_graph_levels_2 = require("./runtime-graph-levels");
 Object.defineProperty(exports, "runtimeAdjacency", { enumerable: true, get: function () { return runtime_graph_levels_2.runtimeAdjacency; } });
 //# sourceMappingURL=runtime-graph.js.map