# Orchestrator Operator Scope with Audit Metadata

## Module
Orchestrator

## Status
VERIFIED

## Description
New `orch:operate` scope and `Orch.Operator` role requiring explicit `operator_reason` and `operator_ticket` parameters on token requests. Authority enforces these fields and captures them as audit properties, giving SecOps traceability for every orchestrator control action.

## Implementation Details
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/`
- **Key Classes**:
  - `AuditEntry` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/AuditEntry.cs`) - audit entry capturing operator actions with reason and ticket metadata
  - `TenantResolver` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Services/TenantResolver.cs`) - resolves tenant and operator context from token claims
  - `AuditEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/AuditEndpoints.cs`) - REST API for querying operator audit trail
  - `AuditLedgerContracts` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Contracts/AuditLedgerContracts.cs`) - API contracts including operator metadata
  - `Quota` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Quota.cs`) - quota model with operator attribution
  - `Job` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Job.cs`) - job model with operator tracking
  - `DeprecationHeaders` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Services/DeprecationHeaders.cs`) - deprecation header support for versioned operator APIs
- **Interfaces**: `IAuditRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/IAuditRepository.cs`)
- **Source**: Feature matrix scan

## E2E Test Plan
- [ ] Request a token with `orch:operate` scope, `operator_reason="maintenance"`, and `operator_ticket="TICKET-123"`; verify the token is issued
- [ ] Perform an operator action (e.g., cancel a job) with the scoped token; verify an `AuditEntry` captures the operator_reason and operator_ticket
- [ ] Attempt an operator action without `operator_reason` and verify it is rejected with a 400 error
- [ ] Query the audit trail via `AuditEndpoints` and filter by operator_ticket; verify matching entries are returned
- [ ] Verify operator scope enforcement: use a token without `orch:operate` scope and verify operator actions are forbidden (403)
- [ ] Perform multiple operator actions and verify each generates a separate `AuditEntry` with correct metadata
- [ ] Verify tenant scoping via `TenantResolver`: operator actions for tenant A are not visible in tenant B's audit trail
- [ ] Verify audit entry immutability: attempt to modify an existing `AuditEntry` and verify it is rejected

## Verification
- Verified on 2026-02-13 via `run-002`.
- Tier 0: Source files confirmed present on disk.
- Tier 1: `dotnet build` passed (0 errors); 1292/1292 tests passed.
- Tier 2d: `docs/qa/feature-checks/runs/jobengine/orchestrator-operator-scope-with-audit-metadata/run-002/tier2-integration-check.json`