# Known-build binary catalog (Build-ID + hash-based binary identity)

## Module
BinaryIndex

## Status
VERIFIED

## Description
BinaryIdentity model and vulnerability assertion repository implement the binary-key-based catalog using Build-ID and file SHA256 as primary keys.

## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/`
- **Key Classes**:
  - `BinaryIdentity` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/BinaryIdentity.cs`) - core identity model with Build-ID and file SHA256 dimensions
  - `BinaryIdentityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/BinaryIdentityService.cs`) - binary identity extraction/indexing service
  - `BinaryIdentityRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Repositories/BinaryIdentityRepository.cs`) - repository lookups by Build-ID, binary key, and file SHA256
  - `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - assertion-backed vulnerability lookup with method mapping
  - `CachedBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CachedBinaryVulnerabilityService.cs`) - read-through cache for repeat identity lookups
- **Interfaces**:
  - `IBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/IBinaryVulnerabilityService.cs`)
  - `IBinaryVulnAssertionRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/IBinaryVulnAssertionRepository.cs`)
  - `IBinaryIdentityRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Repositories/IBinaryIdentityRepository.cs`)

## E2E Test Plan
- [x] Register a binary identity with known Build-ID and verify it is stored in the catalog
- [x] Query the catalog by Build-ID and verify the correct binary identity is returned
- [x] Query by file SHA256 hash and verify the correct binary identity is returned
- [x] Assert a vulnerability against a binary identity and verify the assertion is persisted
- [x] Verify `CachedBinaryVulnerabilityService` caches lookups and returns cached results on repeat queries
- [x] Verify match method mapping: `buildid_catalog` maps to `MatchMethod.BuildIdCatalog`

## Verification
- Run: `run-002`
- Date (UTC): 2026-02-12
- Evidence: `docs/qa/feature-checks/runs/binaryindex/known-build-binary-catalog/run-002/`
- Tier 1 result: pass (`87/87` tests)
- Tier 2 result: pass (`10/10` targeted behavioral checks)
- Verified behaviors:
  - Build-ID lookup positive and negative paths
  - File SHA256 lookup, including latest-row precedence behavior
  - Assertion persistence retrieval path
  - `buildid_catalog` to `MatchMethod.BuildIdCatalog` mapping
  - Repeat identity lookup cache-hit behavior