34 lines
3.6 KiB
Markdown
34 lines
3.6 KiB
Markdown
# 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
|