# Change-Trace Architecture

> **Module:** Scanner / ChangeTrace
> **Version:** 1.0.0
> **Status:** Draft
> **Last Updated:** 2026-01-12

---

## Overview

The Change-Trace feature provides deterministic comparison of binary artifacts across versions, producing a "trust-delta" view that explains what changed, why (backport, rebuild, upgrade), and what it means for security risk.

### Strategic Value

- **Differentiating capability**: Explains backports and security patches that competitors flag as "version mismatch"
- **Audit trail**: Produces verifiable evidence for every version change decision
- **Reduced review time**: Pre-computed deltas with proof steps eliminate manual investigation
- **Compliance support**: Generates attestations suitable for regulatory frameworks

---

## Architecture Diagram

```
                          +------------------+
                          |   CLI / API      |
                          |  (entry points)  |
                          +--------+---------+
                                   |
                    +-------------+v+-------------+
                    |      ChangeTraceBuilder     |
                    |  (orchestrates comparison)  |
                    +---+-----+-----+-----+------+
                        |     |     |     |
           +------------+     |     |     +------------+
           |                  |     |                  |
           v                  v     v                  v
   +-------+------+   +------+-----+------+   +-------+------+
   |  ScanResult  |   |  BinaryIndex      |   |  VexLens     |
   |   Loader     |   |  DeltaSigMatcher  |   |  Consensus   |
   +--------------+   +-------------------+   +--------------+
           |                  |                      |
           v                  v                      v
   +-------+------+   +------+-----+------+   +------+-------+
   | PackageDelta |   | SymbolDelta       |   | TrustDelta   |
   |  Generator   |   | + ByteDelta       |   | Calculator   |
   +--------------+   +-------------------+   +--------------+
           |                  |                      |
           +------------------+----------------------+
                              |
                    +---------v----------+
                    |    ChangeTrace     |
                    |   (output model)   |
                    +--------------------+
                              |
           +------------------+------------------+
           |                  |                  |
           v                  v                  v
   +-------+------+   +------+-----+------+  +--+-------------+
   | JSON Export  |   | DSSE Attestation  |  | CycloneDX      |
   | (standalone) |   | (signing)         |  | (embedded)     |
   +--------------+   +-------------------+  +----------------+
```

---

## Data Flow

### 1. Input Stage

```
Scan1 (from)              Scan2 (to)
     |                         |
     v                         v
+----+----+               +----+----+
| SBOM    |               | SBOM    |
| Findings|               | Findings|
| Binary  |               | Binary  |
| Sigs    |               | Sigs    |
+---------+               +---------+
```

### 2. Comparison Stage

```
Package Comparison:
  - Match by PURL
  - Detect: Added, Removed, Upgraded, Downgraded, Patched, Rebuilt

Symbol Comparison (via BinaryIndex):
  - CFG hash matching
  - Instruction hash matching
  - Semantic hash matching
  - Chunk-level similarity

Byte Comparison (optional):
  - Rolling hash windows (2KB)
  - Per-section analysis
  - Delta identification
```

### 3. Trust Scoring Stage

```
For each PackageDelta:
  1. Get VEX consensus (from, to)
  2. Query reachability (from, to)
  3. Apply patch verification bonus
  4. Compute trust delta

Formula:
  TrustDelta = (AfterTrust - BeforeTrust) / max(BeforeTrust, 0.01)
```

### 4. Output Stage

```
ChangeTrace JSON
  -> Standalone export (.cdxchange.json)
  -> DSSE attestation (stella.ops/changetrace@v1)
  -> CycloneDX embedded (component-evidence extension)
```

---

## Component Responsibilities

### ChangeTraceBuilder

**Location:** `src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/`

Orchestrates the comparison workflow:
- Loads scan results
- Coordinates package, symbol, and byte comparisons
- Aggregates results into `ChangeTrace` model
- Ensures deterministic output (stable ordering, UTC timestamps)

### SymbolChangeTracer

**Location:** `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`

Performs binary-level comparison:
- Compares `SymbolSignature` objects
- Identifies change type (Added, Removed, Modified, Patched)
- Computes similarity metrics
- Generates human-readable explanations

### TrustDeltaCalculator

**Location:** `src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/Scoring/`

Computes risk impact:
- Integrates with VexLens for consensus scores
- Integrates with ReachGraph for reachability data
- Applies patch verification bonus
- Generates proof steps

### ByteLevelDiffer

**Location:** `src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/ByteDiff/`

Performs byte-level analysis:
- Rolling hash window comparison
- Section-aware diffing (ELF/PE/Mach-O)
- Privacy-preserving output (hashes only)

---

## Key Models

### ChangeTrace (Root)

```csharp
public sealed record ChangeTrace
{
    public const string SchemaVersion = "stella.change-trace/1.0";
    public string Schema { get; init; } = SchemaVersion;
    public required ChangeTraceSubject Subject { get; init; }
    public ImmutableArray<PackageDelta> Deltas { get; init; } = [];
    public required ChangeTraceSummary Summary { get; init; }
    public required DateTimeOffset AnalyzedAt { get; init; }
    public string AlgorithmVersion { get; init; } = "1.0";
}
```

