# Smart-Diff Weighted Impact Index (WII)

**Source Advisory:** `docs/product-advisories/unprocessed/16-Dec-2025 - Smart‑Diff Meets Call‑Stack Reachability.md`  
**Status:** Processed 2025-12-17

## Overview

The Weighted Impact Index (WII) is a composite score (0-100) that combines Smart-Diff semantic analysis with call-stack reachability to measure the runtime risk of code changes. It proves not just "what changed" but "how risky the change is in reachable code."

## Core Concepts

### Inputs

1. **Smart-Diff Output** - Semantic differences between artifact states
2. **Call Graph** - Symbol nodes with call edges
3. **Entrypoints** - HTTP routes, jobs, message handlers
4. **Runtime Heat** - pprof, APM, or eBPF execution frequency data
5. **Advisory Data** - CVSS v4, EPSS v4 scores

### WII Scoring Model

The WII uses 8 weighted features per diff unit:

| Feature | Weight | Description |
|---------|--------|-------------|
| `Δreach_len` | 0.25 | Change in shortest reachable path length |
| `Δlib_depth` | 0.10 | Change in library call depth |
| `exposure` | 0.15 | Public/external-facing API |
| `privilege` | 0.15 | Path crosses privileged sinks |
| `hot_path` | 0.15 | Frequently executed (runtime evidence) |
| `cvss_v4` | 0.10 | Normalized CVSS v4 severity |
| `epss_v4` | 0.10 | Exploit probability |
| `guard_coverage` | -0.10 | Sanitizers/validations reduce score |

### Determinism Bonus

When `reachability == true` AND (`cvss_v4 > 0.7` OR `epss_v4 > 0.5`), add +5 bonus for "evidence-linked determinism."

### Formula

```
WII = clamp(0, 1, Σ(w_i × feature_i_normalized)) × 100
```

## Data Structures

### DiffUnit

```json
{
  "unitId": "pkg:npm/lodash@4.17.21#function:merge",
  "change": "modified",
  "before": {"hash": "sha256:abc...", "attrs": {}},
  "after": {"hash": "sha256:def...", "attrs": {}},
  "features": {
    "reachable": true,
    "reachLen": 3,
    "libDepth": 2,
    "exposure": true,
    "privilege": false,
    "hotPath": true,
    "cvssV4": 0.75,
    "epssV4": 0.45,
    "guardCoverage": false
  },
  "wii": 68
}
```

### Artifact-Level WII

Two metrics for artifact-level impact:
- `max(WII_unit)` - Spike impact (single highest risk change)
- `p95(WII_unit)` - Broad impact (distribution of risk)

## DSSE Attestation

The WII is emitted as a DSSE-signed attestation:

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{"name": "ghcr.io/acme/app:1.9.3", "digest": {"sha256": "..."}}],
  "predicateType": "https://stella-ops.org/attestations/smart-diff-wii@v1",
  "predicate": {
    "artifactBefore": {"digest": {"sha256": "..."}},
    "artifactAfter": {"digest": {"sha256": "..."}},
    "evidence": {
      "sbomBefore": {"digest": {"sha256": "..."}},
      "sbomAfter": {"digest": {"sha256": "..."}},
      "callGraph": {"digest": {"sha256": "..."}},
      "runtimeHeat": {"optional": true, "digest": {"sha256": "..."}}
    },
    "units": [...],
    "aggregateWII": {
      "max": 85,
      "p95": 62,
      "mean": 45
    }
  }
}
```

## Pipeline Integration

1. **Collect** - Build call graph, import SBOMs, CVE/EPSS data
2. **Diff** - Run Smart-Diff to generate `DiffUnit[]`
3. **Enrich** - Query reachability engine per unit
4. **Score** - Compute per-unit and aggregate WII
5. **Attest** - Emit DSSE statement with evidence URIs
6. **Store** - Proof-Market Ledger (Rekor) + PostgreSQL

## Use Cases

### CI/CD Gates

```yaml
# .github/workflows/security.yml
- name: Smart-Diff WII Check
  run: |
    stellaops smart-diff \
      --base ${{ env.BASE_IMAGE }} \
      --target ${{ env.TARGET_IMAGE }} \
      --wii-threshold 70 \
      --fail-on-threshold
```

### Risk Prioritization

Sort changes by WII for review prioritization:

```bash
stellaops smart-diff show \
  --sort wii \
  --format table
```

### Attestation Verification

```bash
stellaops verify-attestation \
  --input smart-diff-wii.json \
  --predicate-type smart-diff-wii@v1
```

## Related Documentation

- [Smart-Diff CLI Reference](../cli/smart-diff-cli.md)
- [Reachability Analysis](./reachability-analysis.md)
- [DSSE Attestation Format](../api/dsse-format.md)