Docs: Intrins now require units.

docs/design/intrin-thresholds.md

@@ -9,20 +9,42 @@ allow the stimbuff API library to determine when to construct a stencil
 for postrin or negtrin data and present it to SMO with appropriate
 importance classifications.
 
+## Unit Suffix Rules
+
+All intrinsic threshold params must include an explicit unit suffix.
+These suffix families are not synonyms with each other; they select
+different units:
+
+- `-percentage`/`-pc`
+- `-threshold`/`-thresh`/`-thr`
+
+Parameters with the `-percentage` or `-pc` suffix take a percentage in
+the range `0-100`.
+
+Parameters with the `-threshold`, `-thresh`, or `-thr` suffix take an
+absolute number. The interpretation of that number, and the underlying
+unit, is defined by the API library itself.
+
+Users must specify only one unit-suffixed parameter per targeted
+intrinsic classification. If multiple unit-suffixed variants targeting
+the same classification are supplied anyway, the lattermost supplied
+parameter takes precedence.
+
+Shorthand params without a unit suffix are not permitted anymore. The
+following forms are invalid because they all omit units:
+
+- `[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>`
+
+For stupefying and intolerable thresholds specifically, the `postrin-`
+or `negtrin-` prefix may be omitted when the intended intrinsic is
+already implied by the classification itself. Even in those cases, a
+unit suffix is still mandatory.
+
 ## Interest Threshold Parameters
 
-**Synonyms:**
-- `postrin-interest-percentage`
-- `postrin-interest-pc`
-- `postrin-interest-threshold`
-- `postrin-interest-th` (abbreviation for `-threshold`)
-- `interest-threshold`
-- `postrin-interest`
-- `negtrin-interest-percentage`
-- `negtrin-interest-pc`
-- `negtrin-interest-threshold`
-- `negtrin-interest-th` (abbreviation for `-threshold`)
-- `negtrin-interest`
+**Parameter forms:**
+- `postrin-interest-<percentage|pc|threshold|thresh|thr>`
+- `negtrin-interest-<percentage|pc|threshold|thresh|thr>`
 
 **Description:**
 These parameters denote the value at which the stimbuff API library
@@ -33,30 +55,23 @@ postrinInd/negtrinInd with the "importance" argument set to "INTERESTING".
 **Specification:**
 - The parameter is specified as part of the `quale-iface-api-params`
   in the DAP specification
-- Parameters with the `-percentage` or `-pc` suffix are interpreted as percentages (0-100)
-- Parameters with the `-threshold` or `-th` suffix are interpreted as absolute threshold values
-- The `-threshold` suffix can be abbreviated as `-th`
-- If multiple synonyms are specified, the lattermost (last encountered)
-  synonym takes precedence
+- The unit suffix rules from the top of this document apply here too
 - Separate thresholds can be specified for postrin and negtrin using the
   respective prefixes
 
 **Example:**
-```
-+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-threshold=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
-```
+````
++idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-thr=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
+````
 
-This example sets the interest threshold to 50% for postrins (percentage-based) and 30 for
-negtrins (absolute threshold value).
+This example sets the interest threshold to 50% for postrins
+(percentage-based) and 30 for negtrins (absolute threshold value).
 
 ## Distraction Threshold Parameters
 
-**Synonyms:**
-- `postrin-distraction-threshold`
-- `distraction-threshold`
-- `postrin-distraction`
-- `negtrin-distraction-threshold`
-- `negtrin-distraction`
+**Parameter forms:**
+- `postrin-distraction-<percentage|pc|threshold|thresh|thr>`
+- `negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
 
 **Description:**
 These parameters denote the value at which the stimbuff API library
@@ -66,30 +81,23 @@ negtrinInd/postrinInd with the importance argument set to "DISTRACTION".
 **Specification:**
 - The parameter is specified as part of the `quale-iface-api-params`
   in the DAP specification
-- The value is a numeric threshold that determines when stencils are
-  constructed and delivered with DISTRACTION importance
-- If multiple synonyms are specified, the lattermost (last encountered)
-  synonym takes precedence
+- The unit suffix rules from the top of this document apply here too
 - Separate thresholds can be specified for postrin and negtrin using the
   respective prefixes
 
 **Example:**
-```
-+idev|my-device|pcloudIntensity(negtrin-distraction-threshold=60|postrin-distraction-threshold=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
-```
+````
++idev|my-device|pcloudIntensity(negtrin-distraction-thr=60|postrin-distraction-thr=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
+````
 
 This example sets the distraction threshold to 60 for negtrins and 40
 for postrins.
 
 ## Stupefying Threshold Parameters (Postrin)
 
-**Synonyms:**
-- `postrin-stupefaction-threshold`
-- `postrin-stupefaction`
-- `stupefaction-threshold`
-- `postrin-stupefying`
-- `stupefaction`
-- `stupefying`
+**Parameter forms:**
+- `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`
+- `[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
 
 **Description:**
 These parameters denote the value at which the stimbuff API library
@@ -99,27 +107,21 @@ the importance argument set to "STUPEFYING".
 **Specification:**
 - The parameter is specified as part of the `quale-iface-api-params`
   in the DAP specification
-- The value is a numeric threshold that determines when stencils are
-  constructed and delivered with STUPEFYING importance
+- The unit suffix rules from the top of this document apply here too
 - These parameters apply only to postrin data (positive intrinsic
   stimuli)
-- If multiple synonyms are specified, the lattermost (last encountered)
-  synonym takes precedence
 
 **Example:**
-```
-+idev|my-device|pcloudIntensity(postrin-stupefying=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
-```
+````
++idev|my-device|pcloudIntensity(stupefying-thr=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
+````
 
 This example sets the stupefying threshold to 80 for postrins.
 
 ## Intolerable Threshold Parameters (Negtrin)
 
-**Synonyms:**
-- `negtrin-intolerable-threshold`
-- `negtrin-intolerable`
-- `intolerable-threshold`
-- `intolerable`
+**Parameter forms:**
+- `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
 
 **Description:**
 These parameters denote the value at which the stimbuff API library
@@ -129,17 +131,14 @@ the importance argument set to "INTOLERABLE".
 **Specification:**
 - The parameter is specified as part of the `quale-iface-api-params`
   in the DAP specification
-- The value is a numeric threshold that determines when stencils are
-  constructed and delivered with INTOLERABLE importance
+- The unit suffix rules from the top of this document apply here too
 - These parameters apply only to negtrin data (negative intrinsic
   stimuli)
-- If multiple synonyms are specified, the lattermost (last encountered)
-  synonym takes precedence
 
 **Example:**
-```
-+idev|my-device|pcloudIntensity(negtrin-intolerable=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
-```
+````
++idev|my-device|pcloudIntensity(intolerable-thr=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
+````
 
 This example sets the intolerable threshold to 90 for negtrins.