@webpieces/nx-webpieces-rules 0.4.908 → 0.4.909

package/README.md

@@ -124,7 +124,16 @@ Every row is one level. A library's level is its dependency depth, but every ser
 app (`role:server` / `role:client` / `role:app`) is pinned to the TOP row, one above the highest
 library, so the top row is exactly the entry points (a `role:bundle` sits above the apps it
 aggregates; a server orchestrator above the servers it boots). The `level` in `dependencies.json`
-is that promoted level. The runtime graph keeps its call-depth levels.
+is that promoted level. The runtime graph stores a level and `levelBecause` for every service, queue, external system,
+remote service and trigger in `runtime-dependencies.json`. Outbound systems and remote services are
+L0; services start at L1 and sit one above their highest callee. Foreign queues sit one above their
+consumer and one below their foreign producers. A self-queue shares its consumer's level and does
+not raise it. Contract-only pubsub flows are stored under `contractQueues`, without inventing method
+producers. Foreign queue cycles fail with the queue named in the cycle path; existing explicit legacy
+RPC cuts remain honored. Every trigger shares the top row, one above the highest non-trigger node.
+`maxLevel` records the highest generated level. The renderer ranks all visible node kinds using these
+stored numbers; inbound callers and outbound sinks for the same vendor have separate boxes.
+After upgrading, regenerate old RPC-only JSON with `pnpm nx run architecture:generate`.
 
 - **Runtime** — where the code can run. One runtime is a solid fill. One runtime plus a
   specialization (angular/react inside browser, express inside node) is nested: a frame in the

package/package.json

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

package/src/lib/api-usage/external-systems.js

