save checkpoint

docs/features/checked/scanner/layer-aware-sbom-diff-engine.md

@@ -0,0 +1,43 @@
+# Layer-Aware SBOM Diff Engine
+
+## Module
+Scanner
+
+## Status
+VERIFIED
+
+## Description
+Extension of the SBOM diff engine with layer attribution, tracking which container layer (by diffID) introduced each component change. Enables "blame" queries to identify which layer introduced a specific vulnerability. While "SBOM Delta / Component Diffing" exists in known features, layer-attributed diffing with per-layer blame is a distinct capability.
+
+## Implementation Details
+- **SBOM Diff Engine**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomDiffEngine.cs` - `SbomDiffEngine` performs SBOM-level diffing with layer attribution, tracking which container layer (by diffID) introduced each component change
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomDiff.cs` - `SbomDiff` model representing component changes with layer attribution
+- **Lineage Infrastructure**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/SbomLineage.cs` - `SbomLineage` tracks the history of SBOMs across image versions for lineage-based diff
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/ISbomStore.cs` - `ISbomStore` interface for SBOM storage used by lineage tracking
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Lineage/RebuildProof.cs` - `RebuildProof` for reproducible rebuild verification
+- **Component Diffing**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Diff/ComponentDiffer.cs` - `ComponentDiffer` performs component-level diff analysis
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Diff/ComponentDiffModels.cs` - Models for component diff results
+- **Delta Layer Integration**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Delta/DeltaLayerScanner.cs` - `DeltaLayerScanner` scans individual layers for delta analysis
+
+## E2E Test Plan
+- [ ] Scan two versions of a container image and verify the SBOM diff engine produces a layer-attributed diff showing which layer introduced each change
+- [ ] Verify added components are attributed to the specific layer (by diffID) that introduced them
+- [ ] Verify removed components are attributed to the layer where they were present in the previous image
+- [ ] Run a "blame" query for a specific vulnerable component and verify it returns the layer that introduced it
+- [ ] Verify lineage tracking correctly associates multiple image versions for historical diff analysis
+- [ ] Verify the diff engine handles base image layer changes separately from application layer changes
+
+---
+
+## Verification
+
+| Check | Result |
+|-------|--------|
+| Tier 0 - Source files exist | PASS |
+| Tier 1 - Build + code review | PASS |
+| Tier 2 - Integration tests | PASS |
+| Verified | 2026-02-13T18:10:00Z |