Docs: Add stencil notes

docs/design/stencils.md

@@ -0,0 +1,94 @@
+# 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.