# Orchestrator Admin Quota Controls (orch:quota, orch:backfill)

## Module
Orchestrator

## Status
IMPLEMENTED

## Description
New `orch:quota` and `orch:backfill` scopes with mandatory reason/ticket fields. Token requests must include `quota_reason`/`backfill_reason` and optionally `quota_ticket`/`backfill_ticket`. Authority persists these as claims and audit properties for traceability of capacity-affecting operations.

## Implementation Details
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Backfill/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/`
- **Key Classes**:
  - `Quota` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Quota.cs`) - quota entity with limits, current usage, and allocation metadata
  - `BackfillRequest` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/BackfillRequest.cs`) - backfill request model with reason, ticket, and scope
  - `BackfillManager` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Backfill/BackfillManager.cs`) - manages backfill operations with duplicate suppression and event time window tracking
  - `DuplicateSuppressor` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Backfill/DuplicateSuppressor.cs`) - prevents duplicate backfill requests within a time window
  - `EventTimeWindow` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Backfill/EventTimeWindow.cs`) - time window for backfill event deduplication
  - `QuotaEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/QuotaEndpoints.cs`) - REST API for quota management (view, adjust, allocate)
  - `QuotaContracts` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Contracts/QuotaContracts.cs`) - API contracts for quota operations
  - `AuditEntry` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/AuditEntry.cs`) - audit entry capturing quota/backfill actions with reason and ticket
  - `TenantResolver` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Services/TenantResolver.cs`) - resolves tenant context for quota scoping
- **Interfaces**: `IQuotaRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/IQuotaRepository.cs`), `IBackfillRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/IBackfillRepository.cs`)
- **Source**: Feature matrix scan

## E2E Test Plan
- [ ] Request a quota adjustment via `QuotaEndpoints` with `quota_reason` and `quota_ticket`; verify the adjustment is applied and audited in `AuditEntry`
- [ ] Attempt a quota adjustment without `quota_reason` and verify it is rejected with a 400 error
- [ ] Request a backfill via `BackfillManager` with `backfill_reason` and verify the backfill is initiated
- [ ] Submit a duplicate backfill request within the `EventTimeWindow` and verify `DuplicateSuppressor` rejects it
- [ ] Verify audit trail: check the `AuditEntry` for the quota adjustment and confirm reason and ticket are captured
- [ ] Query current quota usage via `QuotaEndpoints` and verify limits and current usage are returned
- [ ] Adjust quota beyond the maximum limit and verify the operation is rejected by policy
- [ ] Verify tenant scoping via `TenantResolver`: adjust quota for tenant A and verify tenant B's quota is unchanged