feat(risk): supply-chain operational-risk contract (BIAN/FICO)

Makefile

@@ -1,8 +1,12 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-supply-chain-risk-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-supply-chain-risk-examples
 	@echo "OK: validate"
 
+validate-supply-chain-risk-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_supply_chain_risk_examples.py
+
 validate-control-plane-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_control_plane_examples.py

examples/risk_cluster.json

@@ -0,0 +1,18 @@
+{
+  "id": "urn:srcos:risk-cluster:trans-pacific-shipping",
+  "type": "RiskCluster",
+  "specVersion": "2.0.0",
+  "clusterName": "Trans-Pacific shipping lanes",
+  "clusterType": "Logistics / route concentration",
+  "providerShares": [
+    0.55,
+    0.25,
+    0.2
+  ],
+  "hhi": 0.39,
+  "blastRadius": 0.6,
+  "timeToRecover": 0.5,
+  "exitDifficulty": 0.7,
+  "residualCommonMode": 0.52,
+  "rating": "High"
+}

examples/risk_indicator.json

@@ -0,0 +1,15 @@
+{
+  "id": "urn:srcos:risk-indicator:tier0-provenance",
+  "type": "RiskIndicator",
+  "specVersion": "2.0.0",
+  "indicatorType": "KRI",
+  "metric": "Tier-0 nodes with verified provenance",
+  "definition": "Share of tier-0 supply-chain nodes with verified provenance attached before admission.",
+  "value": 0.82,
+  "green": ">=95%",
+  "amber": "80-94.9%",
+  "red": "<80%",
+  "band": "amber",
+  "frequency": "Weekly",
+  "owner": "Supply Chain Risk"
+}

examples/risk_node.json

@@ -0,0 +1,30 @@
+{
+  "id": "urn:srcos:risk-node:escondida",
+  "type": "RiskNode",
+  "specVersion": "2.0.0",
+  "nodeRef": "hg:facility/escondida",
+  "criticalService": "Copper cathode supply",
+  "inherent": {
+    "criticality": 0.9,
+    "privilege": 0.4,
+    "execution": 0.2,
+    "opacity": 0.5,
+    "concentration": 0.8,
+    "velocity": 0.3
+  },
+  "inherentScore": 0.62,
+  "controls": {
+    "governance": 0.7,
+    "identityPublish": 0.5,
+    "provenance": 0.6,
+    "integrity": 0.6,
+    "distribution": 0.4,
+    "monitoring": 0.6
+  },
+  "residualScore": 0.34,
+  "rating": "Medium",
+  "controlGaps": [
+    "distribution"
+  ],
+  "note": "World's largest copper mine — high criticality + concentration; water is the swing risk."
+}

examples/risk_path.json

@@ -0,0 +1,15 @@
+{
+  "id": "urn:srcos:risk-path:copper-cathode",
+  "type": "RiskPath",
+  "specVersion": "2.0.0",
+  "criticalService": "Copper cathode · Antofagasta → Shanghai",
+  "serviceOwner": "Copper Capital Syndicate",
+  "nodeRefs": [
+    "urn:srcos:risk-node:escondida",
+    "urn:srcos:risk-node:antofagasta-port",
+    "urn:srcos:risk-node:route-anf-sha"
+  ],
+  "pathRisk": 0.48,
+  "rating": "High",
+  "impactTolerance": "< 2 weeks"
+}

schemas/RiskCluster.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RiskCluster.json",
+  "title": "RiskCluster",
+  "description": "Common-mode / concentration cluster risk — correlated dependencies (a shared registry, CI provider, identity broker, model provider, or control plane). HHI measures concentration; blast radius, time-to-recover, and exit-difficulty size the systemic exposure.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "clusterName",
+    "hhi",
+    "residualCommonMode",
+    "rating"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:risk-cluster:",
+      "description": "Stable URN. Pattern: urn:srcos:risk-cluster:<local-id>"
+    },
+    "type": {
+      "const": "RiskCluster",
+      "description": "Discriminator — always \"RiskCluster\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version, e.g. \"2.0.0\"."
+    },
+    "clusterName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "clusterType": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "providerShares": {
+      "type": "array",
+      "items": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "description": "Market/dependency share per provider (for HHI)."
+    },
+    "hhi": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Herfindahl-Hirschman concentration index (normalized 0..1)."
+    },
+    "blastRadius": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraction of the estate affected if the cluster fails."
+    },
+    "timeToRecover": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Normalized recovery time (0=fast, 1=slow)."
+    },
+    "exitDifficulty": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "How hard it is to switch away (lock-in)."
+    },
+    "residualCommonMode": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Residual common-mode risk after resilience controls."
+    },
+    "rating": {
+      "type": "string",
+      "enum": [
+        "Low",
+        "Medium",
+        "High",
+        "Critical"
+      ]
+    }
+  }
+}

schemas/RiskIndicator.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RiskIndicator.json",
+  "title": "RiskIndicator",
+  "description": "A key risk indicator (KRI) or key control indicator (KCI) with green/amber/red thresholds, tracked against risk appetite.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "indicatorType",
+    "metric"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:risk-indicator:",
+      "description": "Stable URN. Pattern: urn:srcos:risk-indicator:<local-id>"
+    },
+    "type": {
+      "const": "RiskIndicator",
+      "description": "Discriminator — always \"RiskIndicator\"."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version, e.g. \"2.0.0\"."
+    },
+    "indicatorType": {
+      "type": "string",
+      "enum": [
+        "KRI",
+        "KCI"
+      ]
+    },
+    "metric": {
+      "type": "string",
+      "minLength": 1
+    },
+    "definition": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "value": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "green": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "amber": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "red": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "band": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "green",
+        "amber",
+        "red",
+        null
+      ]
+    },
+    "frequency": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "owner": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}