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/architecture.md
+++ b/docs/modules/policy/architecture.md
@@ -177,6 +177,70 @@ Determinization scores are exposed to SPL policies via the `signals.trust.*` and

 EWS weights are externalized to versioned JSON manifests in `etc/weights/`. The unified score facade (`IUnifiedScoreService`) loads weights from these manifests rather than using compiled defaults, enabling auditable weight changes without code modifications. See [Unified Score Architecture](../../technical/scoring-algebra.md) §4 for manifest schema and versioning rules.

+### 3.1.1 · Trust Score Algebra Facade
+
+The **TrustScoreAlgebraFacade** (`ITrustScoreAlgebraFacade`) provides a unified entry point composing TrustScoreAggregator + K4Lattice + ScorePolicy into a single deterministic scoring pipeline.
+
+```csharp
+public interface ITrustScoreAlgebraFacade
+{
+    Task<TrustScoreResult> ComputeTrustScoreAsync(TrustScoreRequest request, CancellationToken ct);
+    TrustScoreResult ComputeTrustScore(TrustScoreRequest request);
+}
+```
+
+**Pipeline steps:**
+1. Calculate uncertainty entropy from signal snapshot
+2. Aggregate weighted signal scores via TrustScoreAggregator
+3. Compute K4 lattice verdict (Unknown/True/False/Conflict)
+4. Extract dimension scores (BaseSeverity, Reachability, Evidence, Provenance)
+5. Compute weighted final score in basis points (0-10000)
+6. Determine risk tier (Info/Low/Medium/High/Critical)
+7. Produce Score.v1 predicate for DSSE attestation
+
+**Score.v1 Predicate Format:**
+
+All numeric scores use **basis points (0-10000)** for bit-exact determinism:
+
+```json
+{
+  "predicateType": "https://stella-ops.org/predicates/score/v1",
+  "artifactId": "pkg:maven/com.example/mylib@1.0.0",
+  "vulnerabilityId": "CVE-2024-1234",
+  "trustScoreBps": 7250,
+  "tier": "High",
+  "latticeVerdict": "True",
+  "uncertaintyBps": 2500,
+  "dimensions": {
+    "baseSeverityBps": 5000,
+    "reachabilityBps": 10000,
+    "evidenceBps": 6000,
+    "provenanceBps": 8000,
+    "epssBps": 3500,
+    "vexBps": 10000
+  },
+  "weightsUsed": {
+    "baseSeverity": 1000,
+    "reachability": 4500,
+    "evidence": 3000,
+    "provenance": 1500
+  },
+  "policyDigest": "sha256:abc123...",
+  "computedAt": "2026-01-15T12:00:00Z",
+  "tenantId": "tenant-123"
+}
+```
+
+**Risk Tier Mapping:**
+
+| Score (bps) | Tier |
+|-------------|------|
+| ≥ 9000 | Critical |
+| ≥ 7000 | High |
+| ≥ 4000 | Medium |
+| ≥ 1000 | Low |
+| < 1000 | Info |
+
 ### 3.2 - License compliance configuration

 License compliance evaluation runs during SBOM evaluation when enabled in
@@ -871,6 +935,7 @@ The Interop Layer provides bidirectional policy exchange between Stella's native
 | Format | Schema | Direction | Notes |
 |--------|--------|-----------|-------|
 | **PolicyPack v2 (JSON)** | `policy.stellaops.io/v2` | Import + Export | Canonical format with typed gates, environment overrides, remediation hints |
+| **PolicyPack v2 (YAML)** | `policy.stellaops.io/v2` | Import + Export | Deterministic YAML with sorted keys; YAML→JSON roundtrip for validation |
 | **OPA/Rego** | `package stella.release` | Export (+ Import with pattern matching) | Deny-by-default pattern, `remediation` output rules |

 ### 13.2 · Architecture
