semi implemented and features implemented save checkpoint

docs/features/unchecked/findings/admin-audit-trails.md

@@ -0,0 +1,29 @@
+# Admin audit trails (comprehensive logging of changes)
+
+## Module
+Findings
+
+## Status
+IMPLEMENTED
+
+## Description
+Policy evaluation trace snapshots, evidence graph builder, and exception event auditing provide admin-level audit trails for governance.
+
+## Implementation Details
+- **Ledger Event Write Service**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerEventWriteService.cs` -- writes append-only ledger events; every finding state change, VEX decision, and policy evaluation is recorded as an immutable event with timestamp, actor, and payload.
+- **Evidence Graph Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs` -- constructs evidence subgraphs from ledger events and attestation pointers for audit visualization.
+- **Attestation Pointer Service**: `src/Findings/StellaOps.Findings.Ledger/Services/AttestationPointerService.cs` -- links findings to their attestation evidence for audit chain tracking.
+- **Attestation Status Calculator**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Attestation/AttestationStatusCalculator.cs` -- computes attestation coverage status for audit dashboards.
+- **Decision Service**: `src/Findings/StellaOps.Findings.Ledger/Services/DecisionService.cs` (implements `IDecisionService`) -- records policy decisions with full trace context.
+- **Decision Hook Interface**: `src/Findings/StellaOps.Findings.Ledger/Services/IDecisionHook.cs` -- extension point for hooking into decision events for custom audit processing.
+- **Ledger Incident Coordinator**: `src/Findings/StellaOps.Findings.Ledger/Services/Incident/LedgerIncidentCoordinator.cs` -- coordinates incident response workflows with audit trail recording.
+- **Ledger Telemetry**: `src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTelemetry.cs` -- OpenTelemetry instrumentation for ledger operations providing trace-level audit visibility.
+- **Ledger Timeline**: `src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTimeline.cs` -- timeline view of ledger events for audit review.
+- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/FindingsLedgerIntegrationTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerEventWriteServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/LedgerEventWriteServiceIncidentTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Observability/LedgerTelemetryTests.cs`, `LedgerTimelineTests.cs`
+
+## E2E Test Plan
+- [ ] Submit a finding state change via `LedgerEventWriteService` and verify the event is recorded with correct timestamp, actor, and payload in the append-only ledger
+- [ ] Query the evidence graph for a finding that has multiple audit events and verify the graph shows the chronological chain of state changes
+- [ ] Trigger a policy decision and verify `DecisionService` records the full trace context (rule name, inputs, outcome) as an auditable event
+- [ ] Verify incident coordination audit: create an incident via `LedgerIncidentCoordinator` and confirm the incident creation, status changes, and resolution are all recorded in the ledger
+- [ ] Verify telemetry integration: perform a ledger operation and confirm OpenTelemetry spans are emitted with the correct operation name and attributes

docs/features/unchecked/findings/attested-reduction-scoring-in-findings-ledger.md

