partly or unimplemented features - now implemented

2026-02-09 08:53:51 +02:00
parent 1bf6bbf395
commit 4bdc298ec1
674 changed files with 90194 additions and 2271 deletions
--- a/docs/modules/policy/determinization-api.md
+++ b/docs/modules/policy/determinization-api.md
@@ -429,3 +429,151 @@ Policy:
        MinConfidence: 0.75
        MaxEntropy: 0.3
 ```
+
+---
+
+## 13. Delta-If-Present Calculations (TSF-004)
+
+> **Sprint:** SPRINT_20260208_043_Policy_delta_if_present_calculations_for_missing_signals
+
+The Delta-If-Present API provides "what-if" analysis for missing signals, showing hypothetical score changes if specific evidence were obtained.
+
+### 13.1 Purpose
+
+When making release decisions with incomplete evidence, operators need to understand:
+- **Gap prioritization:** Which missing signals would have the most impact?
+- **Score bounds:** What is the possible range of trust scores given current gaps?
+- **Risk simulation:** What would the score be if a missing signal had a specific value?
+
+### 13.2 API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/policy/delta-if-present/signal` | POST | Calculate delta for a single signal |
+| `/api/v1/policy/delta-if-present/analysis` | POST | Full gap analysis with prioritization |
+| `/api/v1/policy/delta-if-present/bounds` | POST | Calculate min/max score bounds |
+
+### 13.3 Single Signal Delta
+
+Calculate hypothetical score change for one missing signal:
+
+**Request:**
+```json
+{
+  "snapshot": {
+    "cve": "CVE-2024-1234",
+    "purl": "pkg:maven/org.example/lib@1.0.0",
+    "vex": { "state": "not_queried" },
+    "epss": { "state": "not_queried" },
+    "reachability": {
+      "state": "queried",
+      "value": { "status": "Reachable", "analyzed_at": "2026-01-15T00:00:00Z" }
+    },
+    "runtime": { "state": "not_queried" },
+    "backport": { "state": "not_queried" },
+    "sbom": {
+      "state": "queried",
+      "value": { "sbom_digest": "sha256:abc", "format": "SPDX" }
+    }
+  },
+  "signal_name": "VEX",
+  "assumed_value": 0.0
+}
+```
+
+**Response:**
+```json
+{
+  "signal": "VEX",
+  "current_score": 0.65,
+  "hypothetical_score": 0.52,
+  "score_delta": -0.13,
+  "assumed_value": 0.0,
+  "signal_weight": 0.25,
+  "current_entropy": 0.60,
+  "hypothetical_entropy": 0.35,
+  "entropy_delta": -0.25
+}
+```
+
+### 13.4 Full Gap Analysis
+
+Analyze all missing signals with best/worst/prior cases:
+
+**Response:**
+```json
+{
+  "cve": "CVE-2024-1234",
+  "purl": "pkg:maven/org.example/lib@1.0.0",
+  "current_score": 0.65,
+  "current_entropy": 0.60,
+  "gap_analysis": [
+    {
+      "signal": "VEX",
+      "gap_reason": "NotQueried",
+      "best_case": {
+        "assumed_value": 0.0,
+        "hypothetical_score": 0.52,
+        "score_delta": -0.13
+      },
+      "worst_case": {
+        "assumed_value": 1.0,
+        "hypothetical_score": 0.77,
+        "score_delta": 0.12
+      },
+      "prior_case": {
+        "assumed_value": 0.5,
+        "hypothetical_score": 0.64,
+        "score_delta": -0.01
+      },
+      "max_impact": 0.25
+    }
+  ],
+  "prioritized_gaps": ["VEX", "Reachability", "EPSS", "Runtime", "Backport", "SBOMLineage"],
+  "computed_at": "2026-01-15T12:00:00Z"
+}
+```
+
+### 13.5 Score Bounds
+
+Calculate the possible range of trust scores:
+
+**Response:**
+```json
+{
+  "cve": "CVE-2024-1234",
+  "purl": "pkg:maven/org.example/lib@1.0.0",
+  "current_score": 0.65,
+  "current_entropy": 0.60,
+  "minimum_score": 0.35,
+  "maximum_score": 0.85,
+  "range": 0.50,
+  "gap_count": 4,
+  "missing_weight_percentage": 65.0,
+  "computed_at": "2026-01-15T12:00:00Z"
+}
+```
+
+### 13.6 Signal Weights
+
+Default signal weights used in delta calculations:
+
+| Signal | Weight | Default Prior |
+|--------|--------|---------------|
+| VEX | 0.25 | 0.5 |
+| Reachability | 0.25 | 0.5 |
+| EPSS | 0.15 | 0.3 |
+| Runtime | 0.15 | 0.3 |
+| Backport | 0.10 | 0.5 |
+| SBOMLineage | 0.10 | 0.5 |
+
+Custom weights can be passed in requests to override defaults.
+
+### 13.7 Use Cases
+
+1. **Evidence Prioritization:** Determine which signals to acquire first based on maximum impact
+2. **Risk Bounding:** Understand worst-case score before making release decisions
+3. **Sensitivity Analysis:** Explore how different evidence values would affect outcomes
+4. **Operator Guidance:** Help operators focus collection efforts on high-impact signals
+5. **Audit Trail:** Document "what-if" analysis as part of release decision rationale
+