@@ -878,8 +943,9 @@ The Interop Layer provides bidirectional policy exchange between Stella's native
 ```mermaid
 graph TD
    subgraph Interop["StellaOps.Policy.Interop"]
-        Exporter[JsonPolicyExporter / RegoPolicyExporter]
-        Importer[JsonPolicyImporter / RegoPolicyImporter]
+        Exporter[JsonPolicyExporter / YamlPolicyExporter / RegoPolicyExporter]
+        Importer[JsonPolicyImporter / YamlPolicyImporter / RegoPolicyImporter]
+        DiffMerge[PolicyDiffMergeEngine]
        Validator[PolicySchemaValidator]
        Generator[RegoCodeGenerator]
        Resolver[RemediationResolver]
@@ -887,7 +953,7 @@ graph TD
        Detector[FormatDetector]
    end
    subgraph Consumers
-        CLI[stella policy export/import/validate/evaluate]
+        CLI[stella policy export/import/validate/evaluate/diff/merge]
        API[Platform API /api/v1/policy/interop]
        UI[Policy Editor UI]
    end
@@ -895,9 +961,11 @@ graph TD
    CLI --> Exporter
    CLI --> Importer
    CLI --> Validator
+    CLI --> DiffMerge
    API --> Exporter
    API --> Importer
    API --> Validator
+    API --> DiffMerge
    UI --> API

    Exporter --> Generator
@@ -946,7 +1014,51 @@ All exports and evaluations are deterministic:
 - No time-dependent logic in deterministic mode
 - `outputDigest` in evaluation results enables replay verification

-### 13.6 · Implementation Reference
+### 13.6 · YAML Format Support
+
+> **Sprint:** SPRINT_20260208_048_Policy_policy_interop_framework
+
+YAML export/import operates on the same `PolicyPackDocument` model as JSON. The YAML format is useful for human-editable policy files and GitOps workflows.
+
+**Export** (`YamlPolicyExporter : IPolicyYamlExporter`):
+- Converts `PolicyPackDocument` to a `SortedDictionary` intermediate for deterministic key ordering
+- Serializes via YamlDotNet (CamelCaseNamingConvention, DisableAliases, OmitNull)
+- Produces SHA-256 digest for replay verification
+- Supports environment filtering and remediation stripping (same options as JSON)
+
+**Import** (`YamlPolicyImporter`):
+- Deserializes YAML via YamlDotNet, then re-serializes as JSON
+- Delegates to `JsonPolicyImporter` for validation (apiVersion, kind, duplicate gates/rules)
+- Errors: `YAML_PARSE_ERROR`, `YAML_EMPTY`, `YAML_CONVERSION_ERROR`
+
+**Format Detection** (`FormatDetector`):
+- Content-based: detects `apiVersion:`, `---`, `kind:` patterns
+- Extension-based: `.yaml`, `.yml` → `PolicyFormats.Yaml`
+
+### 13.7 · Policy Diff/Merge Engine
+
+> **Sprint:** SPRINT_20260208_048_Policy_policy_interop_framework
+
+The `PolicyDiffMergeEngine` (`IPolicyDiffMerge`) compares and merges `PolicyPackDocument` instances structurally.
+
+**Diff** produces `PolicyDiffResult` containing:
+- Changes to metadata (name, version, description)
+- Changes to settings (defaultAction, unknownsThreshold, stopOnFirstFailure, deterministicMode)
+- Gate changes (by ID): added, removed, modified (action, type, config diffs)
+- Rule changes (by Name): added, removed, modified (action, match diffs)
+- Summary with counts of added/removed/modified and `HasChanges` flag
+
+**Merge** applies one of three strategies via `PolicyMergeStrategy`:
+
+| Strategy | Behavior |
+|----------|----------|
+| `OverlayWins` | Overlay values take precedence on conflict |
+| `BaseWins` | Base values take precedence on conflict |
+| `FailOnConflict` | Returns error with conflict details |
+
+Merge output includes the merged `PolicyPackDocument` and a list of `PolicyMergeConflict` items (path, base value, overlay value).
+
+### 13.8 · Implementation Reference

 | Component | Source File |
 |-----------|-------------|
@@ -954,18 +1066,22 @@ All exports and evaluations are deterministic:
 | Remediation Models | `src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/RemediationModels.cs` |
 | Interfaces | `src/Policy/__Libraries/StellaOps.Policy.Interop/Abstractions/` |
 | JSON Exporter | `src/Policy/__Libraries/StellaOps.Policy.Interop/Export/JsonPolicyExporter.cs` |
+| YAML Exporter | `src/Policy/__Libraries/StellaOps.Policy.Interop/Export/YamlPolicyExporter.cs` |
 | JSON Importer | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/JsonPolicyImporter.cs` |
