git.stella-ops.org/docs/modules/unknowns/README.md

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.