@webpieces/nx-webpieces-rules 0.4.908 → 0.4.910

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

@@ -2,7 +2,6 @@
 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");
@@ -17,23 +16,7 @@ const runtime_config_1 = require("./runtime-config");
  * computation over the result, with no knowledge of contracts at all. Splitting it also keeps
  * runtime-graph.ts under the file-size limit, which is the visible symptom of the same thing.
  */
-/**
- * Adjacency (service -> [targets]) used for leveling + cycle checks.
- *
- * 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.
- */
+/** RPC adjacency for callers working with an edge list alone. Full runtime layering uses RuntimeNodeLevels. */
 // webpieces-disable no-function-outside-class -- pure graph helper, matches the sibling helpers in this file
 function adjacencyFromEdges(serviceNames, edges) {
     const adj = {};
@@ -85,8 +68,7 @@ function applyCycleCuts(edges, projects, nodeByServiceName) {
                     `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.
+            // Legacy cuts apply to direct calls only. Foreign queues remain visible to cycle detection.
             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 ` +
@@ -99,11 +81,6 @@ function applyCycleCuts(edges, projects, nodeByServiceName) {
     }
     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);
-}
 /** 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() {
@@ -111,14 +88,13 @@ function cycleCures() {
         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('Break the feedback path through the named queue or RPC hop. Foreign queues count ' +
+            'toward runtime layering; only a service enqueueing to itself is exempt.'),
         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 ' +
+            "<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 ' +
@@ -144,7 +120,9 @@ function cycleCures() {
 function assignLevels(adjacency) {
     const cycles = new graph_cycles_1.ProjectCycleDetector().find(adjacency);
     if (cycles.length > 0) {
-        const listed = cycles.map((cycle) => `  ${cycle.describe()}`).join('\n');
+        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 ' +

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":"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","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"]}
+{"version":3,"file":"runtime-graph-levels.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-levels.ts"],"names":[],"mappings":"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","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 } 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/** RPC adjacency for callers working with an edge list alone. Full runtime layering uses RuntimeNodeLevels. */\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            // Legacy cuts apply to direct calls only. Foreign queues remain visible to cycle detection.\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/** 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            'Break the feedback path through the named queue or RPC hop. Foreign queues count ' +\n                'toward runtime layering; only a service enqueueing to itself is exempt.',\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\n            .map((cycle: ProjectCycle): string => `  ${cycle.describe()}`)\n            .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

@@ -10,8 +10,11 @@
  * class would only ever be a shape assertion over a plain object, never a constructed instance.
  */
 import type { ApiRef, ApiTransport, ExternalSystemDeclaration, ExternalSystemKind } from './api-usage/api-relations';
-export interface RuntimeService {
+export declare class RuntimeLevel {
     level: number;
+    levelBecause: string;
+}
+export interface RuntimeService extends RuntimeLevel {
     /**
      * The project's declared nx role — 'server' or 'client' (a library is never a node). Carried so
      * the viz can LABEL the node with what it actually is: it used to infer the role from
@@ -110,13 +113,16 @@ export interface RuntimeEdge {
  * Only exact method declarations may populate producer facts. Contract-only client wiring
  * produces contract-level edges without a method queue, regardless of the endpoint table.
  */
-export interface RuntimeQueue {
+export declare class RuntimeQueueFlow extends RuntimeLevel {
+    selfQueue: boolean;
+    producedBy: string[];
+    consumedBy: string[];
+}
+export interface RuntimeQueue extends RuntimeQueueFlow {
     api: string;
     method: string;
     /** `@Queue(...)` override, else `${Api}-${method}` — the name Terraform must match 1:1. */
     queueName: string;
-    producedBy: string[];
-    consumedBy: string[];
 }
 /**
  * An endpoint driven by something that is NOT an in-repo caller — a clock or an outside system.
@@ -124,7 +130,7 @@ export interface RuntimeQueue {
  * invisible until now: a nightly sweep and a GCP push subscription are real runtime entry points
  * with real Terraform behind them, and the graph showed neither.
  */
-export interface RuntimeTrigger {
+export interface RuntimeTrigger extends RuntimeLevel {
     /** 'cron' → a scheduler fires it; 'external' → a system outside this repo posts to it. */
     kind: 'cron' | 'external';
     api: string;
@@ -137,16 +143,15 @@ export interface RuntimeTrigger {
      * Present for 'external': WHO outside this repo posts to it, declared as
      * `@Endpoint(POST, p, WRITE, EXTERNAL, { calledBy: 'twilio' })`.
      *
-     * The SAME `(kind,label)` an OUTBOUND {@link RuntimeExternalSystem} carries, so an inbound
-     * `saas twilio` and an outbound `saas twilio` share a node identity and converge on ONE box —
-     * `label` is the identity here too, not display text.
+     * The caller is drawn separately from an outbound system with the same label: callers
+     * start the flow on the top row, while outbound systems are sinks on L0.
      *
      * Optional only for graphs generated BEFORE the caller was required; generation now fails rather
      * than emitting an `external` method without one.
      */
     caller?: ExternalSystemDeclaration;
 }
-export interface RuntimeUnresolved {
+export interface RuntimeUnresolved extends RuntimeLevel {
     service: string;
     api: string;
 }
@@ -167,7 +172,7 @@ export interface RuntimeUnresolved {
  * `label` is the node IDENTITY, not just display text: two services declaring `postgres` converge on
  * ONE node with two arrows into it, rather than drawing a database each.
  */
-export interface RuntimeExternalSystem {
+export interface RuntimeExternalSystem extends RuntimeLevel {
     kind: ExternalSystemKind;
     /** Display name AND node identity — declarations sharing a label share a node. */
     label: string;
@@ -188,10 +193,10 @@ export interface RuntimeRemoteCall {
 /**
  * A service OUTSIDE this workspace (another repo, a VM, partner endpoints) declared in the reviewed
  * `remoteServices` table of dependencies.json (#1203). It is a SERVICE — it implements our contracts —
- * so it is drawn as a service node, distinct from a vendor external system. Render-only, like the
- * external systems: it is never leveled or cycle-checked, because its own calls are not in this repo.
+ * so it is drawn as a service node, distinct from a vendor external system. Its level is zero:
+ * outbound calls from outside this workspace are not part of this graph.
  */
-export interface RuntimeRemoteService {
+export interface RuntimeRemoteService extends RuntimeLevel {
     /** Display text from the reviewed declaration; the key is the identity. */
     label?: string;
     /** The contracts it is declared to implement, as `Api (transport)`, in reviewed order. */
@@ -200,6 +205,9 @@ export interface RuntimeRemoteService {
     calledBy: RuntimeRemoteCall[];
 }
 export interface RuntimeGraph {
+    maxLevel: number;
+    /** Contract-only pubsub flows; these do not assert any method-level producers. */
+    contractQueues: Record<string, RuntimeQueueFlow>;
     services: Record<string, RuntimeService>;
     apis: Record<string, RuntimeApi>;
     runtimeEdges: RuntimeEdge[];

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

@@ -11,4 +11,22 @@
  * class would only ever be a shape assertion over a plain object, never a constructed instance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeQueueFlow = exports.RuntimeLevel = void 0;
+class RuntimeLevel {
+    level = 0;
+    levelBecause = '';
+}
+exports.RuntimeLevel = RuntimeLevel;
+/**
+ * One Cloud Tasks queue: the async seam between a producer and a consumer, at METHOD granularity.
+ *
+ * Only exact method declarations may populate producer facts. Contract-only client wiring
+ * produces contract-level edges without a method queue, regardless of the endpoint table.
+ */
+class RuntimeQueueFlow extends RuntimeLevel {
+    selfQueue = false;
+    producedBy = [];
+    consumedBy = [];
+}
+exports.RuntimeQueueFlow = RuntimeQueueFlow;
 //# sourceMappingURL=runtime-graph-model.js.map

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 {\n    ApiRef,\n    ApiTransport,\n    ExternalSystemDeclaration,\n    ExternalSystemKind,\n} 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    /** Reviewed binding provenance and runtime conditions, retained for compact detail views. */\n    wiringUses?: ApiRef[];\n    wiringImplements?: ApiRef[];\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     * The products this service belongs to (#1179), sorted: exactly its project's declared\n     * `product:<name>` tags (#1216). Never derived from a runtime call or a queue; a call into another\n     * product's service shows as the runtime edge, not as a product. Absent for a service whose\n     * project is untagged. See graph-products.ts.\n     */\n    products?: string[];\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 * Only exact method declarations may populate producer facts. Contract-only client wiring\n * produces contract-level edges without a method queue, regardless of the endpoint table.\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(POST, p, WRITE, 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\n/**\n * One caller's calls into a {@link RuntimeRemoteService}, one entry per (caller, transport): `via`\n * lists the contracts it calls there.\n */\nexport interface RuntimeRemoteCall {\n    from: string;\n    via: string[];\n    type: ApiTransport;\n}\n\n/**\n * A service OUTSIDE this workspace (another repo, a VM, partner endpoints) declared in the reviewed\n * `remoteServices` table of dependencies.json (#1203). It is a SERVICE — it implements our contracts —\n * so it is drawn as a service node, distinct from a vendor external system. Render-only, like the\n * external systems: it is never leveled or cycle-checked, because its own calls are not in this repo.\n */\nexport interface RuntimeRemoteService {\n    /** Display text from the reviewed declaration; the key is the identity. */\n    label?: string;\n    /** The contracts it is declared to implement, as `Api (transport)`, in reviewed order. */\n    implements: string[];\n    /** Workspace services that target it, sorted by caller then transport. */\n    calledBy: RuntimeRemoteCall[];\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     * Reviewed out-of-workspace services, keyed by service name (#1203). Absent when none are\n     * declared, so every graph written before this existed parses and renders exactly as before.\n     */\n    remoteServices?: Record<string, RuntimeRemoteService>;\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;;;AASH,MAAa,YAAY;IACrB,KAAK,GAAG,CAAC,CAAC;IACV,YAAY,GAAG,EAAE,CAAC;CACrB;AAHD,oCAGC;AAkGD;;;;;GAKG;AACH,MAAa,gBAAiB,SAAQ,YAAY;IAC9C,SAAS,GAAG,KAAK,CAAC;IAClB,UAAU,GAAa,EAAE,CAAC;IAC1B,UAAU,GAAa,EAAE,CAAC;CAC7B;AAJD,4CAIC","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 {\n    ApiRef,\n    ApiTransport,\n    ExternalSystemDeclaration,\n    ExternalSystemKind,\n} from './api-usage/api-relations';\n\nexport class RuntimeLevel {\n    level = 0;\n    levelBecause = '';\n}\n\nexport interface RuntimeService extends RuntimeLevel {\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    /** Reviewed binding provenance and runtime conditions, retained for compact detail views. */\n    wiringUses?: ApiRef[];\n    wiringImplements?: ApiRef[];\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     * The products this service belongs to (#1179), sorted: exactly its project's declared\n     * `product:<name>` tags (#1216). Never derived from a runtime call or a queue; a call into another\n     * product's service shows as the runtime edge, not as a product. Absent for a service whose\n     * project is untagged. See graph-products.ts.\n     */\n    products?: string[];\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 * Only exact method declarations may populate producer facts. Contract-only client wiring\n * produces contract-level edges without a method queue, regardless of the endpoint table.\n */\nexport class RuntimeQueueFlow extends RuntimeLevel {\n    selfQueue = false;\n    producedBy: string[] = [];\n    consumedBy: string[] = [];\n}\n\nexport interface RuntimeQueue extends RuntimeQueueFlow {\n    api: string;\n    method: string;\n    /** `@Queue(...)` override, else `${Api}-${method}` — the name Terraform must match 1:1. */\n    queueName: 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 extends RuntimeLevel {\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(POST, p, WRITE, EXTERNAL, { calledBy: 'twilio' })`.\n     *\n     * The caller is drawn separately from an outbound system with the same label: callers\n     * start the flow on the top row, while outbound systems are sinks on L0.\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 extends RuntimeLevel {\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 extends RuntimeLevel {\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\n/**\n * One caller's calls into a {@link RuntimeRemoteService}, one entry per (caller, transport): `via`\n * lists the contracts it calls there.\n */\nexport interface RuntimeRemoteCall {\n    from: string;\n    via: string[];\n    type: ApiTransport;\n}\n\n/**\n * A service OUTSIDE this workspace (another repo, a VM, partner endpoints) declared in the reviewed\n * `remoteServices` table of dependencies.json (#1203). It is a SERVICE — it implements our contracts —\n * so it is drawn as a service node, distinct from a vendor external system. Its level is zero:\n * outbound calls from outside this workspace are not part of this graph.\n */\nexport interface RuntimeRemoteService extends RuntimeLevel {\n    /** Display text from the reviewed declaration; the key is the identity. */\n    label?: string;\n    /** The contracts it is declared to implement, as `Api (transport)`, in reviewed order. */\n    implements: string[];\n    /** Workspace services that target it, sorted by caller then transport. */\n    calledBy: RuntimeRemoteCall[];\n}\n\nexport interface RuntimeGraph {\n    maxLevel: number;\n    /** Contract-only pubsub flows; these do not assert any method-level producers. */\n    contractQueues: Record<string, RuntimeQueueFlow>;\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     * Reviewed out-of-workspace services, keyed by service name (#1203). Absent when none are\n     * declared, so every graph written before this existed parses and renders exactly as before.\n     */\n    remoteServices?: Record<string, RuntimeRemoteService>;\n}\n"]}

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

@@ -94,4 +94,4 @@ export declare function deriveRuntimeGraph(projects: EnhancedGraph, hiddenProjec
  * file that records its own doubts would just get committed and stop being read.
  */
 export declare function deriveRuntimeGraphReport(projects: EnhancedGraph, hiddenProjects?: Set<string>, apiContracts?: ApiContracts, externalSystems?: ExternalSystemDecls, remoteServices?: RemoteServices): RuntimeGraphReport;
-export { runtimeAdjacency } from './runtime-graph-levels';
+export { runtimeAdjacency } from './runtime-node-levels';

package/src/lib/runtime-graph.js

@@ -39,6 +39,7 @@ const external_systems_1 = require("./api-usage/external-systems");
 const graph_products_1 = require("./graph-products");
 const runtime_remote_calls_1 = require("./runtime-remote-calls");
 const runtime_graph_levels_1 = require("./runtime-graph-levels");
+const runtime_node_levels_1 = require("./runtime-node-levels");
 // 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; } });
@@ -172,6 +173,8 @@ class RuntimeGraphDeriver {
         for (const api of Array.from(apis.keys()).sort())
             apisObj[api] = apis.get(api);
         const graph = {
+            maxLevel: 0,
+            contractQueues: {},
             services,
             apis: apisObj,
             runtimeEdges: edgeResult.edges,
@@ -188,6 +191,7 @@ class RuntimeGraphDeriver {
         const systems = (0, external_systems_1.resolveExternalSystems)(this.externalSystemDecls, services);
         (0, external_systems_1.attachExternalSystems)(graph, systems);
         this.remoteCalls.attach(graph);
+        new runtime_node_levels_1.RuntimeNodeLevels().apply(graph);
         return new RuntimeGraphReport(graph, this.warnings, this.problems, [...this.autoHidden].sort());
     }
     /**
@@ -205,6 +209,8 @@ class RuntimeGraphDeriver {
                     if (method.kind !== 'cron' && method.kind !== 'external')
                         continue;
                     const trigger = {
+                        level: 0,
+                        levelBecause: '',
                         kind: method.kind,
                         api: ref.api,
                         method: method.name,
@@ -369,7 +375,12 @@ class RuntimeGraphDeriver {
                 if (implementers.length === 0) {
                     // Nobody in-repo serves it. For a vendor contract that is the ANSWER, not a gap:
                     // the call leaves the repo, and the viz terminates it at a dashed vendor node.
-                    unresolved.push({ service: decl.name, api: ref.api });
+                    unresolved.push({
+                        level: 0,
+                        levelBecause: 'outbound sink',
+                        service: decl.name,
+                        api: ref.api,
+                    });
                     continue;
                 }
                 for (const target of this.targetsFor(decl.name, ref, implementers)) {
@@ -507,6 +518,7 @@ class RuntimeGraphDeriver {
             // the committed JSON stays clean AND deterministic without conditional assembly.
             const service = {
                 level: 0,
+                levelBecause: '',
                 role: this.projects[decl.name]?.role, // labels a relation-less node for what it IS
                 serviceName: this.projects[decl.name]?.serviceName,
                 callsService: this.projects[decl.name]?.callsService,
@@ -532,9 +544,6 @@ class RuntimeGraphDeriver {
                 this.autoHidden.push(decl.name);
             }
         }
-        const levels = (0, runtime_graph_levels_1.assignLevels)((0, runtime_graph_levels_1.adjacencyFromEdges)(Object.keys(services), edges));
-        for (const name of Object.keys(services))
-            services[name].level = levels[name] ?? 0;
         return services;
     }
 }
@@ -560,6 +569,6 @@ function deriveRuntimeGraphReport(projects, hiddenProjects = new Set(), apiContr
 }
 // 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; } });
+var runtime_node_levels_2 = require("./runtime-node-levels");
+Object.defineProperty(exports, "runtimeAdjacency", { enumerable: true, get: function () { return runtime_node_levels_2.runtimeAdjacency; } });
 //# sourceMappingURL=runtime-graph.js.map