# Lineage Smart-Diff UI Architecture

> Sprint: SPRINT_20251229_001_FE_lineage_smartdiff_overview
> Last Updated: 2025-12-29

## 1. Overview

The Lineage Smart-Diff feature provides a comprehensive UI for visualizing SBOM lineage graphs, comparing artifact versions, and explaining security state changes between builds.

### 1.1 Completion Status

| Area | Completion | Notes |
|------|------------|-------|
| **Lineage Graph SVG** | 95% | Full DAG visualization with lanes, pan/zoom, nodes |
| **Hover Cards** | 85% | Basic info displayed; needs CGS integration |
| **SBOM Diff View** | 90% | 3-column diff exists; needs row expanders |
| **VEX Diff View** | 90% | Status change display; needs reachability gates |
| **Compare Mode** | 85% | Three-pane layout exists; needs explainer timeline |
| **Export Dialog** | 80% | Basic export; needs audit pack format |
| **Proof Tree** | 75% | Merkle tree viz; needs confidence breakdown |
| **Reachability Diff** | 60% | Basic view; needs gate visualization |

## 2. UI Data Contracts

### 2.1 CGS/Lineage API Integration

```typescript
// Lineage Graph Response
interface LineageGraph {
  artifact: string;
  nodes: LineageNode[];
  edges: LineageEdge[];
  metadata: {
    totalNodes: number;
    maxDepth: number;
    generatedAt: string;
  };
}

interface LineageNode {
  id: string;
  artifactDigest: string;
  artifactRef: string;
  sequenceNumber: number;
  createdAt: string;
  source: string;
  parentDigests: string[];
  badges: {
    newVulns: number;
    resolvedVulns: number;
    signatureStatus: 'valid' | 'invalid' | 'unknown';
    reachabilityStatus: 'analyzed' | 'pending' | 'unavailable';
  };
  replayHash: string;
  cgsHash?: string;
}

interface LineageEdge {
  fromDigest: string;
  toDigest: string;
  relationship: 'parent' | 'build' | 'base' | 'derived';
}
```

### 2.2 Diff Response Schema

```typescript
interface LineageDiffResponse {
  fromDigest: string;
  toDigest: string;
  sbomDiff: {
    added: ComponentDiff[];
    removed: ComponentDiff[];
    versionChanged: VersionChange[];
    licenseChanged: LicenseChange[];
  };
  vexDiff: VexDelta[];
  reachabilityDiff: ReachabilityDelta[];
  replayHash: string;
  generatedAt: string;
}

interface ComponentDiff {
  purl: string;
  name: string;
  version: string;
  ecosystem: string;
  license?: string;
  scope: 'runtime' | 'development' | 'optional';
}

interface VersionChange {
  purl: string;
  name: string;
  fromVersion: string;
  toVersion: string;
  changeType: 'upgrade' | 'downgrade' | 'patch';
}

interface VexDelta {
  cveId: string;
  purl: string;
  fromStatus: VexStatus;
  toStatus: VexStatus;
  justification?: string;
  effectiveAt: string;
}

interface ReachabilityDelta {
  cveId: string;
  purl: string;
  fromReachable: boolean;
  toReachable: boolean;
  paths?: string[][];
}
```

## 3. Explainer Timeline Requirements

### 3.1 Engine Steps

The explainer timeline shows the sequence of analysis steps:

| Step | Description | Visual Cue |
|------|-------------|------------|
| SBOM Parse | Initial SBOM ingestion | Document icon |
| Component Match | CVE-to-component matching | Link icon |
| VEX Lookup | VEX document resolution | Shield icon |
| Reachability | Call graph analysis | Graph icon |
| Policy Gate | Policy rule evaluation | Gate icon |
| Verdict | Final determination | Checkmark/X |

### 3.2 Data Binding

```typescript
interface ExplainerStep {
  stepId: string;
  stepType: 'sbom_parse' | 'component_match' | 'vex_lookup' | 
            'reachability' | 'policy_gate' | 'verdict';
  timestamp: string;
  duration: number;
  status: 'success' | 'warning' | 'error';
  inputs: Record<string, unknown>;
  outputs: Record<string, unknown>;
  evidence?: {
    type: string;
    hash: string;
    downloadUrl?: string;
  };
}
```

## 4. Node Diff Table UX

### 4.1 Expander Pattern

Each diff row can expand to show:
- Full component details (license, scope, dependencies)
- CVE associations and status
- Reachability paths (if analyzed)
- VEX statements affecting the component

### 4.2 Visual Design

