Initial import NDC_1C

docs/risk_engine_spec.md

@@ -0,0 +1,74 @@
+# Risk Engine Spec (Layer 6 MVP)
+
+Date: 2026-03-23  
+Status: implemented in `canonical_layer/risk.py`
+
+## 1. Purpose
+
+Transform anomaly signals into explainable risk patterns and a global risk score.
+
+## 2. Inputs
+
+- `feature_runs` (latest successful run context)
+- `anomaly_signals` for selected feature run
+- optional explicit `source_feature_run_id`
+
+## 3. Outputs
+
+### `risk_runs`
+
+Execution journal for each risk-scoring run:
+
+- status, timestamps
+- source feature run
+- patterns written
+- global score
+- details/error
+
+### `risk_patterns`
+
+Explainable risk patterns:
+
+- `pattern_key`
+- `severity`
+- `scope`, `scope_id`
+- `score`, `confidence`
+- `details` (breakdown + evidence examples)
+- `is_active`
+
+Always includes:
+
+- `global_risk_summary`
+
+## 4. Domain mapping
+
+Anomaly signal → risk domain:
+
+- `stale_refresh`, `missing_refresh_baseline`, `no_canonical_data` → `operational_freshness`
+- `high_link_degree` → `suspicious_link_hub`
+- `entity_count_drift` → `structural_drift`
+- `empty_display_share_high` → `data_quality`
+- unknown → `miscellaneous`
+
+## 5. Scoring model (MVP)
+
+1. Convert each anomaly to normalized signal score.
+2. Aggregate per domain into domain risk pattern.
+3. Compute global weighted score over domains.
+4. Map score to severity via thresholds:
+   - `RISK_MEDIUM_THRESHOLD`
+   - `RISK_HIGH_THRESHOLD`
+
+## 6. Runtime interfaces
+
+API:
+
+- `POST /risk/run`
+- `GET /risk/stats`
+- `GET /risk/runs`
+- `GET /risk/patterns`
+
+CLI:
+
+- `python scripts/run_risk.py`
+- `powershell scripts/run_risk.ps1`