# 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. 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.

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 pcloudIntensity negtrin, 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 QualeIfaceApi Parameter

A new qualeIfaceApi parameter called `n-stencils` tells the stimbuff how
many stencils it can allocate and deliver to SMO simultaneously. 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 as part of the `quale-iface-api-params` in the
  DAP specification
- The value is an integer representing the maximum number of stencils that
  can be allocated simultaneously
- This parameter controls rate limiting for intrin events
- Stimbuffs must respect this limit and wait for stencil returns before
  allocating new ones

**Example:**
```
+idev|my-device|pcloudAmbience(n-stencils=4)|livoxGen1-pcloud()|livoxProto1()|3JEDK380010Z39
```

This example allows the stimbuff to allocate up to 4 stencils
simultaneously.

## Notes

The stencil registration mechanism discussed above is not currently
implemented. The current design relies on the cooperative relationship
between SMO and stimbuff libraries, where stimbuffs are expected to respect
the n-stencils limit without requiring explicit registration or validation
by SMO.
