# DAG Planner with Critical-Path Metadata

## Module
Orchestrator

## Status
IMPLEMENTED

## Description
DAG-based job planner that computes critical-path metadata for orchestrator execution plans, enabling dependency-aware scheduling and parallel execution of independent job chains.

## Implementation Details
- **Modules**: `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Scheduling/`, `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/`
- **Key Classes**:
  - `DagPlanner` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Scheduling/DagPlanner.cs`) - computes execution DAGs from job dependency graphs, identifies critical path, and enables parallel scheduling of independent chains
  - `DagEdge` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/DagEdge.cs`) - edge model representing dependencies between jobs in the execution DAG
  - `JobScheduler` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Scheduling/JobScheduler.cs`) - schedules jobs based on DAG planner output, respecting dependency ordering
  - `JobStateMachine` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Scheduling/JobStateMachine.cs`) - state machine governing job lifecycle transitions within the DAG execution
  - `Job` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/Job.cs`) - job entity with status, dependencies, and scheduling metadata
  - `JobStatus` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/JobStatus.cs`) - enum defining job lifecycle states
  - `JobHistory` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Core/Domain/JobHistory.cs`) - historical record of job state transitions
  - `DagEndpoints` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/DagEndpoints.cs`) - REST API for querying DAG execution plans
  - `DagContracts` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Contracts/DagContracts.cs`) - API contracts for DAG responses
- **Interfaces**: `IDagEdgeRepository` (`src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/Repositories/IDagEdgeRepository.cs`)
- **Source**: Feature matrix scan

## E2E Test Plan
- [ ] Create a DAG with 5 jobs (A->B->C, A->D->E) and verify `DagPlanner` identifies A as the root and C/E as leaves
- [ ] Verify critical path computation: the longest dependency chain (A->B->C or A->D->E) is marked as the critical path
- [ ] Schedule the DAG via `JobScheduler` and verify B and D execute in parallel after A completes
- [ ] Add a new dependency (D->C) creating a diamond DAG and verify the critical path updates
- [ ] Query the DAG via `DagEndpoints` and verify the response includes all edges, critical path markers, and parallel groups
- [ ] Create a cyclic DAG (A->B->A) and verify `DagPlanner` rejects it with a cycle detection error
- [ ] Verify DAG metadata: each job node in the `DagContracts` response includes estimated duration and dependency count
- [ ] Schedule a DAG with one failed job and verify `JobStateMachine` marks downstream dependencies as blocked