stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/checked/tools/golden-pairs-mirror-and-diff-pipeline.md
master cf5b72974f save checkpoint
2026-02-11 01:32:14 +02:00

7.4 KiB
Raw Blame History

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

  • Run PackageMirrorService to download a known CVE fix pair and verify both binaries are downloaded with correct metadata and SHA-256 verification
  • Run DiffPipelineService on a pair and verify the diff report identifies changed sections with correct verdict
  • Run SectionHashProvider on a known binary and verify section hashes are deterministic across multiple runs
  • Load a golden pair via GoldenPairLoader, re-run the diff pipeline, and verify the new diff report matches
  • Validate a diff report against the JSON schema and verify it passes validation
  • 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.