Capability Version Architecture
===============================

A capability request contains three components: The request itself, *at
least* one version, and *at least* one execution. On capability request
creation, and initial capability version is automatically created. Upon
version submission, a capability execution is created with an associated
Workflow Request.

Additional versions and executions can be created. When this occurs, the system maintains an awareness of the current
version and current execution. These are called the "current version" and "current execution," and are highlighted in
the following diagram:

.. image:: images/versions.png
    :width: 410px
    :height: 217px

What is a Capability Version?
-----------------------------

The concept of Capability Versions was based in part on the VLASS
Manager Jobs System and is meant to allow for multiple processing
iterations of the same requested dataset with differing input parameters
and files. This allows for the best results to be more easily obtained.

Many important lessons were learned from the VLASS Manager system and
the Workspaces developers have endeavored to avoid the worst of the
VLASS pitfalls with the design of the Workspaces Capability Version
System. To that end, while it is possible to create multiple versions
and executions of Workspaces Capability Requests, this functionality is
subject to a set of restrictions meant to ensure that system stability
is easily maintained.

Restrictions on Capability Versions
-----------------------------------

Given that a capability request may contain two or more versions, rules
governing the disposition of capability request versions become
necessary. These rules are implemented as follows.

-  While a Capability Request can have multiple versions, only one
   version may be QA Passed.
-  When one Capability Version is QA Passed, all other versions of the
   Request must be QA Failed.
-  Once a request is Completed as a result of QA Pass, the user is not
   permitted to make new versions.
-  While a Capability Version can have multiple Capability Executions, a
   new execution may only be created if the previous executions have all
   errored.
-  The user is not permitted to alter the Version’s parameters when
   creating a new execution.
-  Any Capability Execution should have one, and only one, workflow
   request.
-  There should only be one mutable version - i.e. one where the user
   can manipulate parameters and files - at any given time and this
   should be the current version. If a mutable version already exists a
   new version cannot be created.

These restrictions are enforced by the *Workspaces Restriction Engine*,
please see :doc:`restriction-engine` for more information.

Are all Capabilities Multiple Version Capable? No.
--------------------------------------------------

While Workspaces is designed to allow for the creation of multiple
versions on any request there are some Capabilities where having
multiple versions makes no logical sense.

Single Version Requests vs. Multi-Version Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two types of Workspaces Capabilities with respect to the
version system: *Single Version Only Requests* and *Multi-Version
Capable Requests*

Single Version Only
^^^^^^^^^^^^^^^^^^^

Currently, there is only one type of single version request possible:
the Download Capability. There is no logical reason to allow multiple
versions of downloads. A download either succeeds or fails.

Multi-Version Capable Requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are two types of Multi-Version requests: QA Requests and Non-QA
Requests.

When QA is required by the specified Capability definition, there are
specific restrictions that come into play, such as the restriction
preventing new versions after QA pass. Once QA Pass is run on a QA-able
request, that request is *sealed* against any further alterations, and
it’s chosen products are ingested.

When QA is *not* required by the specified Capability definition, a
request cannot be sealed and a user may make as many versions as they
wish, subject of course to restrictions, such as the restriction on
mutable versions.