save checkpoint: save features
This commit is contained in:
master
@@ -0,0 +1,33 @@
|
||||
# Findings Ledger with Append-Only Events
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Findings Ledger with event write service, event constants, integration tests, and contract tests for append-only event persistence.
|
||||
|
||||
## Implementation Details
|
||||
- **Ledger Event Write Service**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerEventWriteService.cs` -- core service that appends immutable events to the findings ledger; each event has a unique chain ID, timestamp, event type, actor, and JSON payload.
|
||||
- **Ledger Event Models**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerEventModels.cs` -- domain models for ledger events including event type, payload, and metadata.
|
||||
- **Ledger Event Constants**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerEventConstants.cs` -- event type constants (e.g., FindingCreated, VexStatusChanged, PolicyEvaluated, DecisionRecorded).
|
||||
- **Ledger Chain ID Generator**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerChainIdGenerator.cs` -- generates content-addressed chain IDs linking events to their predecessors for tamper detection.
|
||||
- **Evidence Reference**: `src/Findings/StellaOps.Findings.Ledger/Domain/EvidenceReference.cs` -- references to evidence artifacts attached to ledger events.
|
||||
- **Ledger Event Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/ILedgerEventRepository.cs` -- persistence contract for ledger events.
|
||||
- **Ledger Event Stream Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/ILedgerEventStream.cs` -- streaming interface for replaying event sequences.
|
||||
- **Postgres Ledger Event Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventRepository.cs` -- PostgreSQL implementation of the event repository with append-only guarantees.
|
||||
- **Postgres Ledger Event Stream**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventStream.cs` -- PostgreSQL event stream for replay and projection.
|
||||
- **In-Memory Ledger Event Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/InMemory/InMemoryLedgerEventRepository.cs` -- in-memory implementation for testing.
|
||||
- **Ledger Event Request/Response**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/LedgerEventRequest.cs`, `LedgerEventResponse.cs` -- API DTOs for event submission and retrieval.
|
||||
- **Ledger Event Mapping**: `src/Findings/StellaOps.Findings.Ledger.WebService/Mappings/LedgerEventMapping.cs` -- maps between domain events and API DTOs.
|
||||
- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/FindingsLedgerIntegrationTests.cs`, `FindingsLedgerWebServiceContractTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerEventWriteServiceTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Infrastructure/InMemoryLedgerEventRepositoryTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a finding event via the REST API and verify it is persisted in the ledger with a valid chain ID linking to the previous event
|
||||
- [ ] Verify append-only guarantee: attempt to modify or delete an existing ledger event and confirm the operation is rejected
|
||||
- [ ] Submit multiple events in sequence and verify the chain IDs form a valid hash chain (each event's chain ID includes the previous event's hash)
|
||||
- [ ] Replay the event stream and verify all events are returned in chronological order with correct payloads
|
||||
- [ ] Verify contract tests: submit events with all defined event types from `LedgerEventConstants` and verify each produces a valid response
|
||||
- [ ] Verify the in-memory repository passes the same test suite as the PostgreSQL repository
|
||||
36
docs/features/checked/findings/ledger-replay-determinism.md
Normal file
36
docs/features/checked/findings/ledger-replay-determinism.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Merkle Anchoring for Audit Integrity
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Dedicated Merkle anchor worker that periodically anchors ledger events to Merkle trees for tamper-evident audit integrity.
|
||||
|
||||
## Implementation Details
|
||||
- **Merkle Anchor Worker**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/LedgerMerkleAnchorWorker.cs` -- background worker that periodically collects unanchored ledger events, builds a Merkle tree, and stores the anchor (root hash, tree size, event range).
|
||||
- **Merkle Tree Builder**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/MerkleTreeBuilder.cs` -- builds Merkle trees from ledger event hashes for tamper-evident anchoring.
|
||||
- **Ledger Anchor Queue**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/LedgerAnchorQueue.cs` -- queues events for periodic Merkle anchoring.
|
||||
- **Merkle Anchor Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/IMerkleAnchorRepository.cs` -- persistence contract for Merkle anchor records.
|
||||
- **Postgres Merkle Anchor Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresMerkleAnchorRepository.cs` -- PostgreSQL persistence for Merkle anchor data.
|
||||
- **Merkle Anchor Scheduler Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/IMerkleAnchorScheduler.cs` -- scheduling contract for anchor operations.
|
||||
- **Postgres Merkle Anchor Scheduler**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/PostgresMerkleAnchorScheduler.cs` -- PostgreSQL-backed anchor scheduling.
|
||||
- **Null Merkle Anchor Scheduler**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/NullMerkleAnchorScheduler.cs` -- no-op scheduler for environments where Merkle anchoring is disabled.
|
||||
- **Ledger Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerHashing.cs` -- computes deterministic hashes of ledger events that become Merkle tree leaves.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a batch of ledger events, trigger the Merkle anchor worker, and verify a Merkle anchor record is created with the correct root hash and event range
|
||||
- [ ] Verify tamper detection: retrieve an anchored event, modify its payload, recompute the Merkle proof, and confirm the proof fails validation against the stored root hash
|
||||
- [ ] Verify the Merkle tree builder produces the same root hash when given the same event hashes in the same order
|
||||
- [ ] Verify anchor scheduling: configure a 10-second anchor interval and submit events over 30 seconds; confirm at least 3 anchor records are created
|
||||
- [ ] Verify the null scheduler correctly disables anchoring without errors when configured
|
||||
- [ ] Verify anchor persistence: create anchors, restart the service, and confirm previously stored anchors are retrievable from PostgreSQL
|
||||
|
||||
## Verification
|
||||
- Verified by QA FLOW run `run-001` on 2026-02-11.
|
||||
- Evidence: `docs/qa/feature-checks/runs/findings/merkle-anchoring-for-audit-integrity/run-001/` (Tier 0/1/2 artifacts).
|
||||
Reference in New Issue
Block a user