stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
e716bc6adca8d1a3ac5a24ad491e5fa99e31cf1c
git.stella-ops.org/docs/features/unchecked/findings/findings-ledger-with-append-only-events.md

3.6 KiB
Raw Blame History

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