```
┌─────────────────────────────────────────────────────────────┐
│ Component          │ Before        │ After         │ Status│
├─────────────────────────────────────────────────────────────┤
│ ▶ lodash          │ 4.17.20       │ 4.17.21       │ ↑     │
│   └─ CVE-2021-23337 (fixed in 4.17.21)                     │
│   └─ License: MIT                                           │
├─────────────────────────────────────────────────────────────┤
│ ▶ axios           │ 0.21.1        │ 0.21.4        │ ↑     │
├─────────────────────────────────────────────────────────────┤
│ ▶ express         │ -             │ 4.18.2        │ + NEW │
└─────────────────────────────────────────────────────────────┘
```

## 5. Reachability Gate Diff UI

### 5.1 Visual Cues

| Gate Status | Icon | Color |
|-------------|------|-------|
| Reachable | ● | Red |
| Not Reachable | ○ | Green |
| Unknown | ? | Gray |
| Changed | ↔ | Orange |

### 5.2 Path Display

When reachability changes, show the call path:
```
entrypoint.ts → handler.ts → vulnerable_fn.ts → lodash.get()
```

## 6. Audit Pack Export UI

### 6.1 Export Options

| Option | Description | Default |
|--------|-------------|---------|
| Include SBOMs | Both before/after SBOMs | ✓ |
| Include Diff | Component/VEX/reachability diff | ✓ |
| Include Attestations | DSSE envelopes | ✓ |
| Include Evidence | Supporting evidence files | ✗ |
| Sign Bundle | Sign with tenant key | ✓ |

### 6.2 Manifest Schema

```json
{
  "version": "1.0",
  "generatedAt": "2025-12-29T10:00:00Z",
  "artifactA": { "digest": "sha256:...", "name": "...", "createdAt": "..." },
  "artifactB": { "digest": "sha256:...", "name": "...", "createdAt": "..." },
  "contents": [
    { "type": "sbom", "filename": "before.cdx.json", "sha256": "..." },
    { "type": "sbom", "filename": "after.cdx.json", "sha256": "..." },
    { "type": "diff", "filename": "diff.json", "sha256": "..." },
    { "type": "attestation", "filename": "attestations.dsse.json", "sha256": "..." }
  ],
  "merkleRoot": "sha256:...",
  "summary": {
    "componentsAdded": 5,
    "componentsRemoved": 2,
    "vexUpdates": 3,
    "attestationCount": 2
  }
}
```

## 7. Copy-Safe Workflow

### 7.1 Pinned Explanation UX

Operators can "pin" explanations for ticket export:

1. Click pin icon on any verdict/finding
2. Explanation captures current state with hash
3. Export as Markdown/JSON for JIRA/ServiceNow

### 7.2 Ticket Export Format

```markdown
## Security Finding Report

**Artifact**: myorg/myapp:v1.2.3 (sha256:abc123...)
**Generated**: 2025-12-29T10:00:00Z
**Replay Hash**: sha256:def456...

### Finding: CVE-2021-23337 in lodash

| Field | Value |
|-------|-------|
| Status | Not Affected |
| Reason | Not Reachable |
| Evidence | Call graph analysis |
| VEX ID | VEX-2025-001 |

### Verification

To reproduce this verdict:
```
stella verdict replay --hash sha256:def456...
```
```

## 8. Confidence Breakdown Charts

### 8.1 Metrics Sources

| Metric | Source | Weight |
|--------|--------|--------|
| SBOM Completeness | Scanner analysis | 30% |
| VEX Coverage | VEX Hub aggregation | 25% |
| Reachability Depth | Call graph analysis | 25% |
| Attestation Count | Sigstore/local | 20% |

### 8.2 Visualization

- Donut chart showing confidence breakdown
- Hover for detailed explanations
- Color coding: Green (>80%), Yellow (50-80%), Red (<50%)

## 9. Component Inventory

### 9.1 Lineage Feature Components

| Component | Location | Status |
|-----------|----------|--------|
| `LineageGraphComponent` | `lineage-graph.component.ts` | Complete |
| `LineageNodeComponent` | `lineage-node.component.ts` | Complete |
| `LineageEdgeComponent` | `lineage-edge.component.ts` | Complete |
| `LineageHoverCardComponent` | `lineage-hover-card.component.ts` | Needs CGS |
| `LineageMiniMapComponent` | `lineage-minimap.component.ts` | Complete |
| `LineageControlsComponent` | `lineage-controls.component.ts` | Complete |
| `LineageSbomDiffComponent` | `lineage-sbom-diff.component.ts` | Needs expanders |
| `LineageVexDiffComponent` | `lineage-vex-diff.component.ts` | Needs gates |
| `LineageCompareComponent` | `lineage-compare.component.ts` | Needs timeline |
| `LineageExportDialogComponent` | `lineage-export-dialog.component.ts` | Needs audit pack |

## 10. Related Documentation

- [SbomService Lineage API](../sbomservice/lineage/architecture.md)
- [UI Architecture](../ui/architecture.md)
- [Graph Module Architecture](../graph/architecture.md)