save checkpoint

docs/features/checked/scanner/composition-recipe-api-for-sbom-determinism-verification.md

@@ -0,0 +1,47 @@
+# Composition Recipe API for SBOM Determinism Verification
+
+## Module
+Scanner
+
+## Status
+VERIFIED
+
+## Description
+API endpoint (GET /scans/{id}/composition-recipe) that exposes the SBOM composition recipe with Merkle root and layer digest verification, enabling downstream verification that SBOMs are deterministically composed from layer fragments.
+
+## Implementation Details
+- **Composition Recipe Service**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CompositionRecipeService.cs` - Core service computing composition recipes with Merkle root
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/SbomCompositionResult.cs` - Composition result model with Merkle root and layer digests
+- **Layer SBOM Composition**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomComposer.cs` - Composes full SBOM from per-layer SBOM fragments
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomRef.cs` - Layer SBOM reference with digest
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxComposer.cs` - CycloneDX-specific composition
+- **API Endpoints**:
+  - `src/Scanner/StellaOps.Scanner.WebService/Endpoints/LayerSbomEndpoints.cs` - `LayerSbomEndpoints` exposing composition recipe and layer SBOM data
+  - `src/Scanner/StellaOps.Scanner.WebService/Contracts/LayerSbomContracts.cs` - API contracts
+- **Layer SBOM Service**:
+  - `src/Scanner/StellaOps.Scanner.WebService/Services/ILayerSbomService.cs` - `ILayerSbomService` with `LayerSummary`, `SbomLayerFragment`
+  - `src/Scanner/StellaOps.Scanner.WebService/Services/LayerSbomService.cs` - Implementation
+- **Surface Manifest**:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/SurfaceManifestDeterminismVerifier.cs` - Verifies determinism of surface manifests
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/FacetSealExtractor.cs` - Extracts facet seals for composition verification
+
+## E2E Test Plan
+- [ ] Scan an image and call `GET /api/v1/scans/{scanId}/composition-recipe` to retrieve the composition recipe
+- [ ] Verify the response includes Merkle root and per-layer digest values
+- [ ] Verify each layer fragment digest matches the actual layer SBOM content hash
+- [ ] Re-compose the SBOM from layer fragments and verify the Merkle root matches the recipe
+- [ ] Scan the same image twice and verify composition recipe values are deterministically identical
+- [ ] Verify the composition recipe can be used to verify SBOM integrity in an offline/air-gap environment
+
+---
+
+## 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 |