# Unknowns System (First-Class State, Budget Enforcement, Registry, Attestation Binding)

## Module
Attestor

## Status
VERIFIED

## Description
Full unknowns tracking as first-class state: dedicated module with budget enforcement, ranking, taxonomy, budget-exceeded event publishing, IUnknownsAggregator interface, and UnknownItem records. Registry with trust-decay scoring, repository persistence, and ProofChain aggregation. Unknowns cryptographically bound to attestations via uncertainty statements, budget predicates, and JSON schemas. UI components for unknowns queue and budget widgets.

## Implementation Details
- **IUnknownsAggregator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Services/IUnknownsAggregator.cs` -- interface for aggregating unknown items across scan results and evidence gaps.
- **UnknownsAggregator**: `Services/UnknownsAggregator.cs` -- concrete implementation that collects, deduplicates, and ranks unknown items.
- **UnknownItem**: `Services/UnknownItem.cs` -- individual unknown item record with source, severity, category, and first-seen timestamp.
- **Budget Check Result**: `Services/BudgetCheckResult.cs` -- result of checking aggregated unknowns against budget thresholds.
- **Budget Violation**: `Services/BudgetViolation.cs` -- violation record when unknowns exceed budget limits.
- **Exception Ref**: `Services/ExceptionRef.cs` -- reference to an approved exception that excludes an unknown from budget enforcement.
- **Unknowns Budget Predicate**: `Predicates/UnknownsBudgetPredicate.cs` -- attestation predicate binding unknowns state to the proof chain.
- **Uncertainty Statement**: `Statements/UncertaintyStatement.cs` -- in-toto statement wrapping uncertainty evidence for attestation.
- **Uncertainty State Entry**: `Statements/UncertaintyStateEntry.cs` -- per-finding uncertainty state entry.
- **Uncertainty Evidence**: `Statements/UncertaintyEvidence.cs` -- evidence contributing to the uncertainty measurement.
- **Budget Definition**: `Statements/BudgetDefinition.cs` -- threshold definitions for unknowns budget enforcement.
- **Budget Observation**: `Statements/BudgetObservation.cs` -- observed unknowns counts at a point in time.
- **Budget Violation Entry**: `Statements/BudgetViolationEntry.cs` -- recorded violation when budget is exceeded.
- **Budget Exception Entry**: `Statements/BudgetExceptionEntry.cs` -- approved exception entry.
- **Predicate Schema Validator**: `Json/PredicateSchemaValidator.cs` -- validates unknowns predicates against JSON schemas.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/`

## E2E Test Plan
- [ ] Aggregate 10 unknown items via `UnknownsAggregator` from different sources and verify deduplication by source+CVE key
- [ ] Verify unknowns ranking: add items with varying severities and confirm they are ordered by severity (critical first)
- [ ] Set a budget (max_critical=3) and aggregate 5 critical unknowns; verify `BudgetCheckResult` reports violation
- [ ] Register an `ExceptionRef` for one critical unknown and verify budget count drops to 4 critical
- [ ] Build an `UnknownsBudgetPredicate` from aggregated unknowns and verify it contains correct item counts and budget status
- [ ] Create an `UncertaintyStatement` from unknowns and verify it is a valid in-toto statement with the correct predicate type URI
- [ ] Validate the unknowns predicate against `PredicateSchemaValidator` and verify it passes schema validation
- [ ] Aggregate unknowns from an empty scan and verify the aggregator returns zero items with a passing budget check

## 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 |