# Unknowns Registry

**Status:** Implemented
**Source:** `src/Unknowns/`
**Owner:** Signals Guild, Policy Guild

## Purpose

The Unknowns Registry provides bitemporal ambiguity tracking for security scan gaps where reachability or applicability cannot be determined with confidence. It models Unknown-Reachable and Unknown-Unreachable states as first-class risk signals, enabling uncertainty-aware scoring and triage prioritization.

## Components

**Services:**
- Unknowns registry and tracking service
- Integration with Policy Engine for risk scoring
- Signals correlation for unknowns decay

**Libraries:**
- `StellaOps.Policy.Unknowns` - Unknowns budget and scoring logic
- Unknown state modeling and confidence tracking

## Key Features

- **First-class Unknown state:** Explicit modeling of uncertainty (not hidden as false negatives)
- **Bitemporal tracking:** Valid-time and transaction-time for ambiguity windows
- **Risk scoring integration:** `unknowns_pressure` factor in Policy Engine
- **Decay heuristics:** Unknowns decay over time with configurable policies
- **Triage queue:** Dedicated UI view for unknowns requiring investigation
- **Confidence budgets:** Policy gates can enforce maximum acceptable unknowns

## Configuration

**Unknowns Budget Options** (`UnknownBudgetOptions.cs`):
- Maximum unknowns threshold per finding
- Decay policies and timeouts
- Scoring weight multipliers

**Unknowns Decay Options** (`UnknownsDecayOptions.cs`):
- Decay curve parameters
- Confidence floor values
- Re-evaluation triggers

**Unknowns Rescan Options** (`UnknownsRescanOptions.cs`):
- Automatic rescan scheduling
- Priority queue management

## Integration Points

**Policy Engine:**
- Unknowns budget gate enforcement
- Confidence-based disposition selection
- Risk score adjustments based on unknowns count

**Signals:**
- Runtime signal correlation can resolve unknowns
- Automatic unknowns decay on new evidence

**UI:**
- Unknowns chips in findings display
- Dedicated triage queue for unknowns
- Confidence meter visualization

## Storage

- **Schema:** Part of `policy` schema in PostgreSQL
- **Tables:** Unknowns tracking, decay history, resolution events

## Dependencies

- PostgreSQL (unknowns tracking and audit)
- Policy Engine (scoring integration)
- Signals (runtime correlation)
- Triage UI (operator workflows)

## Related Documentation

- Unknowns decay heuristics: `../../operations/unknowns-triage.md`
- Policy gates: `../policy/gates.md`
- Confidence model: `../policy/confidence-model.md`
- UI triage guide: `../ui/triage-unknowns.md`

## Implementation Status

**Completed:**
- Unknowns registry with bitemporal tracking
- Policy Engine integration with budget gates
- UI chips and triage queue
- Decay heuristics and automatic resolution
- Confidence-based scoring adjustments

**Key Differentiator:**
Unlike other scanners that hide uncertainty, StellaOps makes "what we don't know" visible and policy-addressable. This is critical for air-gapped deployments and zero-day scenarios where external validation is unavailable.