Uncertainty States & Entropy Scoring

Status: Implemented v0 for reachability facts (Signals). Owners: Signals Guild · Policy Guild · UI Guild.

Audience: Signals, Policy, and Console engineers who consume or act on uncertainty data.

Stella Ops treats missing data and untrusted evidence as first-class uncertainty states, not silent false negatives. Signals persists uncertainty state entries alongside reachability facts and derives a deterministic riskScore that increases when entropy is high. Policy gates and the Console then reason over those states explicitly, so a release decision can never quietly rest on an unproven “not affected”.

1. Core states (extensible)

Each state records:

• entropy (0…1)
• evidence[] list pointing to analyzers/heuristics/sources
• optional timestamp (UTC)

1.1 Uncertainty Tiers (v1 — Sprint 0401)

Uncertainty states are grouped into tiers that determine policy thresholds and UI treatment.

Tier Definitions

Tier Assignment Rules

1. U1 (MissingSymbolResolution):

   • entropy >= 0.7 → T1 (>30% unknowns in callgraph)
   • entropy >= 0.4 → T2 (15-30% unknowns)
   • entropy < 0.4 → T3 (<15% unknowns)

2. U2 (MissingPurl):

   • entropy >= 0.5 → T2 (>50% packages unresolved)
   • entropy < 0.5 → T3 (<50% packages unresolved)

3. U3 (UntrustedAdvisory):

   • entropy >= 0.6 → T3 (no corroboration)
   • entropy < 0.6 → T4 (partial corroboration)

4. U4 (Unknown):

   • Always T1 (no analysis performed = maximum uncertainty)

Aggregate Tier Calculation

When multiple uncertainty states exist, the aggregate tier is the maximum (most severe):

aggregateTier = max(tier(state) for state in uncertainty.states)

2. JSON shape

{
  "uncertainty": {
    "states": [
      {
        "code": "U1",
        "name": "MissingSymbolResolution",
        "entropy": 0.72,
        "timestamp": "2025-11-12T14:12:00Z",
        "evidence": [
          {
            "type": "UnknownsRegistry",
            "sourceId": "signals.unknowns",
            "detail": "unknownsCount=12;unknownsPressure=0.375"
          }
        ]
      }
    ]
  }
}

3. Risk score math (Signals)

Signals computes a riskScore deterministically during reachability recompute:

meanEntropy  = avg(uncertainty.states[].entropy)              // 0 when no states
entropyBoost = clamp(meanEntropy * k, 0 .. boostCeiling)
riskScore    = clamp(baseScore * (1 + entropyBoost), 0 .. 1)

Where:

• baseScore is the average of per-target reachability state scores (before unknowns penalty).
• k defaults to 0.5 (SignalsOptions:Scoring:UncertaintyEntropyMultiplier).
• boostCeiling defaults to 0.5 (SignalsOptions:Scoring:UncertaintyBoostCeiling).

4. Policy guidance (high level)

Uncertainty should bias decisions away from “not affected” when evidence is missing:

• High entropy (U1 with high entropy) should lead to under investigation and drive remediation (upload symbols, run probes, close unknowns).
• Low entropy should allow normal confidence-based gates.

See the reachability lattice guide for the current reachability score model and the Signals reachability contract for the Signals API contract.

5. Tier-Based Risk Score (v1 — Sprint 0401)

Risk Score Formula

Building on §3, the v1 risk score incorporates tier-based modifiers:

tierModifier = {
  T1: 0.50,
  T2: 0.25,
  T3: 0.10,
  T4: 0.00
}[aggregateTier]

riskScore = clamp(baseScore * (1 + tierModifier + entropyBoost), 0 .. 1)

Where:

• baseScore is the average of per-target reachability state scores
• tierModifier is the tier-based risk increase
• entropyBoost is the existing entropy-based boost (§3)

Example Calculation

