stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4823f46c4bc090294580a9136fb6b0e11e50f9
git.stella-ops.org/docs/features/unchecked/findings/ledger-replay-determinism.md

3.0 KiB
Raw Blame History

Ledger Replay Determinism

Module

Findings

Status

IMPLEMENTED

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

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