salmanoff/docs/design/intrin-thresholds.md

# Intrinsic Threshold Parameters

## Overview

This document describes quale-iface-api-params that control threshold
values for constructing stencils and delivering them to SMO via
postrinInd/negtrinInd with different importance levels. These parameters
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.

**Intrinsic parameters may appear only on dedicated intrinsic qualeIfaceApi
specs.** The only supported forms are **`negtrin(...)`** and **`postrin(...)`**.
You cannot attach intrinsic threshold params to a sensory or other
non-intrinsic qualeIfaceApi (for example `pcloudIntensity`, `pcloudAmbience`,
`mesh`, `pcloud`, and so on). Those lines are for sensory streams only.

A dedicated intrinsic line must name the sensory stimbuff it derives from via
**`from-stimbuff=<qualeIfaceApi>`** (non-empty). Policy validation rejects
intrinsic params and passband-style comparators on sensory lines, and rejects
dedicated lines that omit `from-stimbuff`.

## Dedicated `negtrin` / `postrin` qualeIfaceApi names

On **`negtrin(...)`** or **`postrin(...)`**, the intrinsic family (negative vs
positive) is fixed by the API name. The **`negtrin-`** and **`postrin-`**
prefixes on parameter names are **optional**: you may use short forms
**`interest-...`**, **`distraction-...`**, **`stupefaction-` / `stupefying-...`**,
and **`intolerable-...`** with the unit suffix rules below. Prefixed names such
as **`negtrin-interest-pc`** remain valid when you prefer explicit spelling.

Example (negtrin driven by ambience, short interest param, passband comparator):

````
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
````

## 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. The following
forms are invalid because they omit units:

- `[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>`

On dedicated **`postrin(...)`** / **`negtrin(...)`** lines, the short forms
**`interest-...`**, **`distraction-...`**, etc. still require those unit
suffixes.

## Interest Threshold Parameters

**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**

- Prefixed: `postrin-interest-<percentage|pc|threshold|thresh|thr>`,
  `negtrin-interest-<percentage|pc|threshold|thresh|thr>`
- Short (prefix optional because the line is already negtrin or postrin):
  `interest-<percentage|pc|threshold|thresh|thr>`

**Description:**
These parameters denote the value at which the stimbuff API library
should construct a stencil for the postrin or negtrin that it delivers
for this intrinsic spec, and present it to SMO via postrinInd/negtrinInd
with the "importance" argument set to "INTERESTING".

**Example (dedicated negtrin line):**
````
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
````

## Distraction Threshold Parameters

**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**

- Prefixed: `postrin-distraction-<percentage|pc|threshold|thresh|thr>`,
  `negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
- Short: `distraction-<percentage|pc|threshold|thresh|thr>` (family is
  fixed by the `negtrin` / `postrin` API name)

**Description:**
These parameters denote the value at which the stimbuff API library
ought to construct a stencil and deliver it to SMO via
negtrinInd/postrinInd with the importance argument set to "DISTRACTION".

## Stupefying Threshold Parameters (Postrin)

**Parameter forms (only inside `postrin(...)`):**

- Prefixed: `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`,
  `[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
- Short: `stupefaction-...`, `stupefying-...` with unit suffix

**Description:**
These parameters denote the value at which the stimbuff API library
ought to construct a stencil and deliver it to SMO via postrinInd with
the importance argument set to "STUPEFYING".

## Intolerable Threshold Parameters (Negtrin)

**Parameter forms (only inside `negtrin(...)`):**

- Prefixed: `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
- Short: `intolerable-<percentage|pc|threshold|thresh|thr>`

**Description:**
These parameters denote the value at which the stimbuff API library
ought to construct a stencil and deliver it to SMO via negtrinInd with
the importance argument set to "INTOLERABLE".

## Notes

The way that SMO handles these importance levels is not yet fully worked
out. For postrins, the distinction between "interesting" vs "stupefying"
is somewhat reasonably intuitively clear, but how that meaning is given
in code has not been worked out yet. Similarly, for negtrins, the
distinctions between "interesting" vs "distracting" vs "intolerable"
are not entirely clear in terms of how their handling will impose
meaningful differences that will give meaning to their distinctions.

These parameters provide the mechanism for the stimbuff API library to
classify and deliver intrinsic stimuli with appropriate importance
levels, but the downstream processing and behavioral implications of
these classifications within SMO remain to be fully defined.