feat(calm-suite): adopt canonical nested relationship-type in CALMGuard

Bring CALMGuard onto the canonical nested relationship-type form for cross-tool interop with CalmStudio, updating the extractor/normalizer/types, examples, and tests.

Signed-off-by: Eddie Knight <knight@linux.com>

Author: eddie-knight

calm-suite/calm-guard/AGENTS.md

@@ -31,16 +31,23 @@ Source: `https://github.com/finos/architecture-as-code` (CALM release 1.2)
 ### Core Entities
 
 **Nodes** (required: unique-id, node-type, name, description):
-- `node-type` enum: `actor`, `ecosystem`, `system`, `service`, `database`, `network`, `ldap`, `webclient`, `data-asset`
+- `node-type`: any string. The 9 well-known values (`actor`, `ecosystem`, `system`, `service`, `database`, `network`, `ldap`, `webclient`, `data-asset`) get first-class UI, but canonical CALM allows any string (e.g. extension types like `aws:lambda`), so CALMGuard accepts any string for interoperability.
 - Optional: `interfaces[]`, `controls{}`, `metadata`, `details`
 
 **Relationships** (required: unique-id, relationship-type):
-- Types (mutually exclusive): `interacts`, `connects`, `deployed-in`, `composed-of`, `options`
-- `interacts`: `{ actor: string, nodes: string[] }`
-- `connects`: `{ source: { node, interfaces[] }, destination: { node, interfaces[] } }`
-- `deployed-in` / `composed-of`: `{ container: string, nodes: string[] }`
+- `relationship-type` is a **nested object** keyed by exactly one variant — NOT a string discriminant. The variant payload lives inside it; `protocol`/`controls`/`metadata`/`description` are siblings of `relationship-type` at the relationship level.
+- Canonical nested form:
+  ```json
+  { "unique-id": "r1", "relationship-type": { "connects": { "source": { "node": "a" }, "destination": { "node": "b" } } }, "protocol": "HTTPS" }
+  ```
+- Variants (exactly one present):
+  - `connects`: `{ source: { node, interfaces?[] }, destination: { node, interfaces?[] } }`
+  - `interacts`: `{ actor: string, nodes: string[] }`
+  - `deployed-in` / `composed-of`: `{ container: string, nodes: string[] }`
+  - `options`: loosely typed (CALMGuard treats as `unknown`)
 - `protocol` enum: `HTTP`, `HTTPS`, `FTP`, `SFTP`, `JDBC`, `WebSocket`, `SocketIO`, `LDAP`, `AMQP`, `TLS`, `mTLS`, `TCP`
-- Optional: `controls{}`, `metadata`, `description`
+- Optional (siblings): `controls{}`, `metadata`, `description`
+- NOTE: the legacy flat form (`"relationship-type": "connects"` + sibling `connects`) is **no longer accepted** — use the nested form so documents round-trip with the CLI, Hub, Visualizer, and Studio.
 
 **Controls** (pattern-keyed object `^[a-zA-Z0-9-]+$`):
 - Each control: `{ description (required), requirements: [{ requirement-url (required), config-url | config }] }`

calm-suite/calm-guard/examples/payment-gateway.calm.json

