37 lines
3.5 KiB
Markdown
37 lines
3.5 KiB
Markdown
# 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.
|