@@ -126,6 +126,8 @@ function resolveExternalSystems(decls, services) {
         out[identity] = {
             kind: decl.kind,
             label: decl.label,
+            level: 0,
+            levelBecause: 'outbound sink',
             usedBy: [...usedBy].sort(),
             apis: [...decl.apis].sort(),
         };

package/src/lib/api-usage/external-systems.js.map

@@ -1 +1 @@
-{"version":3,"file":"external-systems.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/external-systems.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * External system declarations\n *\n * A system OUTSIDE this repo that a service talks to — a database, a bucket, a cache. Until now\n * every one of them collapsed into the same grey dashed box, so `lib-firestore` (a datastore) was\n * indistinguishable from an HTTP service the repo happens not to implement. Declaring what a system\n * IS lets the runtime viz draw it as the thing it is.\n *\n * Split out of api-scanner.ts and runtime-graph.ts (both already at their file-size limit) so the\n * two halves of the feature — DECLARING a system and RESOLVING it to arrows — sit together.\n *\n * The two declaration sites exist 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 TS `interface` cannot carry a\n *    decorator, and these seams are interfaces, so JSDoc is the only marker that fits in place.\n *  - **unwrapped** — the service opens the connection itself (a `pg.Pool`, a TypeORM `DataSource`)\n *    and there is no contract to mark, so the declaration is an `external:<kind>:<identity>` nx tag\n *    on that PROJECT. Wrapping such a datastore purely to gain a marker is not worth it: a TypeORM\n *    facade never closes, unlike the ~8 hand-picked methods a firestore seam needs.\n *\n * Both resolve to the same `(kind, identity)` pair, and identity is the NODE identity — two projects\n * declaring `postgres` converge on one cylinder with an arrow each, rather than drawing a database\n * apiece.\n */\n\nimport type { ApiClassInfo, ExternalSystemDecl, ExternalSystemDecls, ExternalSystemKind } from './api-relations';\nimport { isExternalSystemKind } from './api-relations';\nimport type { ProjectInfo } from '../project-info';\nimport type { RuntimeExternalSystem, RuntimeGraph, RuntimeService } from '../runtime-graph-model';\n\n/** nx tag prefix declaring an external system: `external:<kind>:<identity>`. */\nconst EXTERNAL_TAG_PREFIX = 'external:';\n\n/** The two halves of a parsed `external:<kind>:<identity>` nx tag. */\nclass ExternalTag {\n    constructor(\n        public readonly kind: ExternalSystemKind,\n        public readonly identity: string,\n    ) {}\n}\n\n/**\n * `external:<kind>:<identity>` -> its parts, or null for any other tag.\n *\n * Returns null (rather than throwing) on an unknown kind: this prefix shares a tag list with\n * `framework:` and `role:`, and hard-failing the whole graph generation over one malformed tag is a\n * worse outcome than not drawing one node.\n */\n// webpieces-disable no-function-outside-class -- pure parser, matching the sibling builders in this file\nfunction parseExternalTag(tag: string): ExternalTag | null {\n    if (!tag.startsWith(EXTERNAL_TAG_PREFIX)) return null;\n    const parts = tag.slice(EXTERNAL_TAG_PREFIX.length).split(':');\n    if (parts.length !== 2) return null;\n    const kind = parts[0].toLowerCase();\n    const identity = parts[1].trim();\n    if (!isExternalSystemKind(kind) || identity === '') return null;\n    return new ExternalTag(kind, identity);\n}\n\n/**\n * The committed `externalSystems` table for architecture/dependencies.json, merging both declaration\n * sites into one identity-keyed map.\n *\n * A system may legitimately carry both: a repo can wrap a datastore behind a contract in one service\n * and open it directly in another. Takes the api index rather than the whole scan result so this\n * module never has to import api-scanner, which imports it.\n */\n// webpieces-disable no-function-outside-class -- table builder, mirrors buildApiContracts in api-scanner.ts\nexport function buildExternalSystems(\n    apiIndex: Map<string, ApiClassInfo>,\n    projectInfos: Map<string, ProjectInfo>,\n): ExternalSystemDecls {\n    const systems: ExternalSystemDecls = {};\n    // First declaration wins the kind, so a later typo cannot silently reshape an already-drawn node.\n    const ensure = (identity: string, kind: ExternalSystemKind, label: string): ExternalSystemDecl => {\n        if (systems[identity] === undefined) systems[identity] = { kind, label, apis: [], projects: [] };\n        return systems[identity];\n    };\n\n    for (const api of [...apiIndex.keys()].sort()) {\n        const declared = apiIndex.get(api)!.externalSystem;\n        if (declared === undefined) continue;\n        ensure(declared.label, declared.kind, declared.label).apis.push(api);\n    }\n\n    for (const name of [...projectInfos.keys()].sort()) {\n        for (const tag of projectInfos.get(name)!.tags) {\n            const parsed = parseExternalTag(tag);\n            if (parsed === null) continue;\n            ensure(parsed.identity, parsed.kind, parsed.identity).projects.push(name);\n        }\n    }\n    return systems;\n}\n\n/**\n * Resolve declarations into drawable nodes: which services actually get an arrow to each system.\n *\n * Two resolutions, matching the two declaration sites. A CONTRACT-declared system is reached by\n * every service that `uses` one of its contracts, so the arrows follow real call sites. A\n * TAG-declared system is reached ONLY by the tagged project itself — a tag asserts \"I open this\n * connection\", and fanning it out to dependents would invent arrows nobody wrote (a service that\n * depends on the entity library only for a DTO type does not talk to the database).\n *\n * A system nothing reaches is dropped rather than drawn floating: a declaration whose users all\n * disappeared is stale, and an unconnected node on the graph reads as a live dependency.\n */\n// webpieces-disable no-function-outside-class -- pure resolver, matching the sibling builders in this file\nexport function resolveExternalSystems(\n    decls: ExternalSystemDecls,\n    services: Record<string, RuntimeService>,\n): Record<string, RuntimeExternalSystem> {\n    const out: Record<string, RuntimeExternalSystem> = {};\n    for (const identity of Object.keys(decls).sort()) {\n        const decl = decls[identity];\n        const usedBy = new Set<string>();\n        for (const name of Object.keys(services)) {\n            if (services[name].uses.some((api: string) => decl.apis.includes(api))) usedBy.add(name);\n        }\n        // Only when the tagged project is itself a runtime node — tagging a plain library would\n        // otherwise draw an arrow leaving a box that does not exist on this graph.\n        for (const project of decl.projects) {\n            if (services[project] !== undefined) usedBy.add(project);\n        }\n        if (usedBy.size === 0) continue;\n        out[identity] = {\n            kind: decl.kind,\n            label: decl.label,\n            usedBy: [...usedBy].sort(),\n            apis: [...decl.apis].sort(),\n        };\n    }\n    return out;\n}\n\n/**\n * Hang the resolved systems off the graph, and STAMP each declaring contract with its declaration.\n *\n * The stamp is what stops the same system being drawn twice: the visualizer skips an\n * `unresolvedUses` entry whose contract carries one, because that contract has already been drawn\n * with a real shape rather than as the generic grey box it would otherwise fall back to.\n *\n * A graph with nothing declared is left completely untouched — no empty key is written — so a repo\n * that adopts none of this keeps a byte-identical runtime-dependencies.json.\n */\n// webpieces-disable no-function-outside-class -- pure graph mutator, matching the sibling builders in this file\nexport function attachExternalSystems(graph: RuntimeGraph, systems: Record<string, RuntimeExternalSystem>): void {\n    if (Object.keys(systems).length === 0) return;\n    graph.externalSystems = systems;\n    for (const system of Object.values(systems)) {\n        for (const api of system.apis) {\n            const entry = graph.apis[api];\n            if (entry !== undefined) entry.externalSystem = { kind: system.kind, label: system.label };\n        }\n    }\n}\n"]}
+{"version":3,"file":"external-systems.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/external-systems.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * External system declarations\n *\n * A system OUTSIDE this repo that a service talks to — a database, a bucket, a cache. Until now\n * every one of them collapsed into the same grey dashed box, so `lib-firestore` (a datastore) was\n * indistinguishable from an HTTP service the repo happens not to implement. Declaring what a system\n * IS lets the runtime viz draw it as the thing it is.\n *\n * Split out of api-scanner.ts and runtime-graph.ts (both already at their file-size limit) so the\n * two halves of the feature — DECLARING a system and RESOLVING it to arrows — sit together.\n *\n * The two declaration sites exist 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 TS `interface` cannot carry a\n *    decorator, and these seams are interfaces, so JSDoc is the only marker that fits in place.\n *  - **unwrapped** — the service opens the connection itself (a `pg.Pool`, a TypeORM `DataSource`)\n *    and there is no contract to mark, so the declaration is an `external:<kind>:<identity>` nx tag\n *    on that PROJECT. Wrapping such a datastore purely to gain a marker is not worth it: a TypeORM\n *    facade never closes, unlike the ~8 hand-picked methods a firestore seam needs.\n *\n * Both resolve to the same `(kind, identity)` pair, and identity is the NODE identity — two projects\n * declaring `postgres` converge on one cylinder with an arrow each, rather than drawing a database\n * apiece.\n */\n\nimport type { ApiClassInfo, ExternalSystemDecl, ExternalSystemDecls, ExternalSystemKind } from './api-relations';\nimport { isExternalSystemKind } from './api-relations';\nimport type { ProjectInfo } from '../project-info';\nimport type { RuntimeExternalSystem, RuntimeGraph, RuntimeService } from '../runtime-graph-model';\n\n/** nx tag prefix declaring an external system: `external:<kind>:<identity>`. */\nconst EXTERNAL_TAG_PREFIX = 'external:';\n\n/** The two halves of a parsed `external:<kind>:<identity>` nx tag. */\nclass ExternalTag {\n    constructor(\n        public readonly kind: ExternalSystemKind,\n        public readonly identity: string,\n    ) {}\n}\n\n/**\n * `external:<kind>:<identity>` -> its parts, or null for any other tag.\n *\n * Returns null (rather than throwing) on an unknown kind: this prefix shares a tag list with\n * `framework:` and `role:`, and hard-failing the whole graph generation over one malformed tag is a\n * worse outcome than not drawing one node.\n */\n// webpieces-disable no-function-outside-class -- pure parser, matching the sibling builders in this file\nfunction parseExternalTag(tag: string): ExternalTag | null {\n    if (!tag.startsWith(EXTERNAL_TAG_PREFIX)) return null;\n    const parts = tag.slice(EXTERNAL_TAG_PREFIX.length).split(':');\n    if (parts.length !== 2) return null;\n    const kind = parts[0].toLowerCase();\n    const identity = parts[1].trim();\n    if (!isExternalSystemKind(kind) || identity === '') return null;\n    return new ExternalTag(kind, identity);\n}\n\n/**\n * The committed `externalSystems` table for architecture/dependencies.json, merging both declaration\n * sites into one identity-keyed map.\n *\n * A system may legitimately carry both: a repo can wrap a datastore behind a contract in one service\n * and open it directly in another. Takes the api index rather than the whole scan result so this\n * module never has to import api-scanner, which imports it.\n */\n// webpieces-disable no-function-outside-class -- table builder, mirrors buildApiContracts in api-scanner.ts\nexport function buildExternalSystems(\n    apiIndex: Map<string, ApiClassInfo>,\n    projectInfos: Map<string, ProjectInfo>,\n): ExternalSystemDecls {\n    const systems: ExternalSystemDecls = {};\n    // First declaration wins the kind, so a later typo cannot silently reshape an already-drawn node.\n    const ensure = (identity: string, kind: ExternalSystemKind, label: string): ExternalSystemDecl => {\n        if (systems[identity] === undefined) systems[identity] = { kind, label, apis: [], projects: [] };\n        return systems[identity];\n    };\n\n    for (const api of [...apiIndex.keys()].sort()) {\n        const declared = apiIndex.get(api)!.externalSystem;\n        if (declared === undefined) continue;\n        ensure(declared.label, declared.kind, declared.label).apis.push(api);\n    }\n\n    for (const name of [...projectInfos.keys()].sort()) {\n        for (const tag of projectInfos.get(name)!.tags) {\n            const parsed = parseExternalTag(tag);\n            if (parsed === null) continue;\n            ensure(parsed.identity, parsed.kind, parsed.identity).projects.push(name);\n        }\n    }\n    return systems;\n}\n\n/**\n * Resolve declarations into drawable nodes: which services actually get an arrow to each system.\n *\n * Two resolutions, matching the two declaration sites. A CONTRACT-declared system is reached by\n * every service that `uses` one of its contracts, so the arrows follow real call sites. A\n * TAG-declared system is reached ONLY by the tagged project itself — a tag asserts \"I open this\n * connection\", and fanning it out to dependents would invent arrows nobody wrote (a service that\n * depends on the entity library only for a DTO type does not talk to the database).\n *\n * A system nothing reaches is dropped rather than drawn floating: a declaration whose users all\n * disappeared is stale, and an unconnected node on the graph reads as a live dependency.\n */\n// webpieces-disable no-function-outside-class -- pure resolver, matching the sibling builders in this file\nexport function resolveExternalSystems(\n    decls: ExternalSystemDecls,\n    services: Record<string, RuntimeService>,\n): Record<string, RuntimeExternalSystem> {\n    const out: Record<string, RuntimeExternalSystem> = {};\n    for (const identity of Object.keys(decls).sort()) {\n        const decl = decls[identity];\n        const usedBy = new Set<string>();\n        for (const name of Object.keys(services)) {\n            if (services[name].uses.some((api: string) => decl.apis.includes(api))) usedBy.add(name);\n        }\n        // Only when the tagged project is itself a runtime node — tagging a plain library would\n        // otherwise draw an arrow leaving a box that does not exist on this graph.\n        for (const project of decl.projects) {\n            if (services[project] !== undefined) usedBy.add(project);\n        }\n        if (usedBy.size === 0) continue;\n        out[identity] = {\n            kind: decl.kind,\n            label: decl.label,\n            level: 0,\n            levelBecause: 'outbound sink',\n            usedBy: [...usedBy].sort(),\n            apis: [...decl.apis].sort(),\n        };\n    }\n    return out;\n}\n\n/**\n * Hang the resolved systems off the graph, and STAMP each declaring contract with its declaration.\n *\n * The stamp is what stops the same system being drawn twice: the visualizer skips an\n * `unresolvedUses` entry whose contract carries one, because that contract has already been drawn\n * with a real shape rather than as the generic grey box it would otherwise fall back to.\n *\n * A graph with nothing declared is left completely untouched — no empty key is written — so a repo\n * that adopts none of this keeps a byte-identical runtime-dependencies.json.\n */\n// webpieces-disable no-function-outside-class -- pure graph mutator, matching the sibling builders in this file\nexport function attachExternalSystems(graph: RuntimeGraph, systems: Record<string, RuntimeExternalSystem>): void {\n    if (Object.keys(systems).length === 0) return;\n    graph.externalSystems = systems;\n    for (const system of Object.values(systems)) {\n        for (const api of system.apis) {\n            const entry = graph.apis[api];\n            if (entry !== undefined) entry.externalSystem = { kind: system.kind, label: system.label };\n        }\n    }\n}\n"]}