### PackageDelta

```csharp
public sealed record PackageDelta
{
    public required string Purl { get; init; }
    public string? FromVersion { get; init; }
    public string? ToVersion { get; init; }
    public required ChangeType ChangeType { get; init; }
    public ImmutableArray<SymbolDelta> Symbols { get; init; } = [];
    public ImmutableArray<ByteDelta> Bytes { get; init; } = [];
    public required TrustDelta TrustDelta { get; init; }
}
```

### TrustDelta

```csharp
public sealed record TrustDelta
{
    public double Score { get; init; }  // [-1, +1]
    public double BeforeScore { get; init; }
    public double AfterScore { get; init; }
    public ReachabilityImpact ReachabilityImpact { get; init; }
    public ExploitabilityImpact ExploitabilityImpact { get; init; }
    public ImmutableArray<string> ProofSteps { get; init; } = [];
}
```

---

## Trust-Delta Formula

### Core Formula

```
TrustDelta = (AfterTrust - BeforeTrust) / max(BeforeTrust, 0.01)
```

Where:
- `BeforeTrust = VexConsensus(from) * ReachabilityFactor(from)`
- `AfterTrust = VexConsensus(to) * ReachabilityFactor(to) + PatchBonus`

### Reachability Factor

```
ReachabilityFactor(callPaths) =
  - 1.0 if callPaths > 0 (reachable)
  - 0.7 if callPaths == 0 (unreachable, 30% reduction)
  - 1.0 if callPaths is null (unknown)
```

### Patch Verification Bonus

```
PatchBonus =
  + (FunctionMatchWeight * PatchConfidence)      // 0.25 weight
  + (SectionMatchWeight * SymbolSimilarity)      // 0.15 weight
  + (AttestationWeight * IssuerAuthority)        // 0.10 weight (if DSSE present)
```

### Verdict Mapping

| Delta Range | Verdict |
|-------------|---------|
| < -0.3 | risk_down |
| -0.3 to +0.3 | neutral |
| > +0.3 | risk_up |

---

## Integration Points

### VexLens Integration

- `IVexLensClient.GetConsensusAsync(purl, version)`: Get trust score
- `IVexLensClient.GetAdvisoryAsync(cveId)`: Get CVE details for proof steps

### ReachGraph Integration

- `IReachGraphClient.GetReachabilityAsync(purl, version)`: Get call path count
- Used for reachability impact calculation

### BinaryIndex Integration

- `IDeltaSignatureMatcher.CompareSignaturesAsync(from, to)`: Symbol comparison
- `ISymbolChangeTracer.CompareSymbols(fromSymbol, toSymbol)`: Detailed symbol diff

### Attestor Integration

- `IAttestationService.CreateChangeTraceAttestationAsync(trace)`: DSSE envelope
- Predicate type: `stella.ops/changetrace@v1`

---

## Determinism Requirements

All outputs must be reproducible:

1. **Stable ordering**: Sort deltas by PURL, symbols by name, bytes by offset
2. **UTC timestamps**: Use `TimeProvider` for all timestamps
3. **Canonical JSON**: RFC 8785 compliant serialization
4. **No randomness**: Deterministic ID generation from content hashes

### Verification

```bash
# Two runs should produce identical output
stella change-trace build --from scan1 --to scan2 > trace1.json
stella change-trace build --from scan1 --to scan2 > trace2.json
diff trace1.json trace2.json  # Should be empty
```

---

## Performance Targets

| Metric | Target |
|--------|--------|
| Package comparison | < 100ms |
| Symbol comparison | < 100ms per binary |
| Byte-level diffing | < 500ms for binaries < 5MB |
| Full trace build | < 5s for typical container |
| Memory usage | < 500MB peak |

---

## Security Considerations

### Privacy

- Byte content is never included in output
- Only hashes, offsets, and sizes are exported
- Symbol names may be sensitive (review before external export)

### Integrity

- DSSE attestations provide tamper-evidence
- Signature verification available via `stella change-trace verify`

### Access Control

- API endpoints require authentication
- Traces inherit visibility from source scans

---

## Future Enhancements

### Phase 2

- Function-level heatmap visualization
- Side-by-side disassembly view
- AI-assisted change explanation

### Phase 3

- Historical trend analysis
- Anomaly detection for unexpected changes
- Integration with SLSA provenance

---

## References

- [Sprint INDEX](../../implplan/SPRINT_20260112_200_000_INDEX_change_trace.md)
- [JSON Schema Contract](../../contracts/change-trace-schema.md)
- [Trust-Delta Contract](../../contracts/change-trace-trust-delta.md)
- [BinaryIndex Architecture](../../modules/binary-index/architecture.md)
- [VexLens Architecture](../../modules/vexlens/architecture.md)

---

*Document Version: 1.0.0*
*Last Updated: 2026-01-12*