Given:
  - baseScore = 0.4 (moderate reachability)
  - uncertainty.states = [
      {code: "U1", entropy: 0.72},  // T1 tier
      {code: "U3", entropy: 0.45}   // T3 tier
    ]
  - aggregateTier = T1 (max of T1, T3)
  - tierModifier = 0.50

  meanEntropy = (0.72 + 0.45) / 2 = 0.585
  entropyBoost = clamp(0.585 * 0.5, 0 .. 0.5) = 0.2925

  riskScore = clamp(0.4 * (1 + 0.50 + 0.2925), 0 .. 1)
            = clamp(0.4 * 1.7925, 0 .. 1)
            = clamp(0.717, 0 .. 1)
            = 0.717

Tier Thresholds for Policy Gates

6. JSON Schema (v1)

Extended schema with tier information:

{
  "uncertainty": {
    "states": [
      {
        "code": "U1",
        "name": "MissingSymbolResolution",
        "entropy": 0.72,
        "tier": "T1",
        "timestamp": "2025-12-13T10:00:00Z",
        "evidence": [
          {
            "type": "UnknownsRegistry",
            "sourceId": "signals.unknowns",
            "detail": "unknownsCount=45;totalSymbols=125;unknownsPressure=0.36"
          }
        ]
      },
      {
        "code": "U4",
        "name": "Unknown",
        "entropy": 1.0,
        "tier": "T1",
        "timestamp": "2025-12-13T10:00:00Z",
        "evidence": [
          {
            "type": "NoAnalysis",
            "sourceId": "signals.bootstrap",
            "detail": "subject not yet analyzed"
          }
        ]
      }
    ],
    "aggregateTier": "T1",
    "riskScore": 0.717,
    "computedAt": "2025-12-13T10:00:00Z"
  }
}

7. Implementation Pointers

• Tier calculation: UncertaintyTierCalculator in src/Signals/StellaOps.Signals/Services/
• Risk score math: ReachabilityScoringService.ComputeRiskScore() (extend existing)
• Policy integration: Policy DSL §12 — Uncertainty Gates
• Lattice integration: reachability lattice guide §9 for v1 lattice states

8. Policy Guidance (v1 — Sprint 0401)

Uncertainty gates enforce evidence-quality thresholds in the Policy Engine. When entropy is too high or evidence is missing, policies block or downgrade VEX decisions.

8.1 Gate Mapping

8.2 Sample Policy Rules

// Block not_affected when symbol resolution has high entropy
rule u1_gate_high_entropy priority 5 {
  when signals.uncertainty.level == "U1"
       and signals.uncertainty.entropy >= 0.7
  then status := "under_investigation"
       annotate gate := "U1"
       annotate remediation := "Upload symbols or close unknowns registry"
  because "High symbol entropy blocks strong VEX claims";
}

// Tier-based compound gate
rule tier1_block_not_affected priority 3 {
  when signals.uncertainty.aggregateTier == "T1"
       and vex.any(status == "not_affected")
  then status := "under_investigation"
       annotate blocked_reason := "T1 uncertainty requires evidence"
  because "Maximum uncertainty tier blocks all exclusion claims";
}

8.3 YAML Configuration

uncertainty_gates:
  u1_gate:
    entropy_threshold: 0.7
    blocked_statuses: [not_affected]
    fallback_status: under_investigation
    remediation_hint: "Upload symbols or resolve unknowns"
  u2_gate:
    entropy_threshold: 0.4
    blocked_statuses: [not_affected]
    warn_on_block: true
  u3_gate:
    entropy_threshold: 0.1
    annotate_caveat: true

See Policy DSL §12 — Uncertainty Gates for the complete gate rules and tier-aware compound patterns.

9. Remediation Actions

Each uncertainty state has recommended remediation steps:

9.1 Automated Remediation Flow

1. Policy blocks decision with U1/U2 gate
   ↓
2. Console/CLI shows remediation hint
   ↓
3. User runs remediation command (e.g., stella symbols ingest)
   ↓
4. Signals recomputes uncertainty states
   ↓
5. Risk score updates, tier may drop
   ↓
6. Policy re-evaluates, decision may proceed

9.2 Remediation Priority

When multiple uncertainty states exist, prioritize by tier:

1. T1 states first — Block all exclusions until resolved
2. T2 states — May proceed with warnings if T1 cleared
3. T3/T4 states — Normal flow with caveats

Last updated: 2025-12-13 (Sprint 0401).