NODEDC_1C/docs/HARD_SEMANTIC/risk_engine_spec.md

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