salmanoff/docs/design/stencils.md

# Stencils

## Overview

Stencils are an intrin info event data type used by SMO to efficiently
identify and process intrinsic stimuli (postrins and negtrins). Each stim
feature may have a stencil type if it's expected that devices exporting
stimbuffs for that feature can raise intrins (and even if not, because stencils
are used for projection). Stencils are derived classes
that provide sparse lists of body spots whose stim feature values have
passed the importance threshold for a particular intrin.

## Purpose

Stencils enable SMO's mind layer to quickly "just know" where an intrin is
occurring on the body. When an intrin is raised, SMO doesn't have to first
scan its percepts to figure out where the intrin is. The stencil
descriptors tell it exactly which body spots are raising it, because the sense
organ itself conveyed that information via the stencil.

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. `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
more explicit and obviously scoped items of knowledge. The eventual
solution is automatically classified as being a method to relieve/satisfy
intrins at this point on the body and not just hazily generally for "all
over the body". We get to make the new item of knowledge more specific.

## Format and Allocation Model

Stencils' formats are specified and standardized by SMO, as well as the
number of stencils that a stimbuff may deliver at once. But the size of the
stencil allocated by a stimbuff cannot be known by the SMO layer. Only the
stimbuff itself knows how much memory is required to hold a stencil for
describing intrin events that it raises.

For example, only the livoxGen1 stimbuff knows the upper bound on how many
sparse descriptors are needed to describe an ambience event, for its current
configuration. Because for example, the stencil memory size is determined
by its nDgramsPerFrame parameter.

So SMO must specify the format and number of stencils (for rate limiting)
per stimbuff. But the stimbuff library will determine internally the memory
size required for each stencil. This means that SMO can't pre-allocate and
loan stencils to the stimbuffs. That would be ideal because it would give
total control to SMO over intrin events -- because SMO could reject any
intrin event whose stencil's internal memory doesn't match one that it
previously loaned out.

We could probably still enforce this by making the stimbuffs "register"
their stencils with SMO before raising intrins. This would have the effect
of ensuring that SMO can verify that only its permitted number of stencils
have been allocated. Moreover, we also regain the ability to reject stencils
whose internal memory doesn't match the memory of a registered stencil.

But it's fine because we don't expect the relationship between SMO and
stimbuff libraries to be inimical enough for security measures like that to
be non-negotiable.

## n-stencils Intrin-Segment Parameter

Where a stim buff supports it, a parameter called `n-stencils` tells the
stimbuff how many stencils it can allocate and deliver to SMO
simultaneously for **intrinsic** delivery. `n-stencils` belongs on the
`postrin(...)` / `negtrin(...)` segment it rate-limits — **not** on the
nontrin qualeIfaceApi params. Postrin and negtrin get independent
budgets.

The stimbuff must wait until SMO returns stencils to it via postrinEventRdy or
negtrinEventRdy before delivering new intrin events. Stimbuffs can deliver
as many intrin events as they have stencils for. When all of their stencils
have been given to SMO, they must wait until SMO returns a stencil before
raising new intrins.

**Specification:**
- The parameter is specified inside a `postrin(...)` or `negtrin(...)`
  segment on a DAP line
- The value is an integer representing the maximum number of stencils
  that can be allocated simultaneously for that segment's intrin path
- This parameter controls rate limiting for intrin events
- Stimbuffs must respect this limit and wait for stencil returns before
  allocating new ones

**Example (generic shape — names depend on device):**
```
+idev|my-device
	|negtrin(interest-pc=85|n-stencils=4)|someSensoryQuale()|someStimBuffApi()
	|livoxProto1()|SERIAL
```

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|pcloudLightAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
```