@@ -0,0 +1,27 @@
+# Attested Reduction Scoring in Findings Ledger
+
+## Module
+Findings
+
+## Status
+IMPLEMENTED
+
+## Description
+Anchor-aware evidence wiring into Findings Ledger scoring with reduction profile metadata, hard-fail flag, short-circuit reason, and anchor metadata (DSSE envelope digest, Rekor log index/entry) in API responses.
+
+## Implementation Details
+- **Finding Scoring Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs` -- computes attested reduction scores combining CVSS base score with reachability, VEX, and attestation evidence; includes anchor metadata (DSSE digest, Rekor index) in the score breakdown.
+- **Finding Evidence Provider**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingEvidenceProvider.cs` -- resolves evidence artifacts for scoring, including attestation anchors and proof chain references.
+- **Scoring Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/ScoringContracts.cs` -- API DTOs including reduction profile, hard-fail flag, short-circuit reason, and anchor metadata fields.
+- **Attestation Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/AttestationContracts.cs` -- DTOs for attestation evidence references in scoring responses.
+- **Attestation Pointer Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/AttestationPointerContracts.cs` -- DTOs for attestation pointer queries.
+- **Attestation Query Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/AttestationQueryService.cs` -- queries attestation evidence linked to findings for scoring input.
+- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- REST endpoints exposing scored findings with attested reduction metadata.
+- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/FindingScoringServiceTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Exports/AttestationQueryServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`
+
+## E2E Test Plan
+- [ ] Submit a finding with a DSSE-attested reachability proof and verify the scoring response includes the reduction from the attestation with anchor metadata (DSSE digest, Rekor log index)
+- [ ] Submit a finding with a hard-fail attestation (e.g., missing required evidence) and verify the score response includes `hardFail: true` with the short-circuit reason
+- [ ] Verify reduction profile: submit a finding with multiple evidence types and verify the response includes a breakdown of each reduction source and its contribution percentage
+- [ ] Verify the scoring endpoint returns anchor metadata: query a scored finding and confirm the response includes `dsseEnvelopeDigest` and `rekorLogIndex` fields
+- [ ] Verify short-circuit: submit a finding with an "affected" VEX status and verify scoring short-circuits with the appropriate reason without evaluating further reductions

docs/features/unchecked/findings/cvss-vex-sorting.md

@@ -0,0 +1,26 @@
+# CVSS/VEX Sorting (Multi-Dimension)
+
+## Module
+Findings
+
+## Status
+IMPLEMENTED
+
+## Description
+CVSS v4.0 scoring engine combined with findings summary builder supports multi-dimensional sorting by CVSS and VEX status.
+
+## Implementation Details
+- **Finding Summary Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingSummaryBuilder.cs` -- builds finding summaries with sortable dimensions including CVSS score, VEX status, severity, and component name.
+- **Finding Summary Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingSummaryService.cs` -- queries and sorts finding summaries by multiple dimensions.
+- **Finding Summary Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs` -- REST endpoints for querying sorted finding summaries with multi-dimension ordering.
+- **Finding Summary DTO**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/FindingSummary.cs` -- API response model including CVSS score, VEX status, severity level, and component identity.
+- **VEX Consensus Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs` -- aggregates VEX decisions across multiple sources to determine consensus status for sorting.
+- **VEX Lens Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/VexLensContracts.cs` -- DTOs for VEX status data used in multi-dimension sorting.
+- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/FindingSummaryBuilderTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/ScoredFindingsQueryServiceTests.cs`
+
+## E2E Test Plan
+- [ ] Query finding summaries sorted by CVSS score descending and verify the results are ordered from highest to lowest CVSS score
+- [ ] Query finding summaries sorted by VEX status and verify findings are grouped by status (affected, not_affected, under_investigation, fixed)
+- [ ] Apply multi-dimension sorting (primary: VEX status, secondary: CVSS score) and verify the ordering respects both dimensions
+- [ ] Verify findings with no VEX status are sorted correctly (treated as "no_vex" or equivalent default)
+- [ ] Submit findings with mixed CVSS v3.1 and v4.0 scores and verify the summary builder normalizes them for consistent sorting

docs/features/unchecked/findings/findings-ledger-with-append-only-events.md

@@ -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

docs/features/unchecked/findings/ledger-projections.md

@@ -0,0 +1,26 @@
+# Ledger Projections
+
+## Module
+Findings
+
+## Status
+IMPLEMENTED
+
+## Description
+Projection worker that materializes event streams into queryable read models.
+
+## Implementation Details
+- **Ledger Projection Worker**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Projection/LedgerProjectionWorker.cs` -- background worker that consumes ledger event streams and materializes them into queryable projection read models.
+- **Ledger Projection Reducer**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerProjectionReducer.cs` -- reduces event sequences into projection state, applying each event to build the current finding state from its event history.
+- **Projection Models**: `src/Findings/StellaOps.Findings.Ledger/Domain/ProjectionModels.cs` -- read-side projection models materialized from events (finding state, VEX status, scoring state).
+- **Projection Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/ProjectionHashing.cs` -- computes deterministic hashes of projection state for consistency verification between replays.
+- **Finding Projection Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/IFindingProjectionRepository.cs` -- persistence contract for materialized projections.
+- **Postgres Finding Projection Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresFindingProjectionRepository.cs` -- PostgreSQL persistence for projection read models.
+- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerProjectionReducerTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/ProjectionHashingTests.cs`
+
+## E2E Test Plan
+- [ ] Submit a sequence of finding events (create, update VEX, add attestation) and verify the projection worker materializes the final finding state with correct VEX status and attestation references
+- [ ] Verify projection consistency: replay the same event sequence twice and confirm the projection hashes match (deterministic projection)
+- [ ] Verify projection catch-up: stop the projection worker, submit events, restart the worker, and confirm it processes all missed events and reaches the correct state
+- [ ] Verify the projection reducer correctly handles out-of-order event delivery by ordering events by sequence number before applying
+- [ ] Query the materialized projection via the finding query endpoints and verify the response matches the expected state from the event history

docs/features/unchecked/findings/ledger-replay-determinism.md

@@ -0,0 +1,27 @@
+# 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

docs/features/unchecked/findings/merkle-anchoring-for-audit-integrity.md

@@ -0,0 +1,29 @@
+# Merkle Anchoring for Audit Integrity
+
+## Module
+Findings
+
+## Status
+IMPLEMENTED
+
+## 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