# Ledger Replay Determinism

## Module
Findings

## Status
VERIFIED

## Description
Replay determinism verification with dedicated tests and a replay harness tool for offline validation.

## Implementation Details
- **Ledger Replay Harness**: `src/Findings/StellaOps.Findings.Ledger/tools/LedgerReplayHarness/` -- offline tool for replaying ledger event sequences and verifying determinism. Key files: `Program.cs` (CLI entry point), `HarnessFixtureReader.cs` (loads event fixtures from files), `HarnessDraftParser.cs` (parses draft event formats), `HarnessMath.cs` (statistical verification of replay results), `HarnessFixtureException.cs` (fixture parsing errors).
- **Standalone Replay Harness**: `src/Findings/tools/LedgerReplayHarness/` -- standalone version with additional infrastructure. Key files: `HarnessRunner.cs` (orchestrates replay execution), `HarnessFixtureEntry.cs` (fixture entry model), `HarnessFixtureReader.cs`, `HarnessStats.cs` (statistics), `MerkleCalculator.cs` (verifies Merkle hashes during replay), `TaskThrottler.cs` (controls concurrency), `ILedgerClient.cs` and `InMemoryLedgerClient.cs` (ledger client abstraction for replay).
- **Ledger Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerHashing.cs` -- computes deterministic hashes of ledger events for replay verification.
- **Ledger Canonical JSON Serializer**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerCanonicalJsonSerializer.cs` -- canonical JSON serialization ensuring identical byte output regardless of property ordering.
- **Hash Utilities**: `src/Findings/StellaOps.Findings.Ledger/Hashing/HashUtilities.cs` -- SHA-256 hashing utilities for deterministic event hashing.
- **Projection Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/ProjectionHashing.cs` -- verifies projection state determinism after replay.
- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/LedgerReplayDeterminismTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/HarnessRunnerTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.ReplayHarness.Tests/HarnessFixtureReaderTests.cs`, `HarnessMathTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Tools.LedgerReplayHarness.Tests/HarnessFixtureReaderTests.cs`, `HarnessRunnerTests.cs`

## E2E Test Plan
- [x] Run the ledger replay harness against a fixture file and verify the replay produces identical ledger hashes to the original execution
- [x] Replay the same event sequence 10 times and verify all runs produce identical projection hashes (statistical determinism)
- [x] Modify a single event payload in a fixture and verify the replay harness detects the hash mismatch and reports it as a determinism violation
- [x] Verify Merkle hash consistency: replay events and confirm `MerkleCalculator` produces the same Merkle root as the original anchoring
- [x] Verify canonical JSON serialization: serialize the same event with different property orderings and confirm `LedgerCanonicalJsonSerializer` produces identical byte output
- [x] Verify the `HarnessFixtureReader` correctly loads fixtures from both draft and final formats

## Verification
Run: run-002 (2026-02-11)
- Tier 0 source verification passed for replay-harness, hashing, and determinism test assets.
- Tier 1 build/tests passed across Findings ledger + replay harness projects and focused determinism suites.
- Tier 2 behavioral verification passed using both integration tests and direct CLI harness execution:
  - positive fixture replay returned exit 0 with report status=pass
  - hash-mismatch fixture replay returned exit 1 with report status=fail
- Terminal outcome: done.