# Golden Pairs Mirror and Diff Pipeline

## Module
Tools

## Status
VERIFIED

## Description
Package mirror service to download pre/post-patch binary pairs from distro repos, and a diff pipeline service that runs section-hash diffing to produce golden diff reports for backport detection validation.

## Implementation Details
- **Golden Pairs App**: `src/Tools/GoldenPairs/GoldenPairsApp.cs` (320 lines) -- full CLI with `mirror`, `diff`, and `validate` sub-commands using `System.CommandLine`. Mirror downloads pre/post-patch binaries, diff runs section-hash comparison and writes JSON reports, validate iterates CVE directories and reports pass/fail summary.
- **Package Mirror Service**: `src/Tools/GoldenPairs/Services/PackageMirrorService.cs` (286 lines) -- `AptPackageMirrorService` implementing `IPackageMirrorService`. Downloads from HTTP(S), `apt://` (scheme-rewritten), and `file://` URIs. Extracts files from `.deb` archives via SharpCompress (nested data.tar extraction). SHA-256 hash verification after download.
- **Diff Pipeline Service**: `src/Tools/GoldenPairs/Services/DiffPipelineService.cs` (289 lines) -- section-by-section comparison (Identical/Modified/Added/Removed) using hash comparison. Verdict determination (Patched/Vanilla/Unknown) based on `.text` section changes with confidence scoring. Validation against expected diff.
- **Section Hash Provider**: `src/Tools/GoldenPairs/Services/SectionHashProvider.cs` (87 lines) -- `FileSectionHashProvider` with `LoadAsync` (from JSON) and `ExtractAsync` (from binary via `IElfSectionHashExtractor`). Deterministically ordered `SectionHashSet`.
- **Golden Pair Loader**: `src/Tools/GoldenPairs/Services/GoldenPairLoader.cs` (211 lines) -- loads metadata from JSON files with JSON Schema validation, deserialization, normalization, and error collection. Supports individual pair and index loading.
- **Golden Pairs Schema Provider**: `src/Tools/GoldenPairs/Schema/GoldenPairsSchemaProvider.cs` (36 lines) -- lazy-loads metadata and index JSON schemas.
- **Models**: `src/Tools/GoldenPairs/Models/` (4 files, ~170 lines) -- `GoldenPairMetadata`, `GoldenDiffReport`, `SectionHashModels`, `GoldenPairsIndex`.
- **Serialization**: `src/Tools/GoldenPairs/Serialization/GoldenPairsJsonSerializer.cs` (78 lines) -- deterministic property ordering via `DeterministicTypeInfoResolver`, camelCase naming, enum string conversion.

## E2E Test Plan
- [x] Run `PackageMirrorService` to download a known CVE fix pair and verify both binaries are downloaded with correct metadata and SHA-256 verification
- [x] Run `DiffPipelineService` on a pair and verify the diff report identifies changed sections with correct verdict
- [x] Run `SectionHashProvider` on a known binary and verify section hashes are deterministic across multiple runs
- [x] Load a golden pair via `GoldenPairLoader`, re-run the diff pipeline, and verify the new diff report matches
- [x] Validate a diff report against the JSON schema and verify it passes validation
- [x] Verify hash mismatch detection in mirror service

## Verification
- **Verified**: 2026-02-10
- **Method**: Tier 1 code review + Tier 2d test verification
- **Build**: Passes (0 errors, 0 warnings)
- **Tests**: 9 tests pass across 4 test files (DiffPipelineServiceTests: 2, GoldenPairLoaderTests: 2, PackageMirrorServiceTests: 2, GoldenPairSchemaTests: 3)

## Recheck (Run-002)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (`src/Tools/__Tests/StellaOps.Tools.GoldenPairs.Tests`: 9/9).
- **Tier 2 Evidence**: `docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-002/tier2-integration-check.json`
- **Outcome**: Mirror/diff pipeline behaviors remain healthy with deterministic verdicting and mismatch detection.


## Recheck (Run-003)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (`src/Tools/__Tests/StellaOps.Tools.GoldenPairs.Tests`: 9/9).
- **Tier 2 Evidence**: `docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-003/tier2-integration-check.json`
- **Outcome**: Mirror/diff pipeline behaviors remain healthy with deterministic verdicting and mismatch detection.

## Recheck (Run-004)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (GoldenPairs 9/9).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-004/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in follow-up replay.

## Recheck (Run-005)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (GoldenPairs 9/9).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-005/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in continued replay.

## Recheck (Run-006)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (GoldenPairs 9/9).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-006/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in continued replay.

## Recheck (Run-007)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (GoldenPairs 9/9).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-007/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in continued replay.

## Recheck (Run-008)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (GoldenPairs 9/9).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-008/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in continued replay.


## Recheck (Run-009)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (WorkflowGenerator 76/76, FixtureUpdater 2/2, GoldenPairs 9/9; total 87/87).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-009/tier2-integration-check.json
- **Outcome**: Checked tools behavior remains healthy in continued replay.
## Recheck (Run-010)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (WorkflowGenerator 76/76, FixtureUpdater 2/2, GoldenPairs 9/9; total 87/87).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-010/tier2-integration-check.json
- **Outcome**: Checked tools behavior remains healthy in continued replay.
## Recheck (Run-011)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay.
- **Tests**: PASS (WorkflowGenerator 76/76, FixtureUpdater 2/2, GoldenPairs 9/9; total 87/87).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-011/tier2-integration-check.json
- **Outcome**: Checked tools behavior remains healthy in continued replay.
## Recheck (Run-012)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic tools suite replay.
- **Tests**: PASS (WorkflowGenerator 76/76, FixtureUpdater 2/2, GoldenPairs 9/9; total 87/87).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-012/tier2-integration-check.json
- **Outcome**: Checked tools behavior remains healthy in continued replay.

## Recheck (Run-013)
- **Verified**: 2026-02-10
- **Method**: Tier 2d deterministic integration replay with fresh command-output evidence.
- **Tests**: PASS (9/9; Tools matrix 87/87: WorkflowGenerator 76, FixtureUpdater 2, GoldenPairs 9.)
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-013/tier2-integration-check.json
- **Outcome**: Checked Tools behavior remains healthy in continued replay.

## Recheck (Run-014)
- **Verified**: 2026-02-11
- **Method**: Strict Tier 2 CLI replay (mirror, diff, and missing-CVE negative path).
- **Tests**: PASS (`src/Tools/__Tests/StellaOps.Tools.GoldenPairs.Tests`: 10/10).
- **Tier 2 Evidence**: docs/qa/feature-checks/runs/tools/golden-pairs-mirror-and-diff-pipeline/run-014/tier2-cli-check.json
- **Outcome**: Mirror and diff pipeline flows validated through direct CLI interactions with fresh command evidence.