@@ -163,26 +163,28 @@
   "relationships": [
     {
       "unique-id": "customer-to-checkout",
-      "relationship-type": "interacts",
-      "description": "Customer enters payment information on checkout page",
-      "interacts": {
-        "actor": "customer",
-        "nodes": ["checkout-page"]
-      }
+      "relationship-type": {
+        "interacts": {
+          "actor": "customer",
+          "nodes": ["checkout-page"]
+        }
+      },
+      "description": "Customer enters payment information on checkout page"
     },
     {
       "unique-id": "checkout-to-payment-api",
-      "relationship-type": "connects",
-      "description": "Checkout page submits encrypted payment data to payment API",
-      "protocol": "HTTPS",
-      "connects": {
-        "source": {
-          "node": "checkout-page"
-        },
-        "destination": {
-          "node": "payment-api"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "checkout-page"
+          },
+          "destination": {
+            "node": "payment-api"
+          }
         }
       },
+      "description": "Checkout page submits encrypted payment data to payment API",
+      "protocol": "HTTPS",
       "controls": {
         "tls-enforcement": {
           "description": "Enforce TLS 1.2 minimum with strong cipher suites",
@@ -196,59 +198,63 @@
     },
     {
       "unique-id": "payment-api-to-tokenization",
-      "relationship-type": "connects",
-      "description": "Payment API requests card tokenization",
-      "protocol": "mTLS",
-      "connects": {
-        "source": {
-          "node": "payment-api"
-        },
-        "destination": {
-          "node": "tokenization-service"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "payment-api"
+          },
+          "destination": {
+            "node": "tokenization-service"
+          }
         }
-      }
+      },
+      "description": "Payment API requests card tokenization",
+      "protocol": "mTLS"
     },
     {
       "unique-id": "payment-api-to-fraud",
-      "relationship-type": "connects",
-      "description": "Payment API checks transaction for fraud indicators",
-      "protocol": "HTTPS",
-      "connects": {
-        "source": {
-          "node": "payment-api"
-        },
-        "destination": {
-          "node": "fraud-detection"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "payment-api"
+          },
+          "destination": {
+            "node": "fraud-detection"
+          }
         }
-      }
+      },
+      "description": "Payment API checks transaction for fraud indicators",
+      "protocol": "HTTPS"
     },
     {
       "unique-id": "payment-api-to-db",
-      "relationship-type": "connects",
-      "description": "Payment API persists transaction records",
-      "protocol": "JDBC",
-      "connects": {
-        "source": {
-          "node": "payment-api"
-        },
-        "destination": {
-          "node": "transaction-database"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "payment-api"
+          },
+          "destination": {
+            "node": "transaction-database"
+          }
         }
-      }
+      },
+      "description": "Payment API persists transaction records",
+      "protocol": "JDBC"
     },
     {
       "unique-id": "tokenization-to-card-network",
-      "relationship-type": "connects",
-      "description": "Tokenization service forwards authorization request to card network",
-      "protocol": "mTLS",
-      "connects": {
-        "source": {
-          "node": "tokenization-service"
-        },
-        "destination": {
-          "node": "card-network"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "tokenization-service"
+          },
+          "destination": {
+            "node": "card-network"
+          }
         }
-      }
+      },
+      "description": "Tokenization service forwards authorization request to card network",
+      "protocol": "mTLS"
     }
   ],
   "flows": [

calm-suite/calm-guard/examples/trading-platform.calm.json

@@ -154,124 +154,133 @@
   "relationships": [
     {
       "unique-id": "trader-to-dashboard",
-      "relationship-type": "interacts",
-      "description": "Trader accesses trading dashboard via web browser",
-      "interacts": {
-        "actor": "trader",
-        "nodes": ["trading-dashboard"]
-      }
+      "relationship-type": {
+        "interacts": {
+          "actor": "trader",
+          "nodes": ["trading-dashboard"]
+        }
+      },
+      "description": "Trader accesses trading dashboard via web browser"
     },
     {
       "unique-id": "dashboard-to-order-mgmt",
-      "relationship-type": "connects",
-      "description": "Trading dashboard submits orders to order management service",
-      "protocol": "HTTPS",
-      "connects": {
-        "source": {
-          "node": "trading-dashboard"
-        },
-        "destination": {
-          "node": "order-mgmt-service"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "trading-dashboard"
+          },
+          "destination": {
+            "node": "order-mgmt-service"
+          }
         }
-      }
+      },
+      "description": "Trading dashboard submits orders to order management service",
+      "protocol": "HTTPS"
     },
     {
       "unique-id": "order-mgmt-to-risk",
-      "relationship-type": "connects",
-      "description": "Order management service validates orders with risk engine",
-      "protocol": "HTTPS",
-      "connects": {
-        "source": {
-          "node": "order-mgmt-service"
-        },
-        "destination": {
-          "node": "risk-engine"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "order-mgmt-service"
+          },
+          "destination": {
+            "node": "risk-engine"
+          }
         }
-      }
+      },
+      "description": "Order management service validates orders with risk engine",
+      "protocol": "HTTPS"
     },
     {
       "unique-id": "order-mgmt-to-fix",
-      "relationship-type": "connects",
-      "description": "Order management service routes validated orders to FIX gateway",
-      "protocol": "TCP",
-      "connects": {
-        "source": {
-          "node": "order-mgmt-service"
-        },
-        "destination": {
-          "node": "fix-gateway"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "order-mgmt-service"
+          },
+          "destination": {
+            "node": "fix-gateway"
+          }
         }
-      }
+      },
+      "description": "Order management service routes validated orders to FIX gateway",
+      "protocol": "TCP"
     },
     {
       "unique-id": "order-mgmt-to-db",
-      "relationship-type": "connects",
-      "description": "Order management service persists orders to database",
-      "protocol": "JDBC",
-      "connects": {
-        "source": {
-          "node": "order-mgmt-service"
-        },
-        "destination": {
-          "node": "order-database"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "order-mgmt-service"
+          },
+          "destination": {
+            "node": "order-database"
+          }
         }
-      }
+      },
+      "description": "Order management service persists orders to database",
+      "protocol": "JDBC"
     },
     {
       "unique-id": "market-data-to-cache",
-      "relationship-type": "connects",
-      "description": "Market data service updates real-time price cache",
-      "protocol": "TCP",
-      "connects": {
-        "source": {
-          "node": "market-data-service"
-        },
-        "destination": {
-          "node": "market-data-cache"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "market-data-service"
+          },
+          "destination": {
+            "node": "market-data-cache"
+          }
         }
-      }
+      },
+      "description": "Market data service updates real-time price cache",
+      "protocol": "TCP"
     },
     {
       "unique-id": "fix-to-exchange",
-      "relationship-type": "connects",
-      "description": "FIX gateway connects to exchange for order execution",
-      "protocol": "mTLS",
-      "connects": {
-        "source": {
-          "node": "fix-gateway"
-        },
-        "destination": {
-          "node": "exchange-gateway"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "fix-gateway"
+          },
+          "destination": {
+            "node": "exchange-gateway"
+          }
         }
-      }
+      },
+      "description": "FIX gateway connects to exchange for order execution",
+      "protocol": "mTLS"
     },
     {
       "unique-id": "dashboard-to-market-data",
-      "relationship-type": "connects",
-      "description": "Trading dashboard subscribes to real-time market data",
-      "protocol": "WebSocket",
-      "connects": {
-        "source": {
-          "node": "trading-dashboard"
-        },
-        "destination": {
-          "node": "market-data-service"
+      "relationship-type": {
+        "connects": {
+          "source": {
+            "node": "trading-dashboard"
+          },
+          "destination": {
+            "node": "market-data-service"
+          }
         }
-      }
+      },
+      "description": "Trading dashboard subscribes to real-time market data",
+      "protocol": "WebSocket"
     },
     {
       "unique-id": "trading-services-network",
-      "relationship-type": "deployed-in",
-      "description": "Core trading services deployed in low-latency network",
-      "deployed-in": {
-        "container": "trading-network",
-        "nodes": [
-          "order-mgmt-service",
-          "fix-gateway",
-          "risk-engine",
-          "market-data-service"
-        ]
-      }
+      "relationship-type": {
+        "deployed-in": {
+          "container": "trading-network",
+          "nodes": [
+            "order-mgmt-service",
+            "fix-gateway",
+            "risk-engine",
+            "market-data-service"
+          ]
+        }
+      },
+      "description": "Core trading services deployed in low-latency network"
     }
   ],
   "flows": [