package/src/lib/runtime-external-triggers.js

@@ -32,7 +32,7 @@ class RuntimeExternalTriggers {
             const caller = trigger.caller;
             const from = caller === undefined
                 ? `inbound__${trigger.api.replace(/[^A-Za-z0-9_]/g, '_')}`
-                : `system__${caller.label.replace(/[^A-Za-z0-9_]/g, '_')}`;
+                : `system__caller__${caller.label.replace(/[^A-Za-z0-9_]/g, '_')}`;
             const key = JSON.stringify([from, trigger.service]);
             if (!groups.has(key))
                 groups.set(key, new RuntimeExternalTriggerGroup(from, trigger.service));

package/src/lib/runtime-external-triggers.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-external-triggers.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-external-triggers.ts"],"names":[],"mappings":";;;AAEA,+EAA+E;AAC/E,MAAa,2BAA2B;IAIvB;IACA;IAJJ,QAAQ,GAAqB,EAAE,CAAC;IAEzC,YACa,IAAY,EACZ,EAAU;QADV,SAAI,GAAJ,IAAI,CAAQ;QACZ,OAAE,GAAF,EAAE,CAAQ;IACpB,CAAC;IAEJ,IAAI;QACA,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAuB,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5F,CAAC;IAED,KAAK;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,IAAI,CAAC,MAAM,KAAK,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAuB,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACxF,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;CACJ;AAlBD,kEAkBC;AAED,MAAa,uBAAuB;IACvB,MAAM,CAAgC;IAE/C,YAAY,QAA0B;QAClC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuC,CAAC;QAC9D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU;gBAAE,SAAS;YAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAC9B,MAAM,IAAI,GACN,MAAM,KAAK,SAAS;gBAChB,CAAC,CAAC,YAAY,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE;gBAC1D,CAAC,CAAC,WAAW,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;gBAChB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5E,MAAM,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ;AAnBD,0DAmBC","sourcesContent":["import type { RuntimeTrigger } from './runtime-graph-model';\n\n/** One external caller/service pair, shared by DOT emission and popup data. */\nexport class RuntimeExternalTriggerGroup {\n    readonly triggers: RuntimeTrigger[] = [];\n\n    constructor(\n        readonly from: string,\n        readonly to: string,\n    ) {}\n\n    apis(): string[] {\n        return [...new Set(this.triggers.map((trigger: RuntimeTrigger) => trigger.api))].sort();\n    }\n\n    label(): string {\n        const apis = this.apis();\n        if (apis.length > 1) return `Uses (${apis.length}) ▾`;\n        const methods = new Set(this.triggers.map((trigger: RuntimeTrigger) => trigger.method));\n        return methods.size === 1 ? `${apis[0]}.${this.triggers[0].method}` : apis[0];\n    }\n}\n\nexport class RuntimeExternalTriggers {\n    readonly groups: RuntimeExternalTriggerGroup[];\n\n    constructor(triggers: RuntimeTrigger[]) {\n        const groups = new Map<string, RuntimeExternalTriggerGroup>();\n        for (const trigger of triggers) {\n            if (trigger.kind !== 'external') continue;\n            const caller = trigger.caller;\n            const from =\n                caller === undefined\n                    ? `inbound__${trigger.api.replace(/[^A-Za-z0-9_]/g, '_')}`\n                    : `system__${caller.label.replace(/[^A-Za-z0-9_]/g, '_')}`;\n            const key = JSON.stringify([from, trigger.service]);\n            if (!groups.has(key))\n                groups.set(key, new RuntimeExternalTriggerGroup(from, trigger.service));\n            groups.get(key)!.triggers.push(trigger);\n        }\n        this.groups = [...groups.values()];\n    }\n}\n"]}
+{"version":3,"file":"runtime-external-triggers.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-external-triggers.ts"],"names":[],"mappings":";;;AAEA,+EAA+E;AAC/E,MAAa,2BAA2B;IAIvB;IACA;IAJJ,QAAQ,GAAqB,EAAE,CAAC;IAEzC,YACa,IAAY,EACZ,EAAU;QADV,SAAI,GAAJ,IAAI,CAAQ;QACZ,OAAE,GAAF,EAAE,CAAQ;IACpB,CAAC;IAEJ,IAAI;QACA,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAuB,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5F,CAAC;IAED,KAAK;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,IAAI,CAAC,MAAM,KAAK,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAuB,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACxF,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;CACJ;AAlBD,kEAkBC;AAED,MAAa,uBAAuB;IACvB,MAAM,CAAgC;IAE/C,YAAY,QAA0B;QAClC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuC,CAAC;QAC9D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU;gBAAE,SAAS;YAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAC9B,MAAM,IAAI,GACN,MAAM,KAAK,SAAS;gBAChB,CAAC,CAAC,YAAY,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE;gBAC1D,CAAC,CAAC,mBAAmB,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE,CAAC;YAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;gBAChB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5E,MAAM,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;CACJ;AAnBD,0DAmBC","sourcesContent":["import type { RuntimeTrigger } from './runtime-graph-model';\n\n/** One external caller/service pair, shared by DOT emission and popup data. */\nexport class RuntimeExternalTriggerGroup {\n    readonly triggers: RuntimeTrigger[] = [];\n\n    constructor(\n        readonly from: string,\n        readonly to: string,\n    ) {}\n\n    apis(): string[] {\n        return [...new Set(this.triggers.map((trigger: RuntimeTrigger) => trigger.api))].sort();\n    }\n\n    label(): string {\n        const apis = this.apis();\n        if (apis.length > 1) return `Uses (${apis.length}) ▾`;\n        const methods = new Set(this.triggers.map((trigger: RuntimeTrigger) => trigger.method));\n        return methods.size === 1 ? `${apis[0]}.${this.triggers[0].method}` : apis[0];\n    }\n}\n\nexport class RuntimeExternalTriggers {\n    readonly groups: RuntimeExternalTriggerGroup[];\n\n    constructor(triggers: RuntimeTrigger[]) {\n        const groups = new Map<string, RuntimeExternalTriggerGroup>();\n        for (const trigger of triggers) {\n            if (trigger.kind !== 'external') continue;\n            const caller = trigger.caller;\n            const from =\n                caller === undefined\n                    ? `inbound__${trigger.api.replace(/[^A-Za-z0-9_]/g, '_')}`\n                    : `system__caller__${caller.label.replace(/[^A-Za-z0-9_]/g, '_')}`;\n            const key = JSON.stringify([from, trigger.service]);\n            if (!groups.has(key))\n                groups.set(key, new RuntimeExternalTriggerGroup(from, trigger.service));\n            groups.get(key)!.triggers.push(trigger);\n        }\n        this.groups = [...groups.values()];\n    }\n}\n"]}

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