+| YAML Importer | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/YamlPolicyImporter.cs` |
 | Rego Generator | `src/Policy/__Libraries/StellaOps.Policy.Interop/Rego/RegoCodeGenerator.cs` |
 | Rego Importer | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/RegoPolicyImporter.cs` |
+| Diff/Merge Engine | `src/Policy/__Libraries/StellaOps.Policy.Interop/DiffMerge/PolicyDiffMergeEngine.cs` |
 | Embedded OPA | `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/EmbeddedOpaEvaluator.cs` |
 | Remediation Resolver | `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/RemediationResolver.cs` |
 | Format Detector | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/FormatDetector.cs` |
 | Schema Validator | `src/Policy/__Libraries/StellaOps.Policy.Interop/Validation/PolicySchemaValidator.cs` |
+| DI Registration | `src/Policy/__Libraries/StellaOps.Policy.Interop/DependencyInjection/PolicyInteropServiceCollectionExtensions.cs` |
 | CLI Commands | `src/Cli/StellaOps.Cli/Commands/Policy/PolicyInteropCommandGroup.cs` |
 | Platform API | `src/Platform/StellaOps.Platform.WebService/Endpoints/PolicyInteropEndpoints.cs` |
 | JSON Schema | `docs/schemas/policy-pack-v2.schema.json` |

-### 13.7 · CLI Interface
+### 13.9 · CLI Interface

 ```bash
 # Export to Rego
@@ -983,7 +1099,7 @@ stella policy evaluate --policy baseline.json --input evidence.json --environmen

 Exit codes: `0` = success/allow, `1` = warn, `2` = block/errors, `10` = input-error, `12` = policy-error.

-### 13.8 · Platform API
+### 13.10 · Platform API

 Group: `/api/v1/policy/interop` with tag `PolicyInterop`

@@ -995,7 +1111,7 @@ Group: `/api/v1/policy/interop` with tag `PolicyInterop`
 | POST | `/evaluate` | `platform.policy.evaluate` | Evaluate policy against input |
 | GET | `/formats` | `platform.policy.read` | List supported formats |

-### 13.9 · OPA Supply Chain Evidence Input
+### 13.11 · OPA Supply Chain Evidence Input

 > **Sprint:** SPRINT_0129_001_Policy_supply_chain_evidence_input

