 (ns fhofherr.simple.core.job-execution
+  "Create and manage job executions.
+
+  Job executions represent a single execution of a Simple CI job. A job
+  execution owns a [[job-descriptor]]. During its lifetime a job execution
+  transitions through the following states:
+
+  * *created*: the job execution has just been created.
+  * *queued*: the job execution has been queued for execution. It has not been
+    executed yet.
+  * *executing*: the job execution is currently executing.
+  * *finished*: the job execution is finished executing."
   (:require [fhofherr.simple.core [status-model :as sm]
              [job-execution-context :as ex-ctx]]))
 

          (sm/transition-to-state $ ::finished))))

(defn finished?
  [^JobExecution job-exec]
  (= ::finished (sm/current-state job-exec)))

    (update-in job-exec [:context] apply-f)))

(defn mark-executing
  "Mark `job-exec` as *executing*."
  [^JobExecution job-exec]
  (as-> job-exec $
        (update-context $ ex-ctx/mark-executing)
        (sm/transition-to-state $ ::executing)))

(defn executing?
  "Check if `job-exec`s state is *executing*."
  [^JobExecution job-exec]
  (= ::executing (sm/current-state job-exec)))

(defn mark-finished
  "Mark `job-exec` as *finished*."
  [^JobExecution job-exec]
  (letfn [(update-ctx [ctx] (if (ex-ctx/failed? ctx)
                              ctx
