sprints work

2025-12-25 12:19:12 +02:00
parent 223843f1d1
commit 2a06f780cf
224 changed files with 41796 additions and 1515 deletions
--- a/docs/modules/policy/budget-attestation.md
+++ b/docs/modules/policy/budget-attestation.md
@@ -0,0 +1,191 @@
+# Budget Threshold Attestation
+
+This document describes how unknown budget thresholds are attested in verdict bundles for reproducibility and audit purposes.
+
+## Overview
+
+Budget attestation captures the budget configuration applied during policy evaluation, enabling:
+
+- **Auditability**: Verify what thresholds were enforced at decision time
+- **Reproducibility**: Include all inputs for deterministic verification
+- **Compliance**: Demonstrate policy enforcement for regulatory requirements
+
+## Budget Check Predicate
+
+The budget check is included in the verdict predicate:
+
+```json
+{
+  "_type": "https://stellaops.dev/predicates/policy-verdict@v1",
+  "tenantId": "tenant-1",
+  "policyId": "default-policy",
+  "policyVersion": 1,
+  "verdict": { ... },
+  "budgetCheck": {
+    "environment": "production",
+    "config": {
+      "maxUnknownCount": 10,
+      "maxCumulativeUncertainty": 2.5,
+      "action": "warn",
+      "reasonLimits": {
+        "Reachability": 5,
+        "Identity": 3
+      }
+    },
+    "actualCounts": {
+      "total": 3,
+      "cumulativeUncertainty": 1.2,
+      "byReason": {
+        "Reachability": 2,
+        "Identity": 1
+      }
+    },
+    "result": "pass",
+    "configHash": "sha256:abc123...",
+    "evaluatedAt": "2025-12-25T12:00:00Z",
+    "violations": []
+  }
+}
+```
+
+## Fields
+
+### budgetCheck.config
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `maxUnknownCount` | int | Maximum total unknowns allowed |
+| `maxCumulativeUncertainty` | double | Maximum uncertainty score |
+| `action` | string | Action when exceeded: warn, block |
+| `reasonLimits` | object | Per-reason code limits |
+
+### budgetCheck.actualCounts
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | int | Total unknowns observed |
+| `cumulativeUncertainty` | double | Sum of uncertainty factors |
+| `byReason` | object | Breakdown by reason code |
+
+### budgetCheck.result
+
+Possible values:
+- `pass` - All limits satisfied
+- `warn` - Limits exceeded but action is warn
+- `fail` - Limits exceeded and action is block
+
+### budgetCheck.configHash
+
+SHA-256 hash of the budget configuration for determinism verification. Format: `sha256:{64 hex characters}`
+
+### budgetCheck.violations
+
+List of violations when limits are exceeded:
+
+```json
+{
+  "violations": [
+    {
+      "type": "total",
+      "limit": 10,
+      "actual": 15
+    },
+    {
+      "type": "reason",
+      "limit": 5,
+      "actual": 8,
+      "reason": "Reachability"
+    }
+  ]
+}
+```
+
+## Usage
+
+### Extracting Budget Check from Verdict
+
+```csharp
+using StellaOps.Policy.Engine.Attestation;
+
+// Parse verdict predicate from DSSE envelope
+var predicate = VerdictPredicate.Parse(dssePayload);
+
+// Access budget check
+if (predicate.BudgetCheck is not null)
+{
+    var check = predicate.BudgetCheck;
+    Console.WriteLine($"Environment: {check.Environment}");
+    Console.WriteLine($"Result: {check.Result}");
+    Console.WriteLine($"Total: {check.ActualCounts.Total}/{check.Config.MaxUnknownCount}");
+    Console.WriteLine($"Config Hash: {check.ConfigHash}");
+}
+```
+
+### Verifying Configuration Hash
+
+```csharp
+// Compute expected hash from current configuration
+var currentConfig = new VerdictBudgetConfig(
+    maxUnknownCount: 10,
+    maxCumulativeUncertainty: 2.5,
+    action: "warn");
+
+var expectedHash = VerdictBudgetCheck.ComputeConfigHash(currentConfig);
+
+// Compare with attested hash
+if (predicate.BudgetCheck?.ConfigHash != expectedHash)
+{
+    Console.WriteLine("Warning: Budget configuration has changed since attestation");
+}
+```
+
+## Determinism
+
+The config hash ensures reproducibility:
+
+1. Configuration is serialized to JSON with canonical ordering
+2. SHA-256 is computed over the UTF-8 bytes
+3. Hash is prefixed with `sha256:` algorithm identifier
+
+This allows verification that the same budget configuration was used across runs.
+
+## Integration Points
+
+### VerdictPredicateBuilder
+
+Budget check is added when building verdict predicates:
+
+```csharp
+var budgetCheck = new VerdictBudgetCheck(
+    environment: context.Environment,
+    config: config,
+    actualCounts: counts,
+    result: budgetResult.Passed ? "pass" : budgetResult.Budget.Action.ToString(),
+    configHash: VerdictBudgetCheck.ComputeConfigHash(config),
+    evaluatedAt: DateTimeOffset.UtcNow,
+    violations: violations);
+
+var predicate = new VerdictPredicate(
+    tenantId: trace.TenantId,
+    policyId: trace.PolicyId,
+    // ... other fields
+    budgetCheck: budgetCheck);
+```
+
+### UnknownBudgetService
+
+The enhanced `BudgetCheckResult` includes all data needed for attestation:
+
+```csharp
+var result = await budgetService.CheckBudget(environment, unknowns);
+
+// result.Budget - the configuration applied
+// result.CountsByReason - breakdown for attestation
+// result.CumulativeUncertainty - total uncertainty score
+```
+
+## Related Documentation
+
+- [Unknown Budget Gates](./unknowns-budget-gates.md)
+- [Verdict Attestations](../attestor/verdict-format.md)
+- [BudgetCheckPredicate Model](../../api/attestor/budget-check-predicate.md)