# 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