# Scheduler Graph Job DTOs (GraphBuildJob/GraphOverlayJob)

## Module
Scheduler

## Status
VERIFIED

## Description
New graph-specific job contracts (GraphBuildJob, GraphOverlayJob) with state machine enforcement, metadata fields, and event schemas for graph build/overlay operations coordination between Scheduler and Cartographer/Graph services.

## Implementation Details
- **Graph Build Job Request**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/GraphBuildJobRequest.cs` -- DTO for graph build job requests with source, target, and metadata fields for triggering full graph rebuilds.
- **Graph Overlay Job Request**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/GraphOverlayJobRequest.cs` -- DTO for incremental graph overlay operations that merge new data into existing graphs.
- **Graph Job Service**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/GraphJobService.cs` -- orchestrates graph job lifecycle with state machine enforcement (Pending, Running, Completed, Failed).
- **In-Memory Graph Job Store**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/InMemoryGraphJobStore.cs` -- in-memory persistence for graph job state.
- **Cartographer Webhook Client**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/CartographerWebhookClient.cs` -- HTTP client for notifying the Cartographer service of graph job state changes.
- **Graph Job Endpoints**: `src/Scheduler/StellaOps.Scheduler.WebService/GraphJobs/GraphJobEndpointExtensions.cs` -- REST endpoints for submitting, querying, and managing graph jobs.
- **Tests**: `src/Scheduler/__Tests/StellaOps.Scheduler.WebService.Tests/GraphJobServiceTests.cs`, `src/Scheduler/__Tests/StellaOps.Scheduler.WebService.Tests/GraphJobEndpointTests.cs`, `src/Scheduler/__Tests/StellaOps.Scheduler.WebService.Tests/CartographerWebhookClientTests.cs`

## E2E Test Plan
- [x] Submit a `GraphBuildJobRequest` via the REST endpoint and verify it is created with pending status and metadata.
- [x] Advance job lifecycle via completion webhook path and verify state updates are enforced.
- [x] Submit a `GraphOverlayJobRequest` and verify overlay lag metrics/reporting behavior.
- [x] Verify webhook notification behavior for enabled and disabled modes.
- [x] Verify unauthorized endpoint access is rejected.

## Verification
- Verified on 2026-02-11 via FLOW Tier 0/1/2 replay in `run-003`.
- Tier 0: `docs/qa/feature-checks/runs/scheduler/scheduler-graph-job-dtos/run-003/tier0-source-check.json` (partial: stale doc test path `GraphJobEndpointsTests.cs`; implementation uses `GraphJobEndpointTests.cs`).
- Tier 1: `docs/qa/feature-checks/runs/scheduler/scheduler-graph-job-dtos/run-003/tier1-build-check.json`
- Tier 2: `docs/qa/feature-checks/runs/scheduler/scheduler-graph-job-dtos/run-003/tier2-api-check.json`
- Tier 2 evidence: `docs/qa/feature-checks/runs/scheduler/scheduler-graph-job-dtos/run-003/evidence/`