save checkpoint

docs/features/checked/attestor/unknowns-system.md

@@ -0,0 +1,48 @@
+# 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 |