# Uncertainty Budget System (Schema, Predicates, Violation Tracking)

## Module
Attestor

## Status
VERIFIED

## Description
Full backend schema for uncertainty budgets: budget payloads, violation predicates, check results, exception references, and JSON schema validation with test coverage.

## Implementation Details
- **Uncertainty Budget Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/UncertaintyBudgetPayload.cs` -- payload containing budget definitions, observations, and violation entries for a given subject.
- **Uncertainty Budget Statement**: `Statements/UncertaintyBudgetStatement.cs` -- in-toto statement wrapping the uncertainty budget payload.
- **Uncertainty Payload**: `Statements/UncertaintyPayload.cs` -- payload for individual uncertainty measurements.
- **Uncertainty Statement**: `Statements/UncertaintyStatement.cs` -- in-toto statement wrapping uncertainty evidence.
- **Uncertainty Evidence**: `Statements/UncertaintyEvidence.cs` -- evidence items contributing to uncertainty (e.g., missing scan data, stale SBOM).
- **Uncertainty State Entry**: `Statements/UncertaintyStateEntry.cs` -- per-finding uncertainty state tracking.
- **Budget Definition**: `Statements/BudgetDefinition.cs` -- defines budget thresholds (max critical unknowns, max total unknowns).
- **Budget Observation**: `Statements/BudgetObservation.cs` -- observed budget consumption at a point in time.
- **Budget Exception Entry**: `Statements/BudgetExceptionEntry.cs` -- approved exceptions that exclude specific unknowns from budget counting.
- **Budget Violation Entry**: `Statements/BudgetViolationEntry.cs` -- records when a budget threshold is exceeded.
- **Budget Violation Predicate**: `Predicates/BudgetViolationPredicate.cs` -- predicate for budget violations attached to attestations.
- **Budget Check Predicate**: `Predicates/BudgetCheckPredicate.cs` -- predicate for budget check results.
- **Budget Check Result (Predicate)**: `Predicates/BudgetCheckResult.cs` -- result of checking actuals against budget limits.
- **Budget Config**: `Predicates/BudgetConfig.cs` -- budget configuration (limits per severity level).
- **Budget Actual Counts**: `Predicates/BudgetActualCounts.cs` -- actual observed counts per severity.
- **Budget Violation (Predicate)**: `Predicates/BudgetViolation.cs` -- individual violation entry within a predicate.
- **Unknowns Budget Predicate**: `Predicates/UnknownsBudgetPredicate.cs` -- predicate linking unknowns aggregation to budget enforcement.
- **Budget Check Result (Service)**: `Services/BudgetCheckResult.cs` -- service-layer result for budget checks.
- **Budget Violation (Service)**: `Services/BudgetViolation.cs` -- service-layer violation details.
- **Exception Ref**: `Services/ExceptionRef.cs` -- reference to an approved budget exception.
- **Predicate Schema Validator**: `Json/PredicateSchemaValidator.cs` (with `.Validators`, `.DeltaValidators`) -- validates uncertainty/budget predicates against JSON schemas.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/`

## E2E Test Plan
- [ ] Create an `UncertaintyBudgetPayload` with a `BudgetDefinition` (max_critical=5, max_total=20) and verify it serializes correctly
- [ ] Add `BudgetObservation` entries showing actual counts (critical=3, total=15) and verify `BudgetCheckResult` reports within budget
- [ ] Add observations exceeding the budget (critical=7) and verify `BudgetViolationPredicate` is generated with the correct violation details
- [ ] Register a `BudgetExceptionEntry` for a specific CVE and verify it is excluded from budget counting
- [ ] Validate an uncertainty budget predicate against `PredicateSchemaValidator` and verify it passes schema validation
- [ ] Create a malformed budget predicate (missing required fields) and verify schema validation fails with specific error messages
- [ ] Build an `UncertaintyBudgetStatement` and verify it wraps the payload as a valid in-toto statement with correct predicate type
- [ ] Verify `UncertaintyEvidence` items are ordered deterministically within the `UncertaintyPayload`

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source Verification | PASS |
| Tier 1 - Build + Code Review | PASS |
| Tier 2 - Behavioral Verification | PASS |
| Verified Date | 2026-02-13 |
| Run ID | run-001 |