Artifex/docs/execution_graph_architecture.md

# Execution Graph Architecture

Date: 2026-08-15

## Implemented Architecture

Artifex now has two intentionally separate graph concepts.

Project DAG remains the canonical representation of what work exists:

- `Project`
- `Milestone`
- `Feature`
- `Task`
- `TaskDependency`

Execution Graph is now the canonical representation of how autonomous work is performed. It is runtime-neutral and persisted in Django/Postgres.

## Graph Domain Models

Implemented graph domain models:

- `ExecutionGraphDefinition`
- `ExecutionGraphVersion`
- `GraphRun`
- `GraphNodeRun`
- `GraphEdgeTraversal`
- `GraphApproval`

Execution graph version statuses:

- `DRAFT`
- `CHALLENGER`
- `CHAMPION`
- `RETIRED`

Graph run statuses:

- `PENDING`
- `RUNNING`
- `PAUSED`
- `COMPLETE`
- `FAILED`
- `CANCELLED`

Node runs persist status, timing, input/output metadata, failure evidence, telemetry, optional agent version, and optional model request reference.

Edge traversals persist selected conditional transitions.

## Graph Specification

Graph specs are serializable dictionaries with:

- name
- version
- graph type
- entry node
- nodes
- edges
- conditional edge labels
- terminal nodes
- metadata

Specs do not execute arbitrary Python. Node execution resolves through `NodeHandlerRegistry`.

## TaskExecutionGraph V1

`TaskExecutionGraph v1` mirrors the prior `AutonomousTaskLoop` behavior.

Nodes:

- `claim_task`
- `prepare_worktree`
- `build_context`
- `coder`
- `run_tests`
- `review`
- `judge`
- `commit`
- `retry_or_fail`
- `cleanup`
- `complete`
- `fail`

Important semantics preserved:

- deterministic test failure still reaches Reviewer
- Reviewer failure goes to retry/fail
- Judge failure goes to retry/fail
- maximum semantic task attempts remains three total attempts
- commit is guarded against duplicate commits on resume
- CoderToolLoop remains inside the `coder` node

## NativeGraphRuntime

`NativeGraphRuntime` is the reference implementation.

It supports:

- conditional edges
- loops
- persisted graph runs
- persisted node runs
- edge traversal history
- checkpoint/resume at major node boundaries
- terminal success/failure
- pause state
- cancellation
- graph events
- bounded metadata

Django/Postgres remains canonical for task, attempt, worktree, test, review, judge, commit, event, agent, and Progeny state.

## AutonomousTaskLoop Delegation

`AutonomousTaskLoop` still uses `TaskScheduler` to claim Project DAG work.

After a task is claimed, it now creates a `GraphRun` for the champion `TaskExecutionGraph v1` and delegates task lifecycle execution to `NativeGraphRuntime`.

The scheduler remains Project-DAG-oriented. The execution runtime handles task-attempt workflow.

## LangGraphRuntime

`LangGraphRuntime` is no longer a pure placeholder. It builds a LangGraph `StateGraph` from Artifex graph definitions when the `langgraph` package is installed.

Artifex remains runtime-neutral:

- Artifex owns graph definitions
- Artifex owns persisted graph state
- Artifex owns node contracts
- LangGraph is an execution backend

Current limitation: the local environment used during implementation did not have `langgraph` installed, so deterministic tests validate the adapter boundary and missing-dependency behavior. Full LangGraph execution parity requires installing the declared `langgraph>=0.2,<0.3` dependency in local/Spark environments.

## Checkpoint And Resume

Coarse checkpointing is implemented at graph node boundaries.

Resume behavior avoids repeating a completed interrupted node. Loop re-entry creates a new `GraphNodeRun` visit via `visit_index`.

Irreversible commit behavior is guarded by checking for an existing `CommitRecord` for the task before creating a new commit.

## Human Approval

Graph approval support is implemented with `GraphApproval`.

A node can pause the graph with `AWAITING_APPROVAL`. A signal can approve pending graph approvals and resume execution.

This is intentionally minimal and prepares future gates for risky migrations, deployment, Progeny promotion, destructive infrastructure changes, and project plan approvals.

## Subgraph Support

The graph spec supports runtime-neutral subgraph representation through node metadata.

CoderToolLoop is not moved into a subgraph yet. It remains inside the `coder` node.

## Graph Inspection

`graph_run_inspection()` exposes UI-ready JSON containing:

- graph/version
- node list
- edges
- node statuses
- current node
- durations
- failures
- selected edge traversals

This is sufficient for a future visual execution graph UI.

## Progeny Integration

`ProgenySignal` can now reference:

- `graph_run`
- `graph_node_run`
- `execution_graph_version`

This enables future investigations such as:

- failures by graph version
- failures by node type
- patch success rate by workflow version
- Reviewer rework changes after inserting a verification node

## Migrations

New migrations:

- `graph/0001_initial.py`
- `graph/0002_graphnoderun_visit_index.py`
- `graph/0003_graphapproval.py`
- `projects/0003_commitrecord_graph_run.py`
- `agents/0005_progenysignal_graph_lineage.py`

## Known Limitations

- Full LangGraph parity execution is implemented but not exercised in this environment because `langgraph` is not installed.
- Parallel branch execution is represented by the graph model but not executed concurrently by `NativeGraphRuntime`.
- Subgraph support is represented in the spec but not yet expanded into nested `GraphRun` execution.
- CoderToolLoop remains attempt-granularity for checkpointing.
- Graph telemetry is persisted at node level, but model request references are not yet automatically linked to individual node runs.
- Event Bus records graph facts but is not an orchestration engine.