Fleshing out the Capability Version and Restriction Engine Documentation

docs/source/architecture/capability_versions.md

-# Capability Versions
+# Capability Version Architecture
 
-## What is a capability version?
+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.
 
-A capability request, once created, can have one or more additional versions of the request
-created via its request status page. As soon as a new version is created, the original
-request is designated version 1; subsequent versions, if any, are then numbered sequentially.
+## What is a Capability Version?
 
-## Restrictions on capability versions
+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.
 
-* **One of the versions has passed QA**
-  * capability request state of passed version is set to *Complete*
-  * every other version's state is set to *Failed*
-  * no new versions may be created on this request
+* 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 the engine's associated
+documentation 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.
 
-* **One of the versions has failed QA**
-  * the version that has been failed has its state set to *Failed*
+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.
 
-* **All the versions have failed QA**
-  * each version has its state set to *Failed*
-  * the capability request is set to *Failed*

docs/source/architecture/envoys.md

@@ -9,7 +9,7 @@ interacting with a system external to Workspaces from within a workflow. This in
 required inputs are present and correct as well and launching the external system in question.
 
 ## When should I build a new Envoy?
-If you are needing to interact with a system external to workspaces, i.e. a system which is *not built and maintained
+If you are needing to interact with a system external to workspaces, i.e. *a system which is not built and maintained
 within the workspaces project*, you should create an envoy. Examples of external systems Workspaces
 interacts with are CASA or the *ingest* system.
 
@@ -20,14 +20,14 @@ essential functions: Setup and Launch.
 ### Basic Envoy Architecture
 An envoy is expected to be extensible if required, i.e. it should be able to launch multiple types of calls to the
 system of interest. As such, envoys should typically have the following structure:
-- a main entry point which determines which type of call to make based on supplied parser input, this file is typically
+- A main entry point which determines which type of call to make based on supplied parser input, this file is typically
 named after the envoy (unless it's the main file for CASA Envoy which is aptly named "palaver")
 - A number of typed launcher classes which handle the type specific setup (typically broken up into other classes)
-and then make the call system to execute. These classes are typically contained in a file called *launchers.py* but can
+and then make the call to execute the external system. These classes are typically contained in a file called *launchers.py* but can
 also rely on any number of other classes for setup functionality.
 
-Example: CASA Envoy has two main classes *palaver.py*, the entry point, and *launchers.py*, which contains the
-CalibraitonLauncher and ImageLauncher classes. However, the package also contains the setup helper modules *auditor.py*
+Example: CASA Envoy has two main modules *palaver.py*, the entry point, and *launchers.py*, which contains the
+CalibrationLauncher and ImageLauncher classes. However, the package also contains the setup helper modules *auditor.py*
 and *foundation.py*, which audit the input files for required fields and correct for HTCondor submission, and ensure
 all data is in the required locations for CASA execution respectively.
 

docs/source/architecture/restriction_engine.md

+# Restriction Engine Architecture
+
+## What is the Restriction Engine?
+
+The Workspaces Restriction Engine is a system designed to enforce the limitations of the Capability Version 
+system design (See Capability Version Architecture for details).
+
+In order to provide a stable and effective Capability Version system, it is necessary to enforce a number
+of functionality restrictions. These restrictions are defined, evaluated, and enforced by the Restriction
+Engine.
+
+### What is a Rules Engine?
+
+Most simply, a Rules Engine is a software design pattern meant to create concise and flexible conditional
+code. A Rules Engine simply manages and executes a set of predefined Rules. A Rule contains two components:
+A Condition and An Effect. The condition is evaluated for truthiness and, if true, then the Effect is
+applied.
+
+This pattern was chosen for the Restriction Engine due to its ability to centralize decision-making
+logic, making it possible to build a single management system that could then be called where needed
+rather than being forced to embed the same conditional logic repeatedly in over a dozen places. 
+
+
+
+