# Uncertainty and entropy

Uncertainty captures missing or untrusted evidence as first-class signals.
It prevents silent false negatives and feeds risk scoring and policy gates.

Core states (examples)
- U1: MissingSymbolResolution
- U2: MissingPurl
- U3: UntrustedAdvisory
- U4: Unknown (no analysis yet)

Tiers and scoring
- Tiers group states by entropy ranges (T1 high to T4 negligible).
- Aggregate tier is the maximum tier across states.
- Risk score adds tier and entropy modifiers.

Tier ranges (example)
- T1: 0.7 to 1.0, blocks not_affected.
- T2: 0.4 to 0.69, warns on not_affected.
- T3: 0.1 to 0.39, allow with caveat.
- T4: 0.0 to 0.09, no special handling.

Risk score formula (simplified)
- meanEntropy = avg(states[].entropy)
- entropyBoost = clamp(meanEntropy * k, 0..boostCeiling)
- tierModifier = {T1:0.50, T2:0.25, T3:0.10, T4:0.00}[aggregateTier]
- riskScore = clamp(baseScore * (1 + tierModifier + entropyBoost), 0..1)

Policy guidance
- High uncertainty blocks not_affected claims.
- Lower tiers allow decisions with caveats.
- Remediation hints are attached to findings.

Remediation examples
- U1: upload symbols or resolve unknowns registry.
- U2: generate lockfile and resolve package coordinates.
- U3: cross-reference trusted advisories.
- U4: run initial analysis to remove unknown state.

Payload fields
- states[] include code, name, entropy, tier, timestamp, evidence.
- aggregateTier and riskScore recorded with computedAt timestamp.

Determinism rules
- Stable ordering of uncertainty states.
- UTC timestamps and fixed precision for entropy values.
- Canonical JSON for hashing and replay.

Related references
- docs/uncertainty/README.md
- docs/reachability/lattice.md
- docs/policy/dsl.md