40 lines
4.1 KiB
Markdown
40 lines
4.1 KiB
Markdown
# Orchestrator Audit Ledger
|
|
|
|
## Module
|
|
Orchestrator
|
|
|
|
## Status
|
|
IMPLEMENTED
|
|
|
|
## Description
|
|
Append-only audit ledger tracking all orchestrator job lifecycle state changes, rate-limit decisions, and dead-letter events with tenant-scoped isolation.
|
|
|
|
## Implementation Details
|
|
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/DeadLetter/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Ledger/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/`
|
|
- **Key Classes**:
|
|
- `AuditEntry` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/AuditEntry.cs`) - audit entry model with action type, actor, tenant, timestamp, and metadata
|
|
- `RunLedger` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/RunLedger.cs`) - run-level ledger tracking execution history
|
|
- `SignedManifest` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/SignedManifest.cs`) - signed manifest for tamper-evident ledger export
|
|
- `LedgerExporter` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Ledger/LedgerExporter.cs`) - exports ledger data for compliance and audit
|
|
- `AuditEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/AuditEndpoints.cs`) - REST API for querying audit ledger entries
|
|
- `LedgerEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/LedgerEndpoints.cs`) - REST API for ledger export and querying
|
|
- `AuditLedgerContracts` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Contracts/AuditLedgerContracts.cs`) - API contracts for audit responses
|
|
- `DeadLetterEntry` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/DeadLetterEntry.cs`) - dead-letter entry in the audit trail
|
|
- `DeadLetterNotifier` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/DeadLetter/DeadLetterNotifier.cs`) - notifies on dead-letter events
|
|
- `ErrorClassification` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/DeadLetter/ErrorClassification.cs`) - classifies errors for dead-letter categorization
|
|
- `ReplayManager` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/DeadLetter/ReplayManager.cs`) - manages replay of dead-letter entries
|
|
- `DeadLetterEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/DeadLetterEndpoints.cs`) - REST API for dead-letter management
|
|
- `TenantResolver` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Services/TenantResolver.cs`) - ensures tenant-scoped audit isolation
|
|
- **Interfaces**: `ILedgerExporter` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Ledger/ILedgerExporter.cs`), `IAuditRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/IAuditRepository.cs`), `IDeadLetterRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/DeadLetter/IDeadLetterRepository.cs`), `ILedgerRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/ILedgerRepository.cs`)
|
|
- **Source**: Feature matrix scan
|
|
|
|
## E2E Test Plan
|
|
- [ ] Trigger a job state transition and verify an `AuditEntry` is created in the ledger with action type, actor, and timestamp
|
|
- [ ] Query the audit ledger via `AuditEndpoints` with a time range filter and verify only matching entries are returned
|
|
- [ ] Verify tenant isolation via `TenantResolver`: create audit entries for two tenants and verify each tenant only sees their own entries
|
|
- [ ] Trigger a dead-letter event and verify it appears in both the `DeadLetterEntry` store and the audit ledger
|
|
- [ ] Export the audit ledger via `LedgerExporter` and verify the export contains all entries within the specified range
|
|
- [ ] Replay a dead-letter entry via `ReplayManager` and verify the replay action is also audited
|
|
- [ ] Verify `ErrorClassification` categorizes different error types correctly (transient, permanent, unknown)
|
|
- [ ] Query dead-letter entries via `DeadLetterEndpoints` and verify pagination and filtering work
|