stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
6be4a25d178319a8f79ecea48434cff0174482d3
git.stella-ops.org/docs/features/checked/jobengine/jobengine-audit-ledger.md

4.1 KiB
Raw Blame History

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