@@ -18,6 +18,8 @@ exports.serializeRuntimeGraph = serializeRuntimeGraph;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const runtime_config_1 = require("./runtime-config");
 const toError_1 = require("../toError");
 exports.DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';
 /** Deterministic JSON (sorted keys + arrays already sorted during assembly). */
@@ -42,18 +44,44 @@ function loadRuntimeGraph(workspaceRoot, graphPath = exports.DEFAULT_RUNTIME_GRA
     const fullPath = path.join(workspaceRoot, graphPath);
     if (!fs.existsSync(fullPath))
         return null;
+    let graph;
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
-        return JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
+        graph = JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
         throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });
     }
+    new RuntimeLevelSchema().validate(graph);
+    return graph;
 }
 /** Serialize for an in-memory equality check (matches the on-disk format). */
 // webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts
 function serializeRuntimeGraph(graph) {
     return formatRuntimeJson(graph);
 }
+/** Old RPC-only JSON must be regenerated, never silently rendered with missing ranks. */
+class RuntimeLevelSchema {
+    validate(graph) {
+        const nodes = [
+            ...Object.values(graph.services),
+            ...Object.values(graph.queues),
+            ...Object.values(graph.contractQueues ?? {}),
+            ...graph.triggers,
+            ...Object.values(graph.externalSystems ?? {}),
+            ...Object.values(graph.remoteServices ?? {}),
+            ...graph.unresolvedUses,
+        ];
+        if (graph.contractQueues !== undefined &&
+            Number.isInteger(graph.maxLevel) &&
+            nodes.every((node) => Number.isInteger(node.level) &&
+                node.level >= 0 &&
+                typeof node.levelBecause === 'string'))
+            return;
+        throw new rules_config_1.RuleFailError(runtime_config_1.RUNTIME_RULE_NAME, 'runtime-dependencies.json requires levels for every node and contractQueues. Regenerate with architecture:generate.', undefined, undefined, [
+            new rules_config_1.Option('Run pnpm nx run architecture:generate and commit runtime-dependencies.json.', true),
+        ]);
+    }
+}
 //# sourceMappingURL=runtime-graph-io.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-graph-io.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-io.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAgBH,4CASC;AAGD,wDAKC;AAGD,4CAaC;AAID,sDAEC;;AArDD,+CAAyB;AACzB,mDAA6B;AAE7B,wCAAqC;AAExB,QAAA,0BAA0B,GAAG,wCAAwC,CAAC;AAEnF,gFAAgF;AAChF,8HAA8H;AAC9H,SAAS,iBAAiB,CAAC,KAAmB;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AACjD,CAAC;AAED,8HAA8H;AAC9H,SAAgB,gBAAgB,CAC5B,KAAmB,EACnB,aAAqB,EACrB,YAAoB,kCAA0B;IAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED,8HAA8H;AAC9H,SAAgB,sBAAsB,CAClC,aAAqB,EACrB,YAAoB,kCAA0B;IAE9C,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,8HAA8H;AAC9H,SAAgB,gBAAgB,CAC5B,aAAqB,EACrB,YAAoB,kCAA0B;IAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,8DAA8D;IAC9D,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAiB,CAAC;IAC1E,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,8HAA8H;AAC9H,SAAgB,qBAAqB,CAAC,KAAmB;IACrD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC","sourcesContent":["/**\n * Runtime Graph persistence\n *\n * Reading, writing and canonical-serializing architecture/runtime-dependencies.json. Split out of\n * runtime-graph.ts (which owns the derivation and had grown past the file-size limit).\n *\n * `formatRuntimeJson` is the ONE canonical rendering: validate-runtime-architecture compares the\n * freshly derived graph to the committed one as STRINGS, so any second way of writing this file\n * would show up as unfixable drift.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { RuntimeGraph } from './runtime-graph-model';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}