@@ -1061,4 +1177,107 @@ allow {

 ---

-*Last updated: 2026-01-29 (Sprint 0129_001).*
+*Last updated: 2026-02-09 (Sprint 049 — Proof Studio UX).*
+
+## 14 · Proof Studio (Explainable Confidence Scoring)
+
+The Proof Studio UX provides visual, auditable evidence chains for every verdict decision. It bridges existing verdict rationale, score explanation, and counterfactual simulation data into composable views.
+
+### 14.1 · Library Layout
+
+```
+StellaOps.Policy.Explainability/
+├── VerdictRationale.cs              # 4-line structured rationale model
+├── VerdictRationaleRenderer.cs      # Content-addressed render (text/md/JSON)
+├── IVerdictRationaleRenderer.cs     # Renderer interface
+├── ProofGraphModels.cs              # Proof graph DAG types
+├── ProofGraphBuilder.cs             # Deterministic graph builder
+├── ScoreBreakdownDashboard.cs       # Score breakdown dashboard model
+├── ProofStudioService.cs            # Composition + counterfactual integration
+├── ServiceCollectionExtensions.cs   # DI registration
+└── GlobalUsings.cs
+```
+
+### 14.2 · Proof Graph
+
+A proof graph is a directed acyclic graph (DAG) that visualizes the complete evidence chain from source artifacts to a final verdict decision.
+
+| Node Type | Depth | Purpose |
+|---|---|---|
+| `Verdict` | 0 | Root: the final verdict + composite score |
+| `PolicyRule` | 1 | Policy clause that triggered the decision |
+| `Guardrail` | 1 | Score guardrail (cap/floor) that modified the score |
+| `ScoreComputation` | 2 | Per-factor score contribution |
+| `ReachabilityAnalysis` | 3 | Reachability evidence leaf |
+| `VexStatement` | 3 | VEX attestation leaf |
+| `Provenance` | 3 | Provenance attestation leaf |
+| `SbomEvidence` | 3 | SBOM evidence leaf |
+| `RuntimeSignal` | 3 | Runtime detection signal leaf |
+| `AdvisoryData` | 3 | Advisory data leaf |
+| `Counterfactual` | 0 | What-if hypothesis (overlay) |
+
+Edge relations: `ProvidesEvidence`, `ContributesScore`, `Gates`, `Attests`, `Overrides`, `GuardrailApplied`.
+
+Graph IDs are content-addressed (`pg:sha256:...`) from deterministic sorting of node and edge identifiers.
+
+### 14.3 · Score Breakdown Dashboard
+
+The `ScoreBreakdownDashboard` exposes per-factor contributions with weighted contributions and percentages:
+
+```
+ScoreBreakdownDashboard
+├── CompositeScore (int)
+├── ActionBucket (string)
+├── Factors[] → FactorContribution
+│   ├── FactorId / FactorName
+│   ├── RawScore, Weight → WeightedContribution (computed)
+│   ├── Confidence, IsSubtractive
+│   └── PercentageOfTotal
+├── GuardrailsApplied[] → GuardrailApplication
+│   ├── ScoreBefore → ScoreAfter
+│   └── Reason, Conditions
+├── PreGuardrailScore
+├── Entropy
+└── NeedsReview
+```
+
+### 14.4 · Counterfactual Explorer
+
+The `AddCounterfactualOverlay()` method on `IProofGraphBuilder` adds hypothetical nodes to an existing proof graph. A `CounterfactualScenario` specifies factor overrides (factorId → hypothetical score) and an optional resulting composite score. The overlay:
+
+1. Creates a `Counterfactual` node at depth 0 with the scenario label.
+2. Connects overridden factor score nodes to the counterfactual node via `Overrides` edges.
+3. Recomputes the content-addressed graph ID, making each scenario distinctly identifiable.
+
+### 14.5 · Proof Studio Service (Integration)
+
+The `IProofStudioService` is the primary integration surface:
+
+| Method | Input | Output |
+|---|---|---|
+| `Compose(request)` | `ProofStudioRequest` (rationale + optional score factors + guardrails) | `ProofStudioView` (proof graph + optional score breakdown) |
+| `ApplyCounterfactual(view, scenario)` | Existing view + `CounterfactualScenario` | Updated view with overlay |
+
+The service bridges `ScoreFactorInput` (from scoring engine) to `FactorContribution` models and formats factor names for UI display.
+
+### 14.6 · DI Registration
+
+```csharp
+services.AddVerdictExplainability();
+// Registers:
+//   IVerdictRationaleRenderer → VerdictRationaleRenderer
+//   IProofGraphBuilder → ProofGraphBuilder
+//   IProofStudioService → ProofStudioService
+```
+
+### 14.7 · OTel Metrics
+
+| Metric | Type | Description |
+|---|---|---|
+| `stellaops.proofstudio.views_composed_total` | Counter | Proof studio views composed |
+| `stellaops.proofstudio.counterfactuals_applied_total` | Counter | Counterfactual scenarios applied |
+
+### 14.8 · Tests
+
+- `ProofGraphBuilderTests.cs` — 18 tests (graph construction, determinism, depth hierarchy, critical paths, counterfactual overlay, edge cases)
+- `ProofStudioServiceTests.cs` — 10 tests (compose, score breakdown, guardrails, counterfactual, DI resolution)