Lg1: Implement both light|darkAmbience stimBuffs & their production

We now produce both light and dark ambience stimframes into
stimbuffs for the LivoxGen1 lidar devices.

docs/design/intrin-thresholds.md

@@ -18,8 +18,9 @@ negtrin is free.
 Intrinsic threshold params (and the deprecated `from-stimbuff` marker)
 must not appear on the qualeIfaceApi params themselves — policy
 validation rejects them there. The nontrin qualeIfaceApi
-(e.g. `pcloudAmbience`) still owns its own sensory params (such as
-passband comparators); only the threshold classifications (`interest-*`,
+(e.g. `pcloudLightAmbience` / `pcloudDarkAmbience`) still owns its own
+sensory params (such as passband comparators); only the threshold
+classifications (`interest-*`,
 `distraction-*`, `stupefaction-*` / `stupefying-*`, `intolerable-*`) live
 in the postrin/negtrin segments.
 
@@ -35,7 +36,7 @@ Example (negtrin segment attached to ambience, with passband comparator
 on the nontrin qualeIfaceApi):
 
 ````
-+edev|avia0|negtrin(interest-pc=85)|pcloudAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
++edev|avia0|negtrin(interest-pc=85)|pcloudLightAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
 ````
 
 ## Unit Suffix Rules
@@ -83,7 +84,7 @@ with the "importance" argument set to "INTERESTING".
 
 **Example (negtrin segment attached to ambience):**
 ````
-+edev|avia0|negtrin(interest-pc=85)|pcloudAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
++edev|avia0|negtrin(interest-pc=85)|pcloudLightAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
 ````
 
 ## Distraction Threshold Parameters

docs/design/stencils.md

@@ -19,7 +19,8 @@ descriptors tell it exactly which body spots are raising it.
 This direct information also assists SMO in narrowing down the scope of its
 DB searches for methods to handle (increase or decrease) the stimval. For
 example, for a negtrin raised from a `negtrin(...)` segment attached to a
-nontrin DAP line (e.g. `pcloudAmbience`), we don't search DB by trying to
+nontrin DAP line (e.g. `pcloudLightAmbience` / `pcloudDarkAmbience`),
+we don't search DB by trying to
 match all possible body spots with their stimvals. Rather, we search for
 all the body spots that are described in the stencil. This optimizes DB
 searches and also makes negtrin relieving/postrin satisfying searches
@@ -90,15 +91,15 @@ raising new intrins.
 	|livoxProto1()|SERIAL
 ```
 
-The Livox Gen1 **`pcloudAmbience`** sensory line does **not** use
-`n-stencils`; ambience floats are delivered in the stimulus frame buffer.
-If Livox adds `n-stencils` for its intrinsic pipelines, it would appear
-inside the `postrin(...)` / `negtrin(...)` segments attached to
-`pcloudAmbience`, not on `pcloudAmbience` itself.
+The Livox Gen1 **`pcloudLightAmbience`** / **`pcloudDarkAmbience`** sensory
+lines do **not** use `n-stencils`; each emits one `uint32` passband count
+per stimframe. If Livox adds `n-stencils` for its intrinsic pipelines, it
+would appear inside the `postrin(...)` / `negtrin(...)` segments attached to
+the ambience line, not on the ambience qualeIfaceApi itself.
 
 **Invalid (sensory qualeIfaceApi must not carry intrin-oriented params):**
 ```
-+idev|my-device|pcloudAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
++idev|my-device|pcloudLightAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
 ```
 
 ## Notes

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

@@ -31,24 +31,44 @@ Each stim-buff-api is designed to work with specific stim-iface libraries that u
 **Stim-Buff-API**: `livoxGen1-pcloudIntensity`
 **Quale-Iface-API**: `pcloudIntensity` - Processes intensity/reflectivity data from point clouds
 
-### 2. Point Cloud Ambience Data Device (Interoceptor)
+### 2. Point Cloud Ambience Data Devices (Interoceptors)
 
-**Purpose**: Provides ambience data from the LiDAR point cloud as a **vector of per-dagram average intensities** (one `float` per UDP datagram slot in the staging frame, length `n-dgrams-per-frame`). The OpenCL collate kernel writes these values directly into the acquired ambience `StimulusFrame` buffer.
+Ambience is split into two qualeIfaceApis, each producing a single `uint32`
+per stimframe — the count of per-frame slots whose average intensity passes
+the qualeIface's comparator. The OpenCL collate kernel stages per-slot
+averages into an internal buffer; each attached ambience stimbuff reads that
+buffer and applies its own comparator.
+
+#### 2a. `pcloudLightAmbience` (pairs with `negtrin`)
 
 **Syntax**:
 ```
-+idev | avia0 | pcloudAmbience | livoxGen1-pcloud() | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
++idev | avia0 | negtrin(...) | pcloudLightAmbience(passband-count-gt-val=120) | livoxGen1-pcloud() | livoxProto1(...) | 3JEDK380010Z39
 ```
 
-**Stim-Buff-API**: `livoxGen1-pcloud`
-**Quale-Iface-API**: `pcloudAmbience` - Delivers per-dagram average intensity floats (sensory stream only).
+**Quale-Iface-API**: `pcloudLightAmbience` — Requires exactly one
+`passband-count-gt-val` on its params. Rejects `passband-count-lt-val`. The
+stimframe stimspot is the count of per-frame slots whose average intensity
+exceeds `passband-count-gt-val`. Scene is "unbearably much, get away" — pairs
+with `negtrin(...)`; `postrin(...)` on this line is rejected.
 
-Passband comparators (`passband-count-lt-val`, `passband-count-gt-val`) belong on
-`pcloudAmbience(...)` itself, and both may appear together — `lt` drives the
-postrin path, `gt` drives the negtrin path. Intrinsic threshold params
-(`interest-*`, `distraction-*`, `stupefaction-*`/`stupefying-*`, `intolerable-*`)
-live inside `postrin(...)` / `negtrin(...)` segments attached to the same DAP
-line. See `docs/design/intrin-thresholds.md`.
+#### 2b. `pcloudDarkAmbience` (pairs with `postrin`)
+
+**Syntax**:
+```
++idev | avia0 | postrin(...) | pcloudDarkAmbience(passband-count-lt-val=8) | livoxGen1-pcloud() | livoxProto1(...) | 3JEDK380010Z39
+```
+
+**Quale-Iface-API**: `pcloudDarkAmbience` — Requires exactly one
+`passband-count-lt-val` on its params. Rejects `passband-count-gt-val`. The
+stimframe stimspot is the count of per-frame slots whose average intensity
+falls below `passband-count-lt-val`. Scene is "too good, stay here" — pairs
+with `postrin(...)`; `negtrin(...)` on this line is rejected.
+
+Intrinsic threshold params (`interest-*`, `distraction-*`,
+`stupefaction-*`/`stupefying-*`, `intolerable-*`) live inside `postrin(...)` /
+`negtrin(...)` segments on the same DAP line. See
+`docs/design/intrin-thresholds.md`.
 
 ### 3. Point Cloud Coordinate Data Device (Extrospector)
 
@@ -158,7 +178,8 @@ The `livoxProto1` provider accepts the following parameters:
 | Stim Feature | Stim-Buff-API | Quale-Iface-API | Description |
 |--------------|---------------|----------------|-------------|
 | Point Cloud Intensity | `livoxGen1-pcloudIntensity` | `pcloudIntensity` | Light intensity/reflectivity data |
-| Point Cloud Ambience | `livoxGen1-pcloud` | `pcloudAmbience` | Per-dagram average intensity vector (`float` × `n-dgrams-per-frame`). Accepts `postrin(...)` / `negtrin(...)` segments on the same DAP line for intrin thresholds; see `docs/design/intrin-thresholds.md`. |
+| Point Cloud Light Ambience | `livoxGen1-pcloud` | `pcloudLightAmbience` | One `uint32` per stimframe: count of slots whose average intensity exceeds `passband-count-gt-val`. Pairs with `negtrin(...)`; rejects `postrin(...)` and `passband-count-lt-val`. |
+| Point Cloud Dark Ambience | `livoxGen1-pcloud` | `pcloudDarkAmbience` | One `uint32` per stimframe: count of slots whose average intensity falls below `passband-count-lt-val`. Pairs with `postrin(...)`; rejects `negtrin(...)` and `passband-count-gt-val`. |
 | Point Cloud Coordinates | `livoxGen1-pcloud` | `pcloud` | Spatial coordinate data |
 | Gyroscope | `livoxGen1-gyro` | `gyro` | Angular velocity measurements |
 | Accelerometer | `livoxGen1-accel` | `accel` | Linear acceleration measurements |