+{"version":3,"file":"runtime-graph-io.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph-io.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph persistence\n *\n * Reading, writing and canonical-serializing architecture/runtime-dependencies.json. Split out of\n * runtime-graph.ts (which owns the derivation and had grown past the file-size limit).\n *\n * `formatRuntimeJson` is the ONE canonical rendering: validate-runtime-architecture compares the\n * freshly derived graph to the committed one as STRINGS, so any second way of writing this file\n * would show up as unfixable drift.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport { RUNTIME_RULE_NAME } from './runtime-config';\nimport type { RuntimeGraph } from './runtime-graph-model';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    let graph: RuntimeGraph;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        graph = JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n    new RuntimeLevelSchema().validate(graph);\n    return graph;\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\n// webpieces-disable no-function-outside-class -- module-scope file IO, matching saveGraph/loadBlessedGraph in graph-loader.ts\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n\n/** Old RPC-only JSON must be regenerated, never silently rendered with missing ranks. */\nclass RuntimeLevelSchema {\n    validate(graph: RuntimeGraph): void {\n        const nodes = [\n            ...Object.values(graph.services),\n            ...Object.values(graph.queues),\n            ...Object.values(graph.contractQueues ?? {}),\n            ...graph.triggers,\n            ...Object.values(graph.externalSystems ?? {}),\n            ...Object.values(graph.remoteServices ?? {}),\n            ...graph.unresolvedUses,\n        ];\n        if (\n            graph.contractQueues !== undefined &&\n            Number.isInteger(graph.maxLevel) &&\n            nodes.every(\n                (node) =>\n                    Number.isInteger(node.level) &&\n                    node.level >= 0 &&\n                    typeof node.levelBecause === 'string',\n            )\n        )\n            return;\n        throw new RuleFailError(\n            RUNTIME_RULE_NAME,\n            'runtime-dependencies.json requires levels for every node and contractQueues. Regenerate with architecture:generate.',\n            undefined,\n            undefined,\n            [\n                new Option(\n                    'Run pnpm nx run architecture:generate and commit runtime-dependencies.json.',\n                    true,\n                ),\n            ],\n        );\n    }\n}\n"]}

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

@@ -1,5 +1,5 @@
 import type { EnhancedGraph } from './graph-sorter';
-import type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';
+import type { RuntimeEdge } from './runtime-graph-model';
 /**
  * LEVELS and ADJACENCY for the runtime graph — how deep each service sits, and who calls whom.
  *
@@ -8,23 +8,7 @@ import type { RuntimeEdge, RuntimeGraph } from './runtime-graph-model';
  * 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. */
 export declare function adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]>;
 /**
  * Stamp `cutLegacyCycle` on every runtime edge a project declared a cut for — the DECLARATION
@@ -49,8 +33,6 @@ export declare function adjacencyFromEdges(serviceNames: string[], edges: Runtim
  *                          target, so a tag may name a module name or a declared serviceName.
  */
 export declare function applyCycleCuts(edges: RuntimeEdge[], projects: EnhancedGraph, nodeByServiceName: Map<string, string>): string[];
-/** Adjacency (service -> [targets]) from a loaded runtime graph. */
-export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]>;
 /**
  * Assign levels via topological sort — and THROW on a cycle rather than levelling one.
  *

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';