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:**
+**Parameter forms:**
-- `postrin-interest-percentage`
+- `postrin-interest-<percentage|pc|threshold|thresh|thr>`
-- `postrin-interest-pc`
+- `negtrin-interest-<percentage|pc|threshold|thresh|thr>`
-- `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`
 
 **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)
+- The unit suffix rules from the top of this document apply here too
-- 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
 - 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
+This example sets the interest threshold to 50% for postrins
-negtrins (absolute threshold value).
+(percentage-based) and 30 for negtrins (absolute threshold value).
 
 ## Distraction Threshold Parameters
 
-**Synonyms:**
+**Parameter forms:**
-- `postrin-distraction-threshold`
+- `postrin-distraction-<percentage|pc|threshold|thresh|thr>`
-- `distraction-threshold`
+- `negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
-- `postrin-distraction`
-- `negtrin-distraction-threshold`
-- `negtrin-distraction`
 
 **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
+- The unit suffix rules from the top of this document apply here too
-  constructed and delivered with DISTRACTION importance
-- If multiple synonyms are specified, the lattermost (last encountered)
-  synonym takes precedence
 - 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:**
+**Parameter forms:**
-- `postrin-stupefaction-threshold`
+- `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`
-- `postrin-stupefaction`
+- `[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
-- `stupefaction-threshold`
-- `postrin-stupefying`
-- `stupefaction`
-- `stupefying`
 
 **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
+- The unit suffix rules from the top of this document apply here too
-  constructed and delivered with STUPEFYING importance
 - 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:**
+**Parameter forms:**
-- `negtrin-intolerable-threshold`
+- `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
-- `negtrin-intolerable`
-- `intolerable-threshold`
-- `intolerable`
 
 **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
+- The unit suffix rules from the top of this document apply here too
-  constructed and delivered with INTOLERABLE importance
 - 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.
 

docs/livox-gen1-lidar-dap-spec.md

@@ -46,15 +46,16 @@ Each stim-buff-api is designed to work with specific stim-iface libraries that u
 **Intrinsic Stimuli Support** (for pcloudAmbience quale-iface-api):
 The `pcloudAmbience` quale-iface-api exports both a postrin and a negtrin whose
 thresholds are configurable via standard quale-iface-api-params:
-- **Postrin interest threshold**: Configurable via `postrin-interest-percentage` / `postrin-interest-pc` / `postrin-interest` (default: 90, interpreted as percentage)
+- **Postrin interest threshold**: Configurable via `postrin-interest-[percentage|pc|threshold|thresh|thr]`
-- **Negtrin interest threshold**: Configurable via `negtrin-interest-percentage` / `negtrin-interest-pc` / `negtrin-interest-threshold` / `negtrin-interest-th` / `negtrin-interest` (default: 30)
+- **Negtrin interest threshold**: Configurable via `negtrin-interest-[percentage|pc|threshold|thresh|thr]`
 
-The postrin interest threshold is percentage-based only (0-100) and specifies the
+The `-percentage` and `-pc` variants take percentages in the range
-percentage of frames whose average intensity must be <= the ambience intensity low
+`0-100`. The `-threshold`, `-thresh`, and `-thr` variants take an
-value threshold. Frames whose average intensity is <= the ambience intensity low
+absolute number whose interpretation is defined by the API library
-value qualify for postrin, and frames whose average intensity is >= the negtrin
+itself. Users should specify only one unit-suffixed variant per targeted
-interest threshold qualify for negtrin. The ambience count written to each stimFrame
+intrinsic threshold; if multiple such variants are supplied, the
-is the number of frames that qualify for either intrinsic.
+lattermost one takes precedence. Shorthand forms without a unit suffix
+are not valid.
 
 ### 3. Point Cloud Coordinate Data Device (Extrospector)
 
@@ -258,4 +259,4 @@ The specification includes comprehensive error handling for:
 - Invalid coordinate format requests
 - IMU data stream interruptions
 - Device discovery failures
-- Connection retry timeouts
+- Connection retry timeouts