From 5f9231359625ea2eb9c2edd94e274bbc9bcebdcd Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:28:49 -0500
Subject: [PATCH 01/76] The lifecycle matrix on single audiodsp nodes

---
 tests/support/lifecycle.py   |   6 +
 tests/support/node_matrix.py | 374 +++++++++++++++++++++++++++++++++++
 tests/test_node_matrix.py    | 141 +++++++++++++
 3 files changed, 521 insertions(+)
 create mode 100644 tests/support/node_matrix.py
 create mode 100644 tests/test_node_matrix.py

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index c527a93..047a230 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -1327,6 +1327,12 @@ def _cli(argv):
     for name in names:
         if name in PLANTS:
             cls = PLANTS[name]
+        elif name.startswith("Node"):
+            import node_matrix
+            cls = node_matrix.NODES.get(name)
+            if cls is None:
+                print("MISSING|%s" % name)
+                continue
         else:
             from audioeffects import rebuilt
             cls = rebuilt.module_class(name)
diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
new file mode 100644
index 0000000..879b0b4
--- /dev/null
+++ b/tests/support/node_matrix.py
@@ -0,0 +1,374 @@
+"""The lifecycle matrix on audiodsp nodes, before any class is built on them.
+
+`lifecycle.py` judges effect classes. This module wraps each node a phase
+stands on in the thinnest class that can carry the matrix: the node alone,
+its own controls as the macros, its own `mix` (or the control that is a wire
+at one end) as Mix, and two or three settings as patches. Nothing is routed
+around and nothing is composed, so a red cell is the node's.
+
+    python tests/support/lifecycle.py NodePitchShift [--quick]
+    LIFECYCLE_CLASSES=NodePitchShift python -m unittest tests.test_node_matrix
+
+`clear()` is what `reset()` calls where the node has one (E1), and the
+host's `audiocore.reset_buffer` is E2, so the two are both exercised.
+
+Which nodes, and why: Phase 6's classes (PitchShifter, Harmonizer, Octaver,
+StereoWidener, Rack, ShimmerHall, AirSpace) and their seed dossiers. The
+racks' children are the Phase 2 to 5 classes, so `audioverb.Tank`,
+`audioconvolve.Convolver` and `audioecho.FeedbackDelay`'s delay modes are
+qualified by `tests/test_lifecycle_matrix.py` running those classes at the
+same pin; the routing every class uses (`audioroute.Port`) is under every
+class's output already.
+"""
+
+import audiodelays
+import audiomixer
+
+try:
+    import audiobiquad
+    import audioecho
+    import audiomath
+    import audioroute
+except ImportError:                                   # pragma: no cover
+    audiobiquad = audioecho = audiomath = audioroute = None
+
+from audioeffects import _component
+
+#: `_component` reads VENDOR off the module a class is defined in.
+VENDOR = "PyDevices"
+
+BLOCK = 256
+
+
+def _seconds(e, seconds):
+    return int(seconds * e._sample_rate)
+
+
+class _Node(_component.Component):
+    """One node, its controls as macros. A subclass sets `_node_cls`,
+    `_make(options)` and `_set(name, value)`."""
+
+    TIER = _component.AUDIODSP
+    MACRO_MODES = {}
+    #: Seconds; the tail at the running rate is this times the rate.
+    _TAIL_S = 0.0
+    LATENCY_SAMPLES = 0
+
+    @property
+    def tail_samples(self):
+        self._check_live()
+        return _seconds(self, self._TAIL_S)
+
+    def _values(self):
+        return [_component.macro_value(span, self._macros[i])
+                for i, span in enumerate(type(self)._MACRO_RANGES)]
+
+    def _register(self, node):
+        clear = getattr(node, "clear", None)
+        return self._own(node, reset=clear if clear is not None else True)
+
+
+# -- pitch ----------------------------------------------------------------
+
+
+class NodePitchShift(_Node):
+    """`audiodelays.PitchShift`: the H910's splice shifter (PitchShifter,
+    Harmonizer, ShimmerHall's octave)."""
+    NAME = "NodePitchShift"
+    TIER = _component.STOCK
+    REQUIRES = ()
+    MACRO_LABELS = ("Mix", "Semitones", "Freeze")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "BIPOLAR", 2: "TOGGLE"}
+    _MACRO_RANGES = ((0.0, 1.0), (-12.0, 12.0), (0.0, 1.0))
+    PATCHES = {0: ("Octave up", (127, 127, 0)),
+               1: ("Octave down", (127, 0, 0)),
+               2: ("Fifth, half", (64, 96, 0))}
+    #: The window plus the overlap, twice, at the node's defaults.
+    _TAIL_S = 2 * (1024 + 128) / 22050.0
+
+    def _build(self, mix=1.0, semitones=12.0, freeze=0.0, patch=None):
+        self._node = self._register(audiodelays.PitchShift(
+            semitones=semitones, mix=mix, window=1024, overlap=128,
+            **self._pcm(512)))
+        self._node.play(self._source, loop=True)
+        self._output = self._node
+        self._init_macros((mix, semitones, freeze), patch)
+
+    def _apply_macro(self, index, position):
+        mix, semitones, freeze = self._values()
+        if index == 0:
+            self._node.mix = mix
+        elif index == 1:
+            self._node.semitones = semitones
+        else:
+            self._node.freeze = freeze >= 0.5
+
+
+class NodeGranularPitchShift(_Node):
+    """`audiodelays.GranularPitchShift`: the alternative shifter a
+    PitchShifter card may choose."""
+    NAME = "NodeGranularPitchShift"
+    TIER = _component.STOCK
+    REQUIRES = ()
+    MACRO_LABELS = ("Mix", "Semitones", "Spread")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "BIPOLAR", 2: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (-12.0, 12.0), (0.0, 1.0))
+    PATCHES = {0: ("Octave up", (127, 127, 0)),
+               1: ("Octave down, spread", (127, 0, 96)),
+               2: ("Fifth, half", (64, 96, 0))}
+    _TAIL_S = 4 * 1024 / 22050.0
+
+    def _build(self, mix=1.0, semitones=12.0, spread=0.0, patch=None):
+        self._node = self._register(audiodelays.GranularPitchShift(
+            semitones=semitones, mix=mix, grain_size=1024, density=2,
+            spread=spread, **self._pcm(512)))
+        self._node.play(self._source, loop=True)
+        self._output = self._node
+        self._init_macros((mix, semitones, spread), patch)
+
+    def _apply_macro(self, index, position):
+        mix, semitones, spread = self._values()
+        if index == 0:
+            self._node.mix = mix
+        elif index == 1:
+            self._node.semitones = semitones
+        else:
+            self._node.spread = spread
+
+
+class NodeShimmerLoop(_Node):
+    """`audioecho.FeedbackDelay` with a pitch shift in its loop
+    (`loop_semitones`, ShimmerHall's Rise). Mix runs to 2.0, wet alone."""
+    NAME = "NodeShimmerLoop"
+    REQUIRES = ("audioecho",)
+    MACRO_LABELS = ("Mix", "Feedback", "Semitones", "Time")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "BIPOLAR",
+                   3: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 2.0), (0.0, 0.7), (-12.0, 12.0),
+                     (10.0, 100.0))
+    PATCHES = {0: ("Rise", (64, 64, 127, 64)),
+               1: ("Fall, wet", (127, 96, 0, 32)),
+               2: ("Fifth", (64, 32, 96, 127))}
+    #: 0.7 ** n * 32768 < 1 at n = 30 repeats of the longest time, plus
+    #: the loop shifter's window.
+    _TAIL_S = 30 * 0.1 + 0.1
+
+    def _build(self, mix=1.0, feedback=0.35, semitones=12.0, time_ms=55.0,
+               patch=None):
+        self._node = self._register(audioecho.FeedbackDelay(
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count, max_delay_ms=120.0,
+            delay_ms=time_ms, feedback=feedback, mix=mix,
+            loop_semitones=semitones))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, feedback, semitones, time_ms), patch)
+
+    def _apply_macro(self, index, position):
+        mix, feedback, semitones, time_ms = self._values()
+        name = ("mix", "feedback", "loop_semitones", "delay_ms")[index]
+        self._node.set(**{name: (mix, feedback, semitones, time_ms)[index]})
+
+
+class NodeSubOctave(_Node):
+    """`audiomath.SubOctave`: the OC-2's flip-flop divider (Octaver)."""
+    NAME = "NodeSubOctave"
+    REQUIRES = ("audiomath",)
+    MACRO_LABELS = ("Mix", "Order", "Threshold")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "TOGGLE", 2: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (1.0, 2.0), (0.001, 0.1, "log"))
+    PATCHES = {0: ("One octave", (127, 0, 64)),
+               1: ("Two octaves", (127, 127, 64)),
+               2: ("Half, high threshold", (64, 0, 120))}
+    _TAIL_S = 0.05
+
+    def _build(self, mix=1.0, order=1.0, threshold=0.01, patch=None):
+        self._node = self._register(audiomath.SubOctave(
+            order=int(order), mix=mix, threshold=threshold,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, order, threshold), patch)
+
+    def _apply_macro(self, index, position):
+        mix, order, threshold = self._values()
+        if index == 0:
+            self._node.set(mix=mix)
+        elif index == 1:
+            self._node.set(order=2 if order >= 1.5 else 1)
+        else:
+            self._node.set(threshold=threshold)
+
+
+class NodeSquare(_Node):
+    """`audiomath.Multiply` fed two taps of one `audioroute.Splitter`: the
+    frequency doubler the Octaver dossier names, and the Splitter under it.
+    Mix is the Multiply's own."""
+    NAME = "NodeSquare"
+    REQUIRES = ("audiomath", "audioroute")
+    MACRO_LABELS = ("Mix",)
+    MACRO_MODES = {0: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0),)
+    PATCHES = {0: ("Square", (127,)), 1: ("Half", (64,))}
+    _TAIL_S = 0.0
+
+    def _build(self, mix=1.0, patch=None):
+        split = audioroute.Splitter(self._source, taps=2)
+        self._split = self._own(split, reset=False)
+        self._node = self._register(audiomath.Multiply(
+            split.tap(0), split.tap(1), mix=mix,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._output = self._node
+        self._init_macros((mix,), patch)
+
+    def _apply_macro(self, index, position):
+        self._node.set(mix=self._values()[0])
+
+
+# -- stereo and routing ---------------------------------------------------
+
+
+class NodeMidSide(_Node):
+    """`audioroute.MidSide`: StereoWidener's matrix. Width 1 is a wire, so
+    Mix carries the width from 1 (Mix 0) to the Target macro (Mix 1)."""
+    NAME = "NodeMidSide"
+    REQUIRES = ("audioroute",)
+    MACRO_LABELS = ("Mix", "Target")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (0.0, 2.0))
+    PATCHES = {0: ("Wide", (127, 127)), 1: ("Mono", (127, 0)),
+               2: ("Narrow, half", (64, 32))}
+    _TAIL_S = 0.0
+
+    def _build(self, mix=1.0, target=2.0, patch=None):
+        self._node = self._register(audioroute.MidSide(
+            width=1.0, sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, target), patch)
+
+    def _apply_macro(self, index, position):
+        mix, target = self._values()
+        self._node.set(width=1.0 + mix * (target - 1.0))
+
+
+class NodeSplitMix(_Node):
+    """`audioroute.Splitter` into `audiomixer.Mixer`, the house fan-out
+    (every parallel class, Harmonizer's stack, the racks' dry). Mix moves
+    the second tap's voice up and the first's down; at Mix 0 the first tap
+    plays at unity, which the Rack dossier found byte-identical (A6.3)."""
+    NAME = "NodeSplitMix"
+    REQUIRES = ("audioroute",)
+    MACRO_LABELS = ("Mix", "Level")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (0.0, 1.0))
+    PATCHES = {0: ("Even", (64, 127)), 1: ("Second only", (127, 127)),
+               2: ("Quiet", (127, 32))}
+    _TAIL_S = 0.0
+
+    def _build(self, mix=0.5, level=1.0, patch=None):
+        split = audioroute.Splitter(self._source, taps=2)
+        self._split = self._own(split, reset=False)
+        self._mixer = self._register(audiomixer.Mixer(
+            voice_count=2, **self._pcm(BLOCK * self._channel_count * 2)))
+        self._mixer.voice[0].play(split.tap(0), loop=True)
+        self._mixer.voice[1].play(split.tap(1), loop=True)
+        self._output = self._mixer
+        self._init_macros((mix, level), patch)
+
+    def _apply_macro(self, index, position):
+        mix, level = self._values()
+        self._mixer.voice[0].level = 1.0 - mix
+        self._mixer.voice[1].level = mix * level
+
+
+class NodeBiquad(_Node):
+    """`audiobiquad.Biquad`, low-pass: the Octaver's tracking and tone
+    filters, AirSpace's top cut."""
+    NAME = "NodeBiquad"
+    REQUIRES = ("audiobiquad",)
+    MACRO_LABELS = ("Mix", "Frequency", "Q")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (60.0, 8000.0, "log"), (0.5, 4.0))
+    PATCHES = {0: ("Dark", (127, 32, 10)), 1: ("Resonant", (127, 64, 127)),
+               2: ("Half, bright", (64, 120, 10))}
+    _TAIL_S = 0.5
+
+    def _build(self, mix=1.0, frequency=500.0, Q=0.7071, patch=None):
+        self._node = self._register(audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=frequency, Q=Q, mix=mix,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, frequency, Q), patch)
+
+    def _apply_macro(self, index, position):
+        mix, frequency, q = self._values()
+        if index == 0:
+            self._node.mix = mix
+        elif index == 1:
+            self._node.frequency = self._hz(frequency)
+        else:
+            self._node.Q = q
+
+
+class NodeEcho(_Node):
+    """`audiodelays.Echo`: Reverb's predelay and the Haas line a
+    StereoWidener card may choose."""
+    NAME = "NodeEcho"
+    TIER = _component.STOCK
+    REQUIRES = ()
+    MACRO_LABELS = ("Mix", "Time", "Decay")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (5.0, 100.0), (0.0, 0.5))
+    PATCHES = {0: ("Haas", (127, 5, 0)), 1: ("Slap", (64, 127, 64)),
+               2: ("Short repeats", (96, 40, 127))}
+    #: 0.5 ** n * 32768 < 1 at n = 16 repeats of the longest time.
+    _TAIL_S = 16 * 0.1 + 0.1
+
+    def _build(self, mix=1.0, time_ms=10.0, decay=0.0, patch=None):
+        self._node = self._register(audiodelays.Echo(
+            max_delay_ms=120, delay_ms=time_ms, decay=decay, mix=mix,
+            freq_shift=False, **self._pcm(512)))
+        self._node.play(self._source, loop=True)
+        self._output = self._node
+        self._init_macros((mix, time_ms, decay), patch)
+
+    def _apply_macro(self, index, position):
+        mix, time_ms, decay = self._values()
+        if index == 0:
+            self._node.mix = mix
+        elif index == 1:
+            self._node.delay_ms = time_ms
+        else:
+            self._node.decay = decay
+
+
+NODES = {}
+for _cls in (NodePitchShift, NodeGranularPitchShift, NodeShimmerLoop,
+             NodeSubOctave, NodeSquare, NodeMidSide, NodeSplitMix,
+             NodeBiquad, NodeEcho):
+    NODES[_cls.NAME] = _cls
+
+
+#: Red cells a node has by design, one row per (adapter NAME, event name
+#: prefix, property): reason. Merged into lifecycle.DECLARED on import.
+DECLARED = {
+    ("NodeSubOctave", "E1-", "P4"):
+        "a reset restarts the divider at the pass-through polarity; a node"
+        " that counted an odd number of edges plays the same octave inverted",
+    ("NodeSubOctave", "E2-", "P4"):
+        "as E1: the host reset restarts the divider's count",
+    ("NodeBiquad", "E2-", "P4"):
+        "a float32 recursion on looping input can settle one ulp off a"
+        " never-reset one and flip one LSB now and then for good",
+    ("NodeBiquad", "E6-", "P4"):
+        "as E2: one ulp of filter state after a move and back",
+}
+
+import lifecycle  # noqa: E402
+lifecycle.DECLARED.update(DECLARED)
diff --git a/tests/test_node_matrix.py b/tests/test_node_matrix.py
new file mode 100644
index 0000000..3e8e75d
--- /dev/null
+++ b/tests/test_node_matrix.py
@@ -0,0 +1,141 @@
+"""The lifecycle matrix on the audiodsp nodes the effects stand on
+(`tests/support/node_matrix.py`), on CPython and on the two native
+interpreters.
+
+The same rules as `tests/test_lifecycle_matrix.py`: a red cell is either a
+row of KNOWN_RED below (a finding, with its reason) or a declared exception
+in `node_matrix.DECLARED` (a behaviour the node has by design); the file goes
+red when a cell changes either way, and the three interpreters must print
+the same line for every cell.
+
+    OMP_NUM_THREADS=1 python -m unittest tests.test_node_matrix
+    LIFECYCLE_CLASSES=NodePitchShift python -m unittest tests.test_node_matrix
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(ROOT, "lib"))
+sys.path.insert(0, os.path.join(ROOT, "tests", "support"))
+
+import lifecycle                                          # noqa: E402
+import node_matrix                                        # noqa: E402
+from tests.test_lifecycle_matrix import (FULL, check_known, digest,  # noqa: E402
+                                   native_binaries, parse, red_cells)
+
+VENDOR = "PyDevices"
+
+#: What is red today, in the same shape as test_lifecycle_matrix.KNOWN_RED.
+KNOWN_RED = {}
+
+
+def names():
+    wanted = os.environ.get("LIFECYCLE_CLASSES")
+    picked = wanted.split(",") if wanted else sorted(node_matrix.NODES)
+    return [n for n in picked if n in node_matrix.NODES]
+
+
+def start_native(binary, picked, scratch):
+    env = dict(os.environ, MICROPYPATH="lib:tests/support",
+               GCOV_PREFIX=scratch, PYTHONDONTWRITEBYTECODE="1")
+    return subprocess.Popen(
+        [binary, "-X", "heapsize=256M", "tests/support/lifecycle.py"]
+        + list(picked) + ([] if FULL else ["--quick"]),
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+        cwd=ROOT, env=env)
+
+
+class TestNodeMatrix(unittest.TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        cls.names = names()
+        cls.natives = native_binaries()
+        cls.scratch = tempfile.TemporaryDirectory()
+        cls.procs = {}
+        for family, binary in cls.natives.items():
+            if binary is not None and cls.names:
+                cls.procs[family] = start_native(binary, cls.names,
+                                                 cls.scratch.name)
+        cls.cpython = {}
+        for name in cls.names:
+            lines = []
+            lifecycle.run_class(node_matrix.NODES[name], emit=lines.append,
+                                quick=not FULL)
+            cls.cpython[name] = lines
+        cls.native_lines = {}
+        for family, proc in cls.procs.items():
+            out, err = proc.communicate()
+            lines = out.splitlines()
+            if proc.returncode != 0 or not lines or lines[-1] != "DONE":
+                cls.native_lines[family] = AssertionError(
+                    "%s: %s%s" % (family, out[-1500:], err[-1500:]))
+            else:
+                cls.native_lines[family] = lines
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.scratch.cleanup()
+
+    def test_known_red_on_cpython(self):
+        problems = []
+        for name in self.names:
+            problems += check_known(name, red_cells(parse(self.cpython[name])),
+                                    KNOWN_RED)
+        self.assertEqual(problems, [], "\n".join(problems[:60]))
+
+    def _p6(self, family):
+        if self.natives.get(family) is None:
+            self.skipTest("no %s binary" % family)
+        got = self.native_lines[family]
+        if isinstance(got, Exception):
+            raise got
+        problems = []
+        for name in self.names:
+            ours = parse(self.cpython[name])
+            theirs = parse([l for l in got if l.startswith(name + "|")])
+            for key in sorted(set(ours) | set(theirs)):
+                if ours.get(key) != theirs.get(key):
+                    problems.append("%s: %s cpython %s, %s %s" % (
+                        family, "|".join(map(str, key)), ours.get(key),
+                        family, theirs.get(key)))
+        self.assertEqual(problems, [], "\n".join(problems[:60]))
+
+    def test_p6_micropython(self):
+        self._p6("micropython")
+
+    def test_p6_circuitpython(self):
+        self._p6("circuitpython")
+
+
+class TestAdapters(unittest.TestCase):
+    """An adapter can show a reset defect: one whose reset leaves the node
+    where it was instead of where a fresh one starts is red on P4 where the
+    clean adapter is green."""
+
+    def test_a_reset_that_keeps_state_is_red(self):
+        def cell(cls):
+            lines = []
+            lifecycle.run_class(cls, rates=(48000,), channels=(2,),
+                                patches=[None], only=["E1"],
+                                emit=lines.append)
+            return parse(lines)[(cls.NAME, "E1-reset@block", 48000, 2,
+                                 "d")]["P4"]
+
+        class KeepsState(node_matrix.NodeBiquad):
+            NAME = "NodeBiquadKeepsState"
+
+            def reset(self):
+                self._check_live()
+                self._clear_nodes()
+
+        self.assertEqual(cell(node_matrix.NodeBiquad), "ok")
+        self.assertTrue(cell(KeepsState).startswith("RED"))
+
+
+if __name__ == "__main__":
+    unittest.main()

From e793fada4fddce0db27b5a62b68557f4dfd288e7 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:29:01 -0500
Subject: [PATCH 02/76] test_node_matrix: drop an unused import

---
 tests/test_node_matrix.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_node_matrix.py b/tests/test_node_matrix.py
index 3e8e75d..2c7165b 100644
--- a/tests/test_node_matrix.py
+++ b/tests/test_node_matrix.py
@@ -24,7 +24,7 @@
 
 import lifecycle                                          # noqa: E402
 import node_matrix                                        # noqa: E402
-from tests.test_lifecycle_matrix import (FULL, check_known, digest,  # noqa: E402
+from tests.test_lifecycle_matrix import (FULL, check_known,  # noqa: E402
                                    native_binaries, parse, red_cells)
 
 VENDOR = "PyDevices"

From 644b68af40748341df92766dfd10f2d6f676181b Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:44:34 -0500
Subject: [PATCH 03/76] The effects kit: tail, plant validity, claims, readback
 and arguments, input ceiling and paperwork checks

Six mechanical checks on one class, each printing one line per cell and a
SUMMARY per check. The four render checks are numpy-free and print the
same lines on CPython, MicroPython and CircuitPython; the claims and
paperwork checks read source and git, on CPython. kit_planted.py holds
the tiny planted components the checks are proven on.
---
 tests/support/kit.py           |  99 +++++++++
 tests/support/kit_args.py      | 368 +++++++++++++++++++++++++++++++++
 tests/support/kit_ceiling.py   | 183 ++++++++++++++++
 tests/support/kit_claims.py    | 238 +++++++++++++++++++++
 tests/support/kit_common.py    | 344 ++++++++++++++++++++++++++++++
 tests/support/kit_options.py   |  16 ++
 tests/support/kit_paperwork.py | 212 +++++++++++++++++++
 tests/support/kit_planted.py   | 314 ++++++++++++++++++++++++++++
 tests/support/kit_plants.py    | 167 +++++++++++++++
 tests/support/kit_tail.py      | 160 ++++++++++++++
 10 files changed, 2101 insertions(+)
 create mode 100644 tests/support/kit.py
 create mode 100644 tests/support/kit_args.py
 create mode 100644 tests/support/kit_ceiling.py
 create mode 100644 tests/support/kit_claims.py
 create mode 100644 tests/support/kit_common.py
 create mode 100644 tests/support/kit_options.py
 create mode 100644 tests/support/kit_paperwork.py
 create mode 100644 tests/support/kit_planted.py
 create mode 100644 tests/support/kit_plants.py
 create mode 100644 tests/support/kit_tail.py

diff --git a/tests/support/kit.py b/tests/support/kit.py
new file mode 100644
index 0000000..529308a
--- /dev/null
+++ b/tests/support/kit.py
@@ -0,0 +1,99 @@
+"""The effects kit: six mechanical checks on one class, no model in the loop.
+
+    python tests/support/kit.py DigitalDelay [--only tail,plants,...]
+        [--quick] [--plants-module NAME] [--claims-module NAME] [--no-run]
+
+Prints one line per cell, `name|check|key|V:verdict[|h:digest]`, a
+SUMMARY line per check, and DONE. On MicroPython and CircuitPython
+(`MICROPYPATH=lib:tests/support`) it runs the four render checks; the
+claims and paperwork checks read source and git, and run on CPython only.
+`KIT.md` beside this file says what each check measures and its bars.
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+    sys.path.insert(0, "tests")
+
+import kit_common as kc
+
+CHECKS = ("paperwork", "claims", "args", "plants", "ceiling", "tail")
+STATIC = ("paperwork", "claims")
+
+
+def run_check(check, cls, emit=print, quick=False, plants_module=None,
+              claims_module=None, execute=True, name=None):
+    import kit_options
+    options = kit_options.options_for(cls.NAME)
+    if check == "tail":
+        import kit_tail
+        return kit_tail.run(cls, emit, quick=quick, name=name,
+                            options=options)
+    if check == "plants":
+        import kit_plants
+        return kit_plants.run(cls, emit, module=plants_module, name=name,
+                              options=options)
+    if check == "args":
+        import kit_args
+        return kit_args.run(cls, emit, quick=quick, name=name,
+                            options=options)
+    if check == "ceiling":
+        import kit_ceiling
+        return kit_ceiling.run(cls, emit, quick=quick, name=name,
+                               options=options)
+    if check == "claims":
+        import kit_claims
+        return kit_claims.run(cls, emit, module=claims_module,
+                              execute=execute, name=name)
+    if check == "paperwork":
+        import kit_paperwork
+        return kit_paperwork.run(cls, emit, name=name)
+    raise ValueError(check)
+
+
+def main(argv, only=None, emit=print):
+    names = []
+    quick = False
+    execute = True
+    plants_module = claims_module = None
+    joined = []
+    for arg in argv:
+        if joined and joined[-1] in ("--only", "--plants-module",
+                                     "--claims-module"):
+            joined[-1] += "=" + arg
+        else:
+            joined.append(arg)
+    for arg in joined:
+        if arg.startswith("--only="):
+            only = tuple(arg.split("=", 1)[1].split(","))
+        elif arg == "--quick":
+            quick = True
+        elif arg == "--no-run":
+            execute = False
+        elif arg.startswith("--plants-module="):
+            plants_module = arg.split("=", 1)[1]
+        elif arg.startswith("--claims-module="):
+            claims_module = arg.split("=", 1)[1]
+        else:
+            names.append(arg)
+    only = only or CHECKS
+    for name in names:
+        cls = kc.resolve(name)
+        if cls is None:
+            emit("MISSING|%s" % name)
+            continue
+        for check in CHECKS:
+            if check not in only:
+                continue
+            if check in STATIC and not kc.CPYTHON:
+                emit("SKIP|%s|%s|CPython only" % (name, check))
+                continue
+            run_check(check, cls, emit, quick, plants_module, claims_module,
+                      execute)
+    emit("DONE")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])
diff --git a/tests/support/kit_args.py b/tests/support/kit_args.py
new file mode 100644
index 0000000..41ae01e
--- /dev/null
+++ b/tests/support/kit_args.py
@@ -0,0 +1,368 @@
+"""Readback and arguments: what the control surface does with the values a
+host can hand it.
+
+Cells, all on an 8192-frame click and noise train then silence:
+
+- `rt-m<i>/<rate>/<patch>`: `set_macro(i, get_macro(i))` mid-stream
+  changes no byte of the render, at the defaults and at every patch.
+- `stops-m<i>`: 0, 64 and 127 are accepted and `get_macro` reads each
+  back within 1e-4.
+- `bad-m<i>`: NaN, +inf, -inf, -1 and 128. The contract does not say
+  whether an out-of-range macro value raises or clamps, so either passes:
+  a raise must be ValueError or TypeError and leave every macro where it
+  was (`r`); a clamp must read back a finite value in 0..127 (0 below the
+  range, 127 above it) and render exactly what `set_macro(i, readback)`
+  renders (`c`).
+- `patch-p<k>`: from a fresh instance, `program_change(k)` sets
+  `patch_index` and reads back the patch's values within 1e-4, and
+  `program_change(0)` reads back what the fresh instance read.
+- `ctor-<option>`: each numeric option of `_build` at 0 and at NaN. A
+  raise must be ValueError or TypeError (`r`). A build (`c`) must report
+  readable latency and tail, finite macros in 0..127, render without
+  raising and without sitting on a rail where the input did not (kit
+  RAIL_RUN); and a NaN build must render exactly what the defaults or the
+  option at 0 render.
+
+A render that is silent throughout cannot show a difference; such a cell
+prints `na(silent)`.
+
+    python tests/support/kit_args.py DigitalDelay
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+import lifecycle
+
+CHECK = "args"
+PROBE_FRAMES = 8192
+FRAMES = 16384
+K_MOVE = 8
+READBACK_TOL = 1e-4
+
+NAN = float("nan")
+INF = float("inf")
+BAD = (("nan", NAN), ("inf", INF), ("-inf", -INF), ("-1", -1), ("128", 128))
+REFUSALS = (ValueError, TypeError)
+
+_PROBE = {}
+
+
+def probe(channels):
+    if channels not in _PROBE:
+        _PROBE[channels] = lifecycle.click_noise(PROBE_FRAMES, channels)
+    return _PROBE[channels]
+
+
+#: The class's kit options (kit_options), under every build's own.
+_BASE = {}
+
+
+def fresh(cls, rate=48000, channels=2, patch=None, options=None):
+    feed = kc.feed(probe(channels), rate, channels)
+    merged = dict(_BASE)
+    merged.update(options or {})
+    return kc.build(cls, feed.port, rate, patch, merged)
+
+
+def gets(e):
+    return [e.get_macro(i) for i in range(len(type(e).MACRO_LABELS))]
+
+
+def _silent(data):
+    return lifecycle._is_zero(data)
+
+
+def _close(e):
+    try:
+        e.deinit()
+    except Exception:                                     # noqa: BLE001
+        pass
+
+
+# -- cells ---------------------------------------------------------------
+
+
+def roundtrip(cls, index, rate, patch):
+    a = fresh(cls, rate, 2, patch)
+    b = fresh(cls, rate, 2, patch)
+    try:
+        ra = kc.render(a, FRAMES)
+        rb = kc.render(b, FRAMES, {K_MOVE: lambda e: e.set_macro(
+            index, e.get_macro(index))})
+    finally:
+        _close(a)
+        _close(b)
+    if _silent(ra) and _silent(rb):
+        return "na(silent)", kc.crc(rb)
+    if ra != rb:
+        d = lifecycle._first_diff(ra, rb, 0, len(ra))
+        return "RED(differs from frame %d)" % (d // 4 - K_MOVE * kc.BLOCK), \
+            kc.crc(rb)
+    return "ok", kc.crc(rb)
+
+
+def stops_cell(cls, index):
+    e = fresh(cls)
+    try:
+        for v in (0, 64, 127):
+            try:
+                e.set_macro(index, v)
+            except Exception as exc:                      # noqa: BLE001
+                return "RED(%d raised %s)" % (v, type(exc).__name__)
+            r = e.get_macro(index)
+            if not kc.finite(r) or abs(r - v) > READBACK_TOL:
+                return "RED(%d reads back %s)" % (v, kc.num(r))
+    finally:
+        _close(e)
+    return "ok"
+
+
+def bad_cell(cls, index):
+    codes = []
+    for label, v in BAD:
+        a = fresh(cls)
+        b = None
+        try:
+            before = gets(a)
+            try:
+                a.set_macro(index, v)
+            except REFUSALS:
+                if gets(a) != before:
+                    return "RED(%s raised and moved the macros)" % label
+                codes.append("%s:r" % label)
+                continue
+            except Exception as exc:                      # noqa: BLE001
+                return "RED(%s raised %s)" % (label, type(exc).__name__)
+            r = a.get_macro(index)
+            if not kc.finite(r) or r < 0 or r > 127:
+                return "RED(%s reads back %s)" % (label, kc.num(r))
+            want = 0 if v < 0 else (127 if v > 127 else None)
+            if want is not None and abs(r - want) > READBACK_TOL:
+                return "RED(%s reads back %s, not %d)" % (label, kc.num(r),
+                                                          want)
+            b = fresh(cls)
+            b.set_macro(index, r)
+            ra = kc.render(a, FRAMES)
+            rb = kc.render(b, FRAMES)
+            if ra != rb:
+                return "RED(%s renders other than set_macro(%d, %s))" % (
+                    label, index, kc.num(r))
+            codes.append("%s:%s" % (label, "n" if _silent(ra) else "c"))
+        finally:
+            _close(a)
+            if b is not None:
+                _close(b)
+    return "ok(%s)" % " ".join(codes)
+
+
+def patch_cell(cls, patch):
+    e = fresh(cls)
+    try:
+        start = gets(e)
+        e.program_change(patch)
+        if e.patch_index != patch:
+            return "RED(patch_index reads %r)" % (e.patch_index,)
+        got = gets(e)
+        want = cls.PATCHES[patch][1]
+        for i in range(len(want)):
+            if abs(got[i] - want[i]) > READBACK_TOL:
+                return "RED(m%d reads %s, the patch says %d)" % (
+                    i, kc.num(got[i]), want[i])
+        e.program_change(0)
+        back = gets(e)
+        for i in range(len(start)):
+            if abs(back[i] - start[i]) > READBACK_TOL:
+                return "RED(back at patch 0, m%d reads %s, fresh read %s)" \
+                    % (i, kc.num(back[i]), kc.num(start[i]))
+    finally:
+        _close(e)
+    return "ok"
+
+
+# -- constructor options ---------------------------------------------------
+
+
+def _defining(cls, attr):
+    todo = [cls]
+    while todo:
+        c = todo.pop(0)
+        if attr in c.__dict__:
+            return c
+        todo.extend(c.__bases__)
+    return None
+
+
+def _split_params(text):
+    out = []
+    depth = 0
+    cur = ""
+    for ch in text:
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            out.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    out.append(cur)
+    return [p.strip() for p in out if p.strip()]
+
+
+def _number(text, module):
+    if text in ("True", "False", "None") or text[:1] in ("'", '"'):
+        return None
+    try:
+        return int(text)
+    except ValueError:
+        pass
+    try:
+        return float(text)
+    except ValueError:
+        pass
+    value = getattr(module, text, None)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return value
+
+
+def options_of(cls):
+    """[(name, default)] for each numeric keyword of the class's `_build`,
+    read from its source so every interpreter reads the same list."""
+    owner = _defining(cls, "_build")
+    if owner is None:
+        return []
+    module = sys.modules[owner.__module__]
+    with open(module.__file__) as f:
+        text = f.read()
+    at = text.find("class %s(" % owner.__name__)
+    at = text.find("def _build(", at if at >= 0 else 0)
+    if at < 0:
+        return []
+    at += len("def _build(")
+    depth = 1
+    end = at
+    while depth and end < len(text):
+        if text[end] == "(":
+            depth += 1
+        elif text[end] == ")":
+            depth -= 1
+        end += 1
+    out = []
+    for param in _split_params(text[at:end - 1]):
+        name, _sep, default = param.partition("=")
+        name = name.strip()
+        if name in ("self", "patch") or name.startswith("*") or not _sep:
+            continue
+        value = _number(default.strip(), module)
+        if value is not None:
+            out.append((name, value))
+    return out
+
+
+def _built(cls, options):
+    """(instance or None, code, red or None)."""
+    try:
+        e = fresh(cls, options=options)
+    except REFUSALS:
+        return None, "r", None
+    except Exception as exc:                              # noqa: BLE001
+        return None, None, "raised %s" % type(exc).__name__
+    try:
+        e.tail_samples
+        e.latency_samples
+    except Exception as exc:                              # noqa: BLE001
+        _close(e)
+        return None, None, "tail or latency raised %s" % type(exc).__name__
+    for i, r in enumerate(gets(e)):
+        if not kc.finite(r) or r < 0 or r > 127:
+            _close(e)
+            return None, None, "m%d reads %s" % (i, kc.num(r))
+    return e, "c", None
+
+
+def _render_judged(e):
+    """(bytes or None, red or None)."""
+    try:
+        data = kc.render(e, FRAMES)
+    except Exception as exc:                              # noqa: BLE001
+        return None, "render raised %s" % type(exc).__name__
+    run, where = kc.rail_run(kc.samples(data), probe(2), 2,
+                             e.latency_samples)
+    if run > kc.RAIL_RUN:
+        return data, "%d frames on a rail from %d" % (run, where)
+    return data, None
+
+
+def ctor_cell(cls, option):
+    renders = {}
+    codes = []
+    for label, v in (("0", 0), ("nan", NAN)):
+        e, code, red = _built(cls, {option: v})
+        if red is not None:
+            return "RED(%s: %s)" % (label, red)
+        if e is not None:
+            try:
+                data, red = _render_judged(e)
+            finally:
+                _close(e)
+            if red is not None:
+                return "RED(%s: %s)" % (label, red)
+            renders[label] = data
+        codes.append("%s:%s" % (label, code))
+    if "nan" in renders:
+        d = fresh(cls)
+        try:
+            default = kc.render(d, FRAMES)
+        finally:
+            _close(d)
+        if renders["nan"] not in (default, renders.get("0")):
+            return "RED(nan renders neither the default nor 0)"
+    return "ok(%s)" % " ".join(codes)
+
+
+def run(cls, emit=print, quick=False, name=None, options=None):
+    """Every args cell for `cls`; returns the red count."""
+    global _BASE
+    _BASE = dict(options or {})
+    cells = kc.Cells(name or cls.NAME, CHECK, emit)
+    n = len(cls.MACRO_LABELS)
+    rates = (48000,) if quick else kc.RATES
+
+    def cell(key, fn, *args):
+        try:
+            got = fn(*args)
+        except Exception as exc:                          # noqa: BLE001
+            got = "RED(raised %s: %s)" % (type(exc).__name__, exc)
+        if isinstance(got, tuple):
+            cells.cell(key, got[0], got[1])
+        else:
+            cells.cell(key, got)
+
+    for i in range(n):
+        for rate in rates:
+            for patch in kc.patches(cls):
+                cell("rt-m%d/%d/%s" % (i, rate, kc.pname(patch)), roundtrip,
+                     cls, i, rate, patch)
+    for i in range(n):
+        cell("stops-m%d" % i, stops_cell, cls, i)
+    for i in range(n):
+        cell("bad-m%d" % i, bad_cell, cls, i)
+    for patch in sorted(cls.PATCHES):
+        cell("patch-p%d" % patch, patch_cell, cls, patch)
+    for option, _default in options_of(cls):
+        if option in _BASE:
+            continue
+        cell("ctor-%s" % option, ctor_cell, cls, option)
+    return cells.summary()
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_ceiling.py b/tests/support/kit_ceiling.py
new file mode 100644
index 0000000..1b2ccd2
--- /dev/null
+++ b/tests/support/kit_ceiling.py
@@ -0,0 +1,183 @@
+"""The input ceiling: rendered at the level the class says it is clean at,
+on the worst material, the output never wraps, never sits on a rail the
+input was not on, and never goes silent while the input plays.
+
+**The stated level.** A class states it as `INPUT_CEILING_DBFS`, a class
+attribute in dBFS (0 or below). A class that states none is held to 0 dBFS,
+full scale. The material's peak is round(32767 x 10^(dBFS/20)).
+
+**The material**, 2 s at the rate: a 100 Hz square, a 50 Hz sine, one
+-sample clicks of alternating sign every 97 frames, LCG noise, and a DC
+step (silence for the first eighth, then the peak held). Each at the
+defaults, at every patch, and with each macro alone at each stop (0 and
+127, and 64 for a bipolar macro); at 48 and 22.05 kHz, stereo and mono
+(`--quick`: 48 kHz stereo).
+
+**The bars**, each its own clause in a RED verdict:
+
+- `wrap`: two neighbouring samples of opposite sign more than 32768 apart,
+  with the signal running the same way on both sides of the jump (into it
+  before, out of it after), as an int16 sum that overflowed runs, and the
+  input, `latency_samples` earlier, made no such jump. A square's edge
+  is flat on both sides, so it is not one. Not judged on the noise, whose
+  jumps run every way.
+- `rail`: more than 8 frames in a row on a rail (|y| >= 32767) where the
+  input, `latency_samples` earlier, was not.
+- `silent`: the last second exactly zero while the input played through
+  it. Not judged on the DC step, which a high-pass rightly takes to zero.
+
+    python tests/support/kit_ceiling.py DigitalDelay [--quick]
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+import lifecycle
+
+CHECK = "ceiling"
+SECONDS = 2
+MATERIALS = ("square", "sine", "clicks", "noise", "dc")
+WRAP_JUMP = 32768
+
+_MAT = {}
+
+
+def peak(cls):
+    db = getattr(cls, "INPUT_CEILING_DBFS", 0)
+    if db >= 0:
+        return kc.RAIL
+    return int(32767 * 10.0 ** (db / 20.0) + 0.5)
+
+
+def material(which, rate, channels, amp):
+    key = (which, rate, channels, amp)
+    if key not in _MAT:
+        frames = SECONDS * rate
+        if which == "square":
+            values = kc.square(frames, channels, amp, rate // 100)
+        elif which == "sine":
+            values = kc.sine(frames, channels, amp, rate // 50)
+        elif which == "clicks":
+            values = kc.clicks(frames, channels, amp)
+        elif which == "noise":
+            values = kc.noise(frames, channels, amp)
+        elif which == "dc":
+            values = kc.dc(frames, channels, amp, start=frames // 8)
+        else:
+            raise ValueError(which)
+        _MAT.clear()
+        _MAT[key] = values
+    return _MAT[key]
+
+
+def wrap_at(out, values, channels, lat):
+    """(frame, channel) of the first wrap, or None."""
+    n = len(out) // channels
+    nin = len(values) // channels
+    for ch in range(channels):
+        for f in range(2, n - 1):
+            a = out[(f - 1) * channels + ch]
+            b = out[f * channels + ch]
+            if (a >= 0) == (b >= 0):
+                continue
+            jump = b - a
+            if jump < WRAP_JUMP and -jump < WRAP_JUMP:
+                continue
+            before = a - out[(f - 2) * channels + ch]
+            after = out[(f + 1) * channels + ch] - b
+            if jump < 0 and not (before > 0 and after > 0):
+                continue
+            if jump > 0 and not (before < 0 and after < 0):
+                continue
+            g = f - lat
+            if 1 <= g < nin:
+                x = values[g * channels + ch] - values[(g - 1) * channels + ch]
+                if x >= WRAP_JUMP or -x >= WRAP_JUMP:
+                    continue
+            return f, ch
+    return None
+
+
+def judge(data, values, channels, rate, lat, which):
+    out = kc.samples(data)
+    reds = []
+    if which != "noise":
+        hit = wrap_at(out, values, channels, lat)
+        if hit is not None:
+            reds.append("wrap at %d ch %d" % hit)
+    run, where = kc.rail_run(out, values, channels, lat)
+    if run > kc.RAIL_RUN:
+        reds.append("rail %d frames from %d" % (run, where))
+    if which != "dc":
+        lo = (SECONDS - 1) * rate * channels
+        if lifecycle._is_zero(data[2 * lo:]):
+            quiet = True
+            for i in range(lo, len(values)):
+                if values[i]:
+                    quiet = False
+                    break
+            if not quiet:
+                last = kc.last_nonzero_frame(out, channels)
+                reds.append("silent from %d" % last)
+    return reds
+
+
+def configs(cls):
+    """(key, patch, knob) for the defaults, every patch and every stop."""
+    out = [("d", None, None)]
+    for patch in sorted(cls.PATCHES):
+        out.append(("p%d" % patch, patch, None))
+    for knob in kc.knob_positions(cls):
+        out.append(("m%d=%d" % knob, None, knob))
+    return out
+
+
+def measure(cls, rate, channels, which, patch, knob, options=None):
+    amp = peak(cls)
+    values = material(which, rate, channels, amp)
+    feed = kc.feed(values, rate, channels)
+    e = kc.build(cls, feed.port, rate, patch, options)
+    try:
+        if knob is not None:
+            e.set_macro(knob[0], knob[1])
+        data = kc.render(e, SECONDS * rate)
+        reds = judge(data, values, channels, rate, e.latency_samples, which)
+    finally:
+        e.deinit()
+    verdict = "RED(%s)" % "; ".join(reds) if reds else "ok"
+    return verdict, kc.crc(data)
+
+
+def run(cls, emit=print, quick=False, rates=None, channels=None,
+        materials=MATERIALS, only=None, options=None, name=None):
+    """Every ceiling cell for `cls`; returns the red count. `only` limits
+    the configurations to keys in it ("d", "p0", "m1=127")."""
+    cells = kc.Cells(name or cls.NAME, CHECK, emit)
+    if rates is None:
+        rates = (48000,) if quick else kc.RATES
+    if channels is None:
+        channels = (2,) if quick else kc.CHANNELS
+    for rate in rates:
+        for ch in channels:
+            for which in materials:
+                for key, patch, knob in configs(cls):
+                    if only is not None and key not in only:
+                        continue
+                    ckey = "%s/%d/%d/%s" % (which, rate, ch, key)
+                    try:
+                        verdict, digest = measure(cls, rate, ch, which,
+                                                  patch, knob, options)
+                    except Exception as exc:              # noqa: BLE001
+                        verdict, digest = "RED(raised %s: %s)" % (
+                            type(exc).__name__, exc), None
+                    cells.cell(ckey, verdict, digest)
+    return cells.summary()
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_claims.py b/tests/support/kit_claims.py
new file mode 100644
index 0000000..4e37c23
--- /dev/null
+++ b/tests/support/kit_claims.py
@@ -0,0 +1,238 @@
+"""The claims check: every sentence in a class's docstring that makes a
+claim is tied to a test, and that test exists and passes.
+
+**The convention.** The class's test module (by default
+`tests/test_cpython_effects_<name>.py`) holds a module-level `CLAIMS`
+table. Each row is `(sentence, test)`: the docstring sentence word for
+word (whitespace aside), and the test that asserts it. `test` is a test
+method's name (`"test_x"`, any TestCase in the module that defines it), a
+`"Class.test_x"`, a tuple of those, or `"DECLARED:<NAME>,<event
+prefix>,<property>"`, naming a row of the lifecycle matrix's DECLARED
+table (a disclosure the matrix holds).
+
+**The text.** What a player reads: the class's module docstring, then the
+class docstring (a rebuilt module holds one class, and either may carry
+the player's text). Markdown bold headings (`**Controls.**`) are not
+sentences.
+
+**What counts as a claim.** Mechanically, a sentence is a claim if it holds
+a digit, a number word, or one of the bound and absolute words in
+`CLAIM_WORDS` (always, never, exactly, every, no, at most, up to, within,
+...). The rule errs on catching too much: a sentence it catches that
+asserts nothing is reworded or struck, not argued with.
+
+**Cells.** `table` (the module and its CLAIMS exist), `row<N>` per CLAIMS
+row (the sentence is in the docstring, each named test exists by an AST
+lookup and passes when run alone under unittest on CPython; a skipped test
+has not passed), and `loose<N>` per claim-shaped docstring sentence that no
+row covers.
+
+CPython only: it reads the source and runs unittest.
+
+    python tests/support/kit_claims.py SlapbackDelay [--no-run]
+"""
+
+import ast
+import io
+import os
+import re
+import sys
+import unittest
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+
+CHECK = "claims"
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+TESTS = os.path.join(ROOT, "tests")
+
+NUMBER_WORDS = (
+    "zero one two three four five six seven eight nine ten eleven twelve "
+    "twenty thirty forty fifty sixty hundred thousand million half halves "
+    "twice double triple quarter third thirds").split()
+CLAIM_WORDS = (
+    "always never exactly every each all any no none nothing only cannot "
+    "can't must guarantee guarantees guaranteed bound bounded bounds limit "
+    "limits most least more less fewer than within under over above below "
+    "beyond until same identical unchanged untouched equal equals "
+    "maximum minimum max min").split()
+_WORDS = re.compile(r"[A-Za-z']+")
+_SENTENCE_END = re.compile(r"(?<=[.!?])\s+(?=[A-Z`*(\"'])")
+_ABBREV = ("e.g.", "i.e.", "etc.", "vs.", "cf.")
+_HEADING = re.compile(r"\*\*[^*]+\*\*")
+
+
+def flat(text):
+    return " ".join((text or "").split())
+
+
+def is_claim(sentence):
+    """Whether the sentence makes a claim, by the mechanical rule."""
+    if any(c.isdigit() for c in sentence):
+        return True
+    for word in _WORDS.findall(sentence.lower()):
+        if word in NUMBER_WORDS or word in CLAIM_WORDS:
+            return True
+    lowered = sentence.lower()
+    return "up to" in lowered or "at most" in lowered or \
+        "at least" in lowered
+
+
+def sentences(text):
+    """The flattened text cut into sentences, keeping e.g./i.e. inside."""
+    out = []
+    for piece in _SENTENCE_END.split(flat(text)):
+        if out and out[-1].endswith(_ABBREV):
+            out[-1] += " " + piece
+        else:
+            out.append(piece)
+    return [s for s in out if s.strip()]
+
+
+def test_index(path):
+    """{method name: [TestCase class names]} by an AST read of `path`."""
+    with open(path) as f:
+        tree = ast.parse(f.read(), path)
+    index = {}
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) \
+                        and item.name.startswith("test"):
+                    index.setdefault(item.name, []).append(node.name)
+    return index
+
+
+def targets(test):
+    if isinstance(test, (tuple, list)):
+        return list(test)
+    return [test]
+
+
+def resolve(target, index):
+    """Test ids ("Class.test_x") for one target, or None if none exists."""
+    if "." in target:
+        cls, meth = target.split(".", 1)
+        return [target] if cls in index.get(meth, ()) else None
+    owners = index.get(target)
+    if not owners:
+        return None
+    return ["%s.%s" % (owner, target) for owner in owners]
+
+
+def declared_exists(target):
+    import lifecycle
+    parts = target.split(":", 1)[1].split(",")
+    return len(parts) == 3 and tuple(parts) in lifecycle.DECLARED
+
+
+def run_tests(module, ids):
+    """{test id: None if it passed, else why not}."""
+    out = {}
+    for tid in ids:
+        suite = unittest.defaultTestLoader.loadTestsFromName(tid, module)
+        result = unittest.TextTestResult(io.StringIO(), False, 0)
+        suite.run(result)
+        if result.failures or result.errors:
+            out[tid] = "fails"
+        elif result.skipped:
+            out[tid] = "skipped"
+        elif result.testsRun == 0:
+            out[tid] = "did not run"
+        else:
+            out[tid] = None
+    return out
+
+
+def check(name, doc, module, path, emit=print, execute=True):
+    """The claims cells for a class with docstring `doc`, whose test module
+    is the imported `module` at `path`. Returns the red count."""
+    cells = kc.Cells(name, CHECK, emit)
+    claims = getattr(module, "CLAIMS", None) if module is not None else None
+    if not doc:
+        cells.cell("table", "RED(no docstring)")
+        return cells.summary()
+    if claims is None:
+        cells.cell("table", "RED(no CLAIMS table in %s)"
+                   % os.path.basename(path or "the test module"))
+        rows = ()
+    else:
+        cells.cell("table", "ok")
+        rows = claims
+    text = flat(doc)
+    index = test_index(path) if path else {}
+    ids = []
+    plans = []
+    for sentence, test in rows:
+        sentence = flat(sentence)
+        reds = []
+        mine = []
+        if sentence not in text:
+            reds.append("not in the docstring")
+        for target in targets(test):
+            if target.startswith("DECLARED:"):
+                if not declared_exists(target):
+                    reds.append("no lifecycle row %s" % target[9:])
+                continue
+            found = resolve(target, index)
+            if found is None:
+                reds.append("no test %s" % target)
+            else:
+                mine.extend(found)
+        ids.extend(t for t in mine if t not in ids)
+        plans.append((sentence, reds, mine))
+    results = run_tests(module, ids) if execute and ids else {}
+    rest = text
+    for n, (sentence, reds, mine) in enumerate(plans):
+        for tid in mine:
+            if results.get(tid):
+                reds.append("%s %s" % (tid, results[tid]))
+        rest = rest.replace(sentence, " ")
+        verdict = "RED(%s: %s)" % ("; ".join(reds), sentence[:60]) if reds \
+            else "ok"
+        cells.cell("row%d" % n, verdict)
+    n = 0
+    for sentence in sentences(rest):
+        sentence = flat(_HEADING.sub(" ", sentence))
+        if sentence and is_claim(sentence):
+            cells.cell("loose%d" % n, "RED(claim with no CLAIMS row: %s)"
+                       % sentence[:80])
+            n += 1
+    return cells.summary()
+
+
+def module_for(cls, name=None):
+    """(imported test module or None, its path)."""
+    name = name or "test_cpython_effects_%s" % cls.NAME.lower()
+    path = os.path.join(TESTS, name + ".py")
+    if TESTS not in sys.path:
+        sys.path.insert(0, TESTS)
+    if not os.path.isfile(path):
+        return None, None
+    return __import__(name), path
+
+
+def run(cls, emit=print, module=None, execute=True, name=None, **_):
+    try:
+        mod, path = module_for(cls, module)
+    except Exception as exc:                              # noqa: BLE001
+        cells = kc.Cells(name or cls.NAME, CHECK, emit)
+        cells.cell("table", "RED(the test module does not import: %s)"
+                   % type(exc).__name__)
+        return cells.summary()
+    return check(name or cls.NAME, player_text(cls), mod, path, emit,
+                 execute)
+
+
+def player_text(cls):
+    module = sys.modules.get(cls.__module__)
+    parts = [getattr(module, "__doc__", None), cls.__doc__]
+    return " ".join(flat(p) for p in parts if p)
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
new file mode 100644
index 0000000..0835be1
--- /dev/null
+++ b/tests/support/kit_common.py
@@ -0,0 +1,344 @@
+"""What the effects kit's checks share: material, rendering, the printed
+cell and the table of declared exceptions.
+
+Numpy-free, like `lifecycle.py`, so every render check runs unchanged on
+CPython, MicroPython and CircuitPython and the three can be held to the
+same printed lines. `KIT.md` beside this file says what each check
+measures.
+"""
+
+import sys
+import binascii
+
+try:
+    from array import array
+except ImportError:                                   # pragma: no cover
+    array = None
+
+import audiocore
+
+import lifecycle
+
+BLOCK = lifecycle.BLOCK
+RATES = lifecycle.RATES
+CHANNELS = lifecycle.CHANNELS
+RAIL = 32767
+
+#: Where a class cannot satisfy a kit cell by design, it says so HERE, one
+#: row per (class NAME, check, cell key prefix): reason. A matching RED
+#: cell prints `decl` and is counted as a declared exception. Nothing else
+#: skips a cell.
+DECLARED = {
+}
+
+CPYTHON = sys.implementation.name == "cpython"
+
+
+# --------------------------------------------------------------------------
+# Material: integer arithmetic only, so every interpreter makes the same
+# bytes.
+
+
+def _blank(frames, channels):
+    return array("h", bytes(2 * frames * channels))
+
+
+def noise(frames, channels, amp, seed=4242):
+    """LCG noise in [-amp, amp], each channel its own."""
+    values = _blank(frames, channels)
+    state = seed
+    span = 2 * amp + 1
+    for i in range(frames * channels):
+        state = lifecycle._lcg(state)
+        values[i] = ((state >> 8) % span) - amp
+    return values
+
+
+def dc(frames, channels, level, start=0):
+    """Zero until `start`, then `level` held."""
+    values = _blank(frames, channels)
+    for i in range(start * channels, frames * channels):
+        values[i] = level
+    return values
+
+
+def square(frames, channels, amp, period):
+    values = _blank(frames, channels)
+    half = period // 2
+    for frame in range(frames):
+        v = amp if (frame % period) < half else -amp
+        for ch in range(channels):
+            values[frame * channels + ch] = v
+    return values
+
+
+def sine(frames, channels, amp, period):
+    """A parabolic sine: each half period is 4 amp q (h - q) / h^2, so the
+    peak is `amp` and the bytes are the same everywhere."""
+    values = _blank(frames, channels)
+    half = period // 2
+    hh = half * half
+    for frame in range(frames):
+        p = frame % period
+        q = p % half
+        v = 4 * amp * q * (half - q) // hh
+        if p >= half:
+            v = -v
+        for ch in range(channels):
+            values[frame * channels + ch] = v
+    return values
+
+
+def clicks(frames, channels, amp, spacing=97):
+    """One-sample clicks every `spacing` frames, alternating in sign."""
+    values = _blank(frames, channels)
+    sign = 1
+    for frame in range(3, frames, spacing):
+        for ch in range(channels):
+            values[frame * channels + ch] = sign * amp
+        sign = -sign
+    return values
+
+
+def last_nonzero_frame(values, channels):
+    """One past the last frame with a non-zero sample, or 0."""
+    for i in range(len(values) - 1, -1, -1):
+        if values[i]:
+            return i // channels + 1
+    return 0
+
+
+def feed(values, rate, channels):
+    """The material in 256-frame blocks, then silence for ever, behind a
+    Port (lifecycle's Feed)."""
+    return lifecycle.Feed(values, rate, channels, "256", loop=False)
+
+
+# --------------------------------------------------------------------------
+# Rendering
+
+
+def pull(e):
+    """One block from `e.output`; 64 empty pulls in a row are a block of
+    silence (a source that has ended)."""
+    for _ in range(64):
+        data = bytes(audiocore.get_buffer(e.output)[1])
+        if data:
+            return data
+    fsize = 2 * e.channel_count
+    return bytes(BLOCK * fsize)
+
+
+def render(e, frames, actions=None):
+    """`frames` frames of `e.output` as bytes. `actions` maps a pull index
+    to a callable taken before that pull."""
+    fsize = 2 * e.channel_count
+    out = bytearray()
+    k = 0
+    while len(out) < frames * fsize:
+        if actions and k in actions:
+            actions[k](e)
+        out.extend(pull(e))
+        k += 1
+    return bytes(out[:frames * fsize])
+
+
+class Stream:
+    """Pulls without keeping the bytes: the CRC of everything handed, the
+    frame count, and one past the last frame holding a non-zero sample."""
+
+    def __init__(self, e):
+        self.e = e
+        self.fsize = 2 * e.channel_count
+        self.frames = 0
+        self.last = 0
+        self.nonzero = False
+        self.crc = 0
+        self.pulls = 0
+
+    def step(self):
+        data = pull(self.e)
+        self.crc = binascii.crc32(data, self.crc)
+        n = len(data) // self.fsize
+        if not lifecycle._is_zero(data):
+            d = lifecycle._last_diff(data, bytes(len(data)), 0, len(data))
+            self.last = self.frames + d // self.fsize + 1
+            self.nonzero = True
+        self.frames += n
+        self.pulls += 1
+        return data
+
+    def to(self, frames):
+        while self.frames < frames:
+            self.step()
+
+
+def crc_value(data, seed=0):
+    return binascii.crc32(data, seed)
+
+
+def crc(data, seed=0):
+    return "%08x" % (binascii.crc32(data, seed) & 0xFFFFFFFF)
+
+
+def samples(data):
+    return lifecycle._samples(data)
+
+
+def num(x):
+    """A number as every interpreter prints it."""
+    if isinstance(x, float):
+        return "%.6g" % x
+    return str(x)
+
+
+def finite(x):
+    try:
+        x = float(x)
+    except (TypeError, ValueError):
+        return False
+    return x == x and x not in (float("inf"), float("-inf"))
+
+
+# --------------------------------------------------------------------------
+# The class under test
+
+
+def build(cls, port, rate, patch=None, options=None):
+    e = cls(port, sample_rate=rate, **(options or {}))
+    if patch is not None:
+        e.program_change(patch)
+    return e
+
+
+def patches(cls):
+    return [None] + sorted(cls.PATCHES)
+
+
+def pname(patch):
+    return "d" if patch is None else "p%d" % patch
+
+
+def stops(cls, index):
+    return lifecycle.stops(cls, index)
+
+
+def knob_positions(cls):
+    """(index, value) for each macro at each of its stops, 64 included for
+    a bipolar macro."""
+    out = []
+    for i in range(len(cls.MACRO_LABELS)):
+        for v in stops(cls, i):
+            out.append((i, v))
+    return out
+
+
+def resolve(name):
+    """A class by provider name: a kit plant, a rebuilt class, or a class
+    `audioeffects` exports."""
+    import kit_planted
+    if name in kit_planted.PLANTS:
+        return kit_planted.PLANTS[name]
+    from audioeffects import rebuilt
+    cls = rebuilt.module_class(name)
+    if cls is None:
+        import audioeffects
+        cls = getattr(audioeffects, name, None)
+    return cls
+
+
+# --------------------------------------------------------------------------
+# Cells
+
+
+def declared(name, check, key):
+    for (cname, ccheck, prefix), _reason in DECLARED.items():
+        if cname == name and ccheck == check and key.startswith(prefix):
+            return True
+    return False
+
+
+class Cells:
+    """Emits `name|check|key|V:verdict[|h:digest]` per cell and a SUMMARY
+    line per check, counting red, declared and na cells."""
+
+    def __init__(self, name, check, emit=print):
+        self.name = name
+        self.check = check
+        self.emit = emit
+        self.cells = self.red = self.decl = self.na = 0
+        self.lines = []
+
+    def cell(self, key, verdict, digest=None):
+        verdict = verdict.replace("|", "/")
+        if verdict.startswith("RED") and declared(self.name, self.check,
+                                                  key):
+            verdict = "decl"
+        line = "%s|%s|%s|V:%s" % (self.name, self.check, key, verdict)
+        if digest is not None:
+            line += "|h:%s" % digest
+        self.cells += 1
+        if verdict.startswith("RED"):
+            self.red += 1
+        elif verdict == "decl":
+            self.decl += 1
+        elif verdict.startswith("na"):
+            self.na += 1
+        self.lines.append(line)
+        self.emit(line)
+
+    def summary(self):
+        self.emit("SUMMARY|%s|%s|cells %d|red %d|declared %d|na %d" % (
+            self.name, self.check, self.cells, self.red, self.decl,
+            self.na))
+        return self.red
+
+
+def parse(lines):
+    """{(name, check, key): {"V": verdict, "h": digest}} from printed
+    lines."""
+    out = {}
+    for line in lines:
+        parts = line.split("|")
+        if len(parts) < 4 or parts[0] in ("SUMMARY", "DONE", "SKIP"):
+            continue
+        props = {}
+        for p in parts[3:]:
+            k, _sep, v = p.partition(":")
+            props[k] = v
+        out[(parts[0], parts[1], parts[2])] = props
+    return out
+
+
+# --------------------------------------------------------------------------
+# Judging samples
+
+#: The longest run of frames a channel may sit on a rail (|y| >= 32767)
+#: where the input, `latency_samples` earlier, did not.
+RAIL_RUN = 8
+
+
+def rail_run(out, values, channels, lat=0):
+    """(longest run of output frames on a rail where the input was not,
+    the frame it starts at), over every channel."""
+    best = 0
+    where = -1
+    n = len(out) // channels
+    nin = len(values) // channels
+    for ch in range(channels):
+        run = 0
+        for f in range(n):
+            y = out[f * channels + ch]
+            if y >= RAIL or y <= -RAIL:
+                g = f - lat
+                x = values[g * channels + ch] if 0 <= g < nin else 0
+                if x >= RAIL or x <= -RAIL:
+                    run = 0
+                    continue
+                run += 1
+                if run > best:
+                    best = run
+                    where = f - run + 1
+            else:
+                run = 0
+    return best, where
diff --git a/tests/support/kit_options.py b/tests/support/kit_options.py
new file mode 100644
index 0000000..4c4fb74
--- /dev/null
+++ b/tests/support/kit_options.py
@@ -0,0 +1,16 @@
+"""The constructor options the kit builds a class with.
+
+Most classes are run at their defaults ({}). A class whose defaults are
+trivial (the generic `Rack`'s default chain is empty, so it is a wire) is
+given something real here, and every kit check builds it with these.
+"""
+
+KIT_OPTIONS = {
+    # Filled with a real chain when the Rack's kit run is set up.
+    "Rack": {"chain": ()},
+}
+
+
+def options_for(name):
+    """A fresh dict of the options for class NAME `name`."""
+    return dict(KIT_OPTIONS.get(name, {}))
diff --git a/tests/support/kit_paperwork.py b/tests/support/kit_paperwork.py
new file mode 100644
index 0000000..4d9c4ff
--- /dev/null
+++ b/tests/support/kit_paperwork.py
@@ -0,0 +1,212 @@
+"""The paperwork check: the class has a CHANGELOG line, and every source
+citation in its module resolves against the audiodsp pin.
+
+**CHANGELOG.** CHANGELOG.md names a class at the start of a bullet:
+``- **`DigitalDelay` (rebuilt, Phase 5; ...):**``. The `changelog` cell is
+red when no line starts with ``- **`<NAME>`**``.
+
+**Citations.** Every `<file>.c:NN`, `.h:NN`, `.py:NN` or `<path>:NN-MM`
+in the class's module (docstrings and comments alike), and every bare
+`` `:NN` `` after one, which cites the file named last. A citation that
+names a file in audiodsp at the commit in AUDIODSP_PIN (by path, or by
+file name when it gives no directory) must name lines inside that file
+there; one that names a file of this repository is read against the
+working tree. A file found in neither is red. Line numbers inside the
+file are all this can know: a citation whose lines moved under it still
+resolves.
+
+The pinned audiodsp is read from a checkout, never changed: `KIT_AUDIODSP`
+or an `audiodsp` directory beside this repository (or beside a parent of
+it). Without one, or without the pinned commit in it, each audiodsp
+citation prints `na(...)` saying which.
+
+CPython only: it reads git.
+
+    python tests/support/kit_paperwork.py DigitalDelay
+"""
+
+import os
+import re
+import subprocess
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+
+CHECK = "paperwork"
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+CITE = re.compile(
+    r"(?<![\w/.-])((?:[\w-]+/)*[\w.-]+\.(?:c|h|py)):(\d+)(?:-(\d+))?")
+MORE = re.compile(r"(?:(?<=[\s(,`])|^):(\d+)(?:-(\d+))?\b")
+
+
+def pin_commit(root=ROOT):
+    """The commit AUDIODSP_PIN names (its last non-comment line's second
+    word), or None."""
+    path = os.path.join(root, "AUDIODSP_PIN")
+    if not os.path.isfile(path):
+        return None
+    commit = None
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#"):
+                words = line.split()
+                commit = words[1] if len(words) > 1 else words[0]
+    return commit
+
+
+def find_checkout(root=ROOT):
+    env = os.environ.get("KIT_AUDIODSP")
+    if env:
+        return env if os.path.isdir(env) else None
+    here = root
+    for _up in range(6):
+        here = os.path.dirname(here)
+        candidate = os.path.join(here, "audiodsp")
+        if os.path.exists(os.path.join(candidate, ".git")):
+            return candidate
+    return None
+
+
+class Pin:
+    """The audiodsp tree at one commit, read with git."""
+
+    def __init__(self, checkout, commit):
+        self.checkout = checkout
+        self.commit = commit
+        self.why = None
+        self.files = None
+        self._lines = {}
+        if checkout is None:
+            self.why = "no audiodsp checkout"
+        elif commit is None:
+            self.why = "no AUDIODSP_PIN"
+        else:
+            done = subprocess.run(
+                ["git", "-C", checkout, "ls-tree", "-r", "--name-only",
+                 commit], capture_output=True, text=True)
+            if done.returncode != 0:
+                self.why = "pin %s is not in %s" % (commit[:10], checkout)
+            else:
+                self.files = done.stdout.split()
+
+    def match(self, path):
+        if self.files is None:
+            return []
+        if "/" in path:
+            return [f for f in self.files
+                    if f == path or f.endswith("/" + path)]
+        return [f for f in self.files if f.rsplit("/", 1)[-1] == path]
+
+    def lines(self, path):
+        if path not in self._lines:
+            done = subprocess.run(
+                ["git", "-C", self.checkout, "show",
+                 "%s:%s" % (self.commit, path)], capture_output=True)
+            self._lines[path] = done.stdout.count(b"\n") \
+                if done.returncode == 0 else 0
+        return self._lines[path]
+
+
+def local_match(path, root=ROOT):
+    if "/" in path and os.path.isfile(os.path.join(root, path)):
+        return [os.path.join(root, path)]
+    base = path.rsplit("/", 1)[-1]
+    out = []
+    for top in ("lib", "tools", "tests"):
+        for here, _dirs, files in os.walk(os.path.join(root, top)):
+            if base in files:
+                full = os.path.join(here, base)
+                if full.endswith(path):
+                    out.append(full)
+    return sorted(out)
+
+
+def _count(path):
+    with open(path, "rb") as f:
+        return f.read().count(b"\n")
+
+
+def citations(text):
+    """[(file, first line, last line)] in the order they appear; a bare
+    `:NN` cites the file named last."""
+    found = []
+    for m in CITE.finditer(text):
+        found.append((m.start(), m.group(1), int(m.group(2)),
+                      int(m.group(3) or m.group(2))))
+    for m in MORE.finditer(text):
+        before = [c for c in found if c[0] < m.start() and c[1] is not None]
+        if not before:
+            continue
+        last = max(before, key=lambda c: c[0])
+        found.append((m.start(), last[1], int(m.group(1)),
+                      int(m.group(2) or m.group(1))))
+    found.sort()
+    return [(f, a, b) for _pos, f, a, b in found]
+
+
+def cite_verdict(path, first, last, pin, root=ROOT):
+    if last < first:
+        return "RED(range runs backwards)"
+    hits = pin.match(path)
+    if hits:
+        fits = [h for h in hits if last <= pin.lines(h)]
+        if not fits:
+            return "RED(%s has %d lines at the pin)" % (
+                hits[0], max(pin.lines(h) for h in hits))
+        return "ok"
+    local = local_match(path, root)
+    if local:
+        if any(last <= _count(p) for p in local):
+            return "ok"
+        return "RED(%s has %d lines)" % (os.path.relpath(local[0], root),
+                                         _count(local[0]))
+    if pin.files is None:
+        return "na(%s)" % pin.why
+    return "RED(no %s at the pin or in this repository)" % path
+
+
+def has_changelog_line(name, changelog_text):
+    head = "- **`%s`" % name
+    for line in changelog_text.splitlines():
+        if line.startswith(head):
+            return True
+    return False
+
+
+def check(name, text, changelog_text, pin, emit=print, root=ROOT):
+    """The paperwork cells for class `name` whose module source is `text`.
+    Returns the red count."""
+    cells = kc.Cells(name, CHECK, emit)
+    cells.cell("changelog", "ok" if has_changelog_line(name, changelog_text)
+               else "RED(no CHANGELOG line starts - **`%s`)" % name)
+    seen = {}
+    for path, first, last in citations(text):
+        key = "cite:%s:%d" % (path, first)
+        if last != first:
+            key += "-%d" % last
+        if key in seen:
+            continue
+        seen[key] = True
+        cells.cell(key, cite_verdict(path, first, last, pin, root))
+    return cells.summary()
+
+
+def run(cls, emit=print, name=None, **_):
+    module = sys.modules[cls.__module__]
+    with open(module.__file__) as f:
+        text = f.read()
+    with open(os.path.join(ROOT, "CHANGELOG.md")) as f:
+        changelog = f.read()
+    pin = Pin(find_checkout(), pin_commit())
+    return check(name or cls.NAME, text, changelog, pin, emit)
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_planted.py b/tests/support/kit_planted.py
new file mode 100644
index 0000000..f902967
--- /dev/null
+++ b/tests/support/kit_planted.py
@@ -0,0 +1,314 @@
+"""The kit's planted faults: tiny components that each break one thing a
+kit check measures, beside the controls that break nothing.
+
+`tests/test_kit.py` holds every plant red on its cell and its control
+green on the same cell. Each is an `audioshaper.Waveshaper` (a table and a
+level) around the borrowed source, with an `audioecho.FeedbackDelay` after
+it for the tail plants, so they render fast on every interpreter.
+"""
+
+import sys
+
+try:
+    from array import array
+except ImportError:                                   # pragma: no cover
+    array = None
+
+from audioeffects import _component
+
+#: `_component` reads VENDOR off the module a class is defined in.
+VENDOR = "PyDevices"
+
+
+def _curve(fn):
+    """A Q15 Waveshaper table of 4097 points over the int16 input."""
+    table = array("h", bytes(2 * 4097))
+    for i in range(4097):
+        table[i] = max(-32768, min(32767, fn((i - 2048) * 16)))
+    return table
+
+
+def _same(x):
+    return x
+
+
+def _wrap2(x):
+    y = 2 * x
+    while y > 32767:
+        y -= 65536
+    while y < -32768:
+        y += 65536
+    return y
+
+
+def _clip2(x):
+    return 2 * x
+
+
+def _dc9(x):
+    return x + 9
+
+
+def _nothing(x):
+    return 0
+
+
+class KitPlain(_component.Component):
+    """The control: the source through a straight table at a level of
+    1 - Mix + Mix x Gain, Gain from 0.25 to 1, so no knob position is
+    silent and none goes past unity."""
+    NAME = "KitPlain"
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioroute", "audioshaper")
+    LATENCY_SAMPLES = 0
+    TAIL_SAMPLES = 0
+    MACRO_LABELS = ("Mix", "Gain")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (0.25, 1.0))
+    PATCHES = {0: ("Unity", (127, 127)), 1: ("Soft", (127, 96))}
+    CURVE = staticmethod(_same)
+
+    def _build(self, mix=1.0, gain=1.0, patch=None):
+        import audioshaper
+        self._shaper = self._own(audioshaper.Waveshaper(
+            curve=_curve(type(self).CURVE), oversample=1,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._arm()
+        self._macros = [0.0, 0.0]
+        self._init_macros((mix, gain), patch)
+
+    def _arm(self):
+        self._shaper.play(self._source)
+        self._output = self._shaper
+
+    def _level(self):
+        mix = self.macro(0)
+        return 1.0 - mix + mix * self.macro(1)
+
+    def _apply_macro(self, index, position):
+        self._shaper.set(post_gain=self._level())
+
+
+class Silent(KitPlain):
+    """A class that does nothing at all: every check must tell it from a
+    pass."""
+    NAME = "Silent"
+    CURVE = staticmethod(_nothing)
+
+
+# -- the input ceiling -------------------------------------------------------
+
+
+class WrapKit(KitPlain):
+    """Ceiling: twice the input, wrapped round int16 as a missing clamp
+    would."""
+    NAME = "WrapKit"
+    CURVE = staticmethod(_wrap2)
+
+
+class WrapKitQuiet(WrapKit):
+    """The same class stating a level it is clean at: 7 dB down, where
+    twice the input stays inside int16."""
+    NAME = "WrapKitQuiet"
+    INPUT_CEILING_DBFS = -7
+
+
+class ClipKit(KitPlain):
+    """Ceiling: twice the input, clamped, so a loud input sits on the
+    rail."""
+    NAME = "ClipKit"
+    CURVE = staticmethod(_clip2)
+
+
+class DeadStop(KitPlain):
+    """Ceiling: Gain's bottom stop is silence, as a level that went NaN on
+    a board would be."""
+    NAME = "DeadStop"
+
+    def _level(self):
+        if self._macros[1] == 0.0:
+            return 0.0
+        return KitPlain._level(self)
+
+
+class ImplKit(KitPlain):
+    """P6: the level is a hair different off CPython, so every render
+    check prints other bytes natively."""
+    NAME = "ImplKit"
+
+    def _level(self):
+        level = KitPlain._level(self)
+        if sys.implementation.name != "cpython":
+            level = level * 0.99
+        return level
+
+
+# -- the tail ---------------------------------------------------------------
+
+
+class EchoTail(KitPlain):
+    """One repeat 20 ms after the input, nothing dry, and a tail that says
+    so (2048 frames covers 20 ms at 48 and 22.05 kHz)."""
+    NAME = "EchoTail"
+    TAIL_SAMPLES = 2048
+    REQUIRES = ("audioroute", "audioshaper", "audioecho")
+
+    def _build(self, mix=1.0, gain=1.0, patch=None):
+        import audioecho
+        self._delay = self._own(audioecho.FeedbackDelay(
+            max_delay_ms=50, delay_ms=20, feedback=0.0, mix=1.0,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        KitPlain._build(self, mix, gain, patch)
+
+    def _arm(self):
+        self._shaper.play(self._source)
+        self._delay.play(self._shaper)
+        self._output = self._delay
+
+
+class ShortTail(EchoTail):
+    """Tail: `tail_samples` 0 under a 20 ms repeat."""
+    NAME = "ShortTail"
+    TAIL_SAMPLES = 0
+
+
+class EventTail(EchoTail):
+    """Tail: right at construction, 0 after any control move, though the
+    repeat never changes."""
+    NAME = "EventTail"
+
+    @property
+    def tail_samples(self):
+        self._check_live()
+        return 0 if getattr(self, "_moved", False) else 2048
+
+    def set_macro(self, index, value, *args, **kw):
+        EchoTail.set_macro(self, index, value, *args, **kw)
+        self._moved = True
+
+    def program_change(self, index, *args, **kw):
+        EchoTail.program_change(self, index, *args, **kw)
+        if not self._constructing:
+            self._moved = True
+
+
+class NoneSilent(EchoTail):
+    """Tail: reports no bound, and falls silent 20 ms after the input."""
+    NAME = "NoneSilent"
+    TAIL_SAMPLES = None
+
+
+class NoneDC(KitPlain):
+    """Tail: reports no bound, and never falls silent (a DC of 9)."""
+    NAME = "NoneDC"
+    TAIL_SAMPLES = None
+    CURVE = staticmethod(_dc9)
+
+
+# -- plant validity ------------------------------------------------------------
+
+
+class Inert(KitPlain):
+    """Plants: a plant that changes nothing."""
+
+
+class KnobReach(KitPlain):
+    """Plants: Gain stuck at its bottom stop, which the knob reaches."""
+
+    def _level(self):
+        mix = self.macro(0)
+        return 1.0 - mix + mix * 0.25
+
+
+class DCOffset(KitPlain):
+    """Plants: a DC of 9 under the output, which no knob reaches."""
+    CURVE = staticmethod(_dc9)
+
+
+class SoftOnly(KitPlain):
+    """Plants: a fault only patch 1 shows (its Gain read a step low)."""
+
+    def _level(self):
+        if self._patch_index == 1:
+            mix = self.macro(0)
+            return 1.0 - mix + mix * (0.25 + 0.75 * 95.0 / 127.0)
+        return KitPlain._level(self)
+
+    def program_change(self, index, *args, **kw):
+        KitPlain.program_change(self, index, *args, **kw)
+        self._apply_macro(1, self._macros[1])
+
+
+#: KitPlain's plants, the way a class's test module declares them: a
+#: label to a plant, or to (plant, the patch it is judged at).
+KIT_PLANTS = {"inert": Inert, "knob": KnobReach, "valid": DCOffset,
+              "soft": (SoftOnly, 1), "soft-at-d": SoftOnly}
+
+
+# -- readback and arguments ---------------------------------------------------
+
+
+class ReadbackOff(KitPlain):
+    """Args: get_macro reads half a step under where the knob is."""
+    NAME = "ReadbackOff"
+
+    def get_macro(self, index):
+        return KitPlain.get_macro(self, index) - 0.5
+
+
+class StopRaises(KitPlain):
+    """Args: the top stop is refused."""
+    NAME = "StopRaises"
+
+    def set_macro(self, index, value, *args, **kw):
+        if value == 127:
+            raise ValueError("planted: 127 refused")
+        KitPlain.set_macro(self, index, value, *args, **kw)
+
+
+class NanLevel(KitPlain):
+    """Args: a NaN macro reads back 0 but plays a level of 0.5."""
+    NAME = "NanLevel"
+
+    def set_macro(self, index, value, *args, **kw):
+        KitPlain.set_macro(self, index, value, *args, **kw)
+        if value != value:
+            self._shaper.set(post_gain=0.5)
+
+
+class PatchStale(KitPlain):
+    """Args: a patch change applies only the first macro."""
+    NAME = "PatchStale"
+
+    def program_change(self, index, *args, **kw):
+        patch = type(self).PATCHES.get(index)
+        if patch is None:
+            return
+        self._macros[0] = _component.position_of_midi("UNIPOLAR",
+                                                      patch[1][0])
+        self._apply_macro(0, self._macros[0])
+        self._patch_index = index
+
+
+class CtorNan(KitPlain):
+    """Args: a NaN Gain builds a level of 0.6, neither the default nor
+    the bottom stop."""
+    NAME = "CtorNan"
+
+    def _build(self, mix=1.0, gain=1.0, patch=None):
+        self._nan = gain != gain
+        KitPlain._build(self, mix, gain, patch)
+
+    def _level(self):
+        if self._nan:
+            return 0.6
+        return KitPlain._level(self)
+
+
+PLANTS = {}
+for _cls in (KitPlain, Silent, WrapKit, WrapKitQuiet, ClipKit, DeadStop,
+             ImplKit, EchoTail, ShortTail, EventTail, NoneSilent, NoneDC,
+             ReadbackOff, StopRaises, NanLevel, PatchStale, CtorNan):
+    PLANTS[_cls.NAME] = _cls
diff --git a/tests/support/kit_plants.py b/tests/support/kit_plants.py
new file mode 100644
index 0000000..7dc66f3
--- /dev/null
+++ b/tests/support/kit_plants.py
@@ -0,0 +1,167 @@
+"""Plant validity: each planted fault a class's tests use differs from the
+clean class at the defaults, and no knob position and no patch of the
+clean class renders what the plant renders.
+
+A plant that renders what the clean class renders proves nothing, and a
+plant some knob reaches is a setting, not a fault: a test that goes red on
+it would go red on a user turning that knob.
+
+**Declaring plants.** A class's test module (by default
+`tests/test_cpython_effects_<name>.py`, name in lower case) declares
+`KIT_PLANTS = {"T1": PlantedSubclass, ...}`: a label (the trait or test
+the plant serves) to a subclass of the class. A value may instead be
+`(PlantedSubclass, patch)`: the plant is then judged against the clean
+class at that patch instead of the defaults (a class with two characters
+plants faults in the one the defaults do not use), and the walk below
+still covers every patch and stop. `(PlantedSubclass, patch, settings)`
+adds `rate`, `channels` and constructor `options` for a plant that only
+shows at one setting (`patch` may be None). A module that does not import on an interpreter (one that needs
+numpy, natively) prints `na(...)`; keep plants in a numpy-free module and
+name it with `--plants-module` to check them natively.
+
+**What is compared.** The digest of the render (an 8192-frame click and
+noise train, then silence to the clean class's tail at the defaults,
+between 16384 frames and 4 s) together with `tail_samples` and
+`latency_samples`. The plant is rendered at its patch (or its defaults),
+the clean class at its defaults, with each macro alone at each stop (0
+and 127, and 64 for a bipolar macro), and at every patch, all at the
+plant's settings.
+
+    python tests/support/kit_plants.py SlapbackDelay
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+import lifecycle
+
+CHECK = "plants"
+PROBE_FRAMES = 8192
+MIN_FRAMES = 16384
+MAX_SECONDS = 4
+
+_PROBE = {}
+
+
+def probe(channels):
+    if channels not in _PROBE:
+        _PROBE[channels] = lifecycle.click_noise(PROBE_FRAMES, channels)
+    return _PROBE[channels]
+
+
+def module_name(cls):
+    return "test_cpython_effects_%s" % cls.NAME.lower()
+
+
+def load_plants(cls, module=None):
+    """(KIT_PLANTS dict or None, why not)."""
+    name = module or module_name(cls)
+    try:
+        mod = __import__(name)
+    except Exception as exc:                              # noqa: BLE001
+        return None, "%s does not import: %s" % (name, type(exc).__name__)
+    plants = getattr(mod, "KIT_PLANTS", None)
+    if plants is None:
+        return None, "%s has no KIT_PLANTS" % name
+    return plants, None
+
+
+def _setting(value, options=None):
+    """(plant, patch, rate, channels, options) for one KIT_PLANTS value."""
+    patch = None
+    settings = {}
+    if isinstance(value, tuple):
+        cls = value[0]
+        if len(value) > 1:
+            patch = value[1]
+        if len(value) > 2:
+            settings = value[2]
+    else:
+        cls = value
+    merged = dict(options or {})
+    merged.update(settings.get("options", {}))
+    return (cls, patch, settings.get("rate", 48000),
+            settings.get("channels", 2), merged)
+
+
+def digest(cls, rate, channels, frames, options=None, patch=None,
+           knob=None):
+    values = probe(channels)
+    feed = kc.feed(values, rate, channels)
+    e = kc.build(cls, feed.port, rate, patch, options)
+    try:
+        if knob is not None:
+            e.set_macro(knob[0], knob[1])
+        data = kc.render(e, frames)
+        state = "|%r|%r" % (e.tail_samples, e.latency_samples)
+        return kc.crc(state.encode(), kc.crc_value(data))
+    finally:
+        e.deinit()
+
+
+def frames_for(cls, rate, channels, options):
+    feed = kc.feed(probe(channels), rate, channels)
+    e = kc.build(cls, feed.port, rate, None, options)
+    try:
+        tail = e.tail_samples
+        lat = e.latency_samples
+    finally:
+        e.deinit()
+    if tail is None:
+        extra = MAX_SECONDS * rate
+    else:
+        extra = min(tail + lat + kc.BLOCK, MAX_SECONDS * rate)
+    return max(MIN_FRAMES, PROBE_FRAMES + extra)
+
+
+def check_plant(clean, plant, rate, channels, options, patch=None):
+    """(verdict, plant digest)."""
+    frames = frames_for(clean, rate, channels, options)
+    planted = digest(plant, rate, channels, frames, options, patch=patch)
+    if digest(clean, rate, channels, frames, options, patch=patch) == \
+            planted:
+        return "RED(same as clean at %s)" % (
+            "the defaults" if patch is None else "patch %d" % patch), planted
+    if patch is not None and digest(clean, rate, channels, frames,
+                                    options) == planted:
+        return "RED(reproduced by the defaults)", planted
+    for knob in kc.knob_positions(clean):
+        if digest(clean, rate, channels, frames, options,
+                  knob=knob) == planted:
+            return "RED(reproduced by m%d=%d)" % knob, planted
+    for patch in sorted(clean.PATCHES):
+        if digest(clean, rate, channels, frames, options,
+                  patch=patch) == planted:
+            return "RED(reproduced by patch %d)" % patch, planted
+    return "ok", planted
+
+
+def run(cls, emit=print, module=None, plants=None, name=None, quick=False,
+        options=None):
+    """Every plant's cell for `cls`; returns the red count."""
+    cells = kc.Cells(name or cls.NAME, CHECK, emit)
+    if plants is None:
+        plants, why = load_plants(cls, module)
+        if plants is None:
+            cells.cell("-", "na(%s)" % why)
+            return cells.summary()
+    for label in sorted(plants):
+        plant, patch, rate, channels, opts = _setting(plants[label], options)
+        key = "%s/%d/%d/%s" % (label, rate, channels, kc.pname(patch))
+        try:
+            verdict, dig = check_plant(cls, plant, rate, channels, opts,
+                                       patch)
+        except Exception as exc:                          # noqa: BLE001
+            verdict, dig = "RED(raised %s: %s)" % (type(exc).__name__,
+                                                  exc), None
+        cells.cell(key, verdict, dig)
+    return cells.summary()
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_tail.py b/tests/support/kit_tail.py
new file mode 100644
index 0000000..5b86c5e
--- /dev/null
+++ b/tests/support/kit_tail.py
@@ -0,0 +1,160 @@
+"""The tail harness: the output reaches exact zero inside the tail the class
+reports, read after every control event, on a DC step and on low bursts.
+
+A cell plays 4096 frames of material and then silence. The event's move
+lands 3072 frames in (pull 12, inside the material) and, for the `back`
+placement, its way back 1536 frames after the input stops. `tail_samples`
+is read after each action; the bound is the last reading + latency + one
+block, counted from the input's last non-zero frame or from the last
+action, whichever is later (lifecycle P2's bound). The output's last
+non-zero frame must be inside it; 2048 frames past it are rendered to see.
+
+A class whose `tail_samples` is None gives no bound, so it must never fall
+silent: the cell renders 3 s past the input and prints `na(tail None)`
+when the output is still non-zero in the last second, RED when it fell
+silent before (then the class could have stated a bound). A cell whose
+output was zero all along prints `na(silent)`: it shows nothing.
+
+    python tests/support/kit_tail.py DigitalDelay [--quick]
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import kit_common as kc
+import lifecycle
+
+CHECK = "tail"
+MAT_FRAMES = 16 * kc.BLOCK
+K_AWAY = 12
+K_BACK = 22
+MARGIN = lifecycle.MARGIN
+#: For a class with no bound: seconds rendered past the input, and the
+#: closing stretch that must still hold a non-zero sample.
+NONE_WINDOW_S = 3
+NONE_LIVE_S = 1
+
+MATERIALS = ("dc", "lsb3", "m60", "fs")
+#: The lifecycle events the harness reads the tail after: a reset, a macro
+#: to each stop, Mix to 0, a patch change.
+EVENT_PREFIXES = ("E1-reset@block", "E4-", "E5-", "E6-")
+
+_MAT = {}
+
+
+def material(which, channels):
+    """`dc` a DC step to -6 dBFS, `lsb3` noise at +-3 LSB, `m60` noise
+    at -60 dBFS (+-33), `fs` full-scale noise; 4096 frames each."""
+    key = (which, channels)
+    if key not in _MAT:
+        if which == "dc":
+            values = kc.dc(MAT_FRAMES, channels, 16384)
+        elif which == "lsb3":
+            values = kc.noise(MAT_FRAMES, channels, 3)
+        elif which == "m60":
+            values = kc.noise(MAT_FRAMES, channels, 33)
+        elif which == "fs":
+            values = kc.noise(MAT_FRAMES, channels, 32767)
+        else:
+            raise ValueError(which)
+        _MAT[key] = values
+    return _MAT[key]
+
+
+def tail_events(cls, patch, quick):
+    """(name, lifecycle Event or None, placement) for one patch."""
+    out = [("none", None, "held")]
+    for ev in lifecycle.events(cls, patch, quick):
+        if not lifecycle._starts(ev.name, EVENT_PREFIXES):
+            continue
+        out.append((ev.name, ev, "held"))
+        if ev.back and not quick:
+            out.append((ev.name, ev, "back"))
+    return out
+
+
+def measure(cls, rate, channels, patch, which, ev, placement, options=None):
+    """(verdict, digest) for one cell."""
+    values = material(which, channels)
+    in_end = kc.last_nonzero_frame(values, channels)
+    feed = kc.feed(values, rate, channels)
+    e = kc.build(cls, feed.port, rate, patch, options)
+    try:
+        ctx = lifecycle.Ctx(e, patch)
+        s = kc.Stream(e)
+        tail = e.tail_samples
+        last_action = 0
+        pulls = K_BACK + 1 if placement == "back" else K_AWAY + 1
+        for k in range(pulls):
+            if ev is not None and k == K_AWAY:
+                lifecycle.act(e, feed, ctx, ev.away)
+                last_action = s.frames
+                tail = e.tail_samples
+            if ev is not None and placement == "back" and k == K_BACK:
+                lifecycle.act(e, feed, ctx, ev.back)
+                last_action = s.frames
+                tail = e.tail_samples
+            s.step()
+        lat = e.latency_samples
+        start = max(in_end, last_action)
+        if tail is None:
+            window = start + NONE_WINDOW_S * rate
+            s.to(window)
+            if not s.nonzero:
+                verdict = "na(silent)"
+            elif s.last <= window - NONE_LIVE_S * rate:
+                verdict = "RED(tail None, silent from +%d)" % (s.last - start)
+            else:
+                verdict = "na(tail None)"
+        else:
+            bound = start + tail + lat + kc.BLOCK
+            s.to(bound + MARGIN)
+            if not s.nonzero:
+                verdict = "na(silent)"
+            elif s.last <= bound:
+                verdict = "ok"
+            else:
+                verdict = "RED(rings to +%d, bound +%d)" % (s.last - start,
+                                                           bound - start)
+        return verdict, "%08x" % (s.crc & 0xFFFFFFFF)
+    finally:
+        e.deinit()
+
+
+def run(cls, emit=print, quick=False, rates=kc.RATES, channels=kc.CHANNELS,
+        patches=None, materials=MATERIALS, events=None, options=None,
+        name=None):
+    """Every tail cell for `cls`; returns the red count. `events` limits the
+    cells to event names starting with one of its prefixes."""
+    cells = kc.Cells(name or cls.NAME, CHECK, emit)
+    if patches is None:
+        patches = kc.patches(cls)
+    for rate in rates:
+        for ch in channels:
+            for patch in patches:
+                for evname, ev, placement in tail_events(cls, patch, quick):
+                    if events is not None and not lifecycle._starts(
+                            evname, events):
+                        continue
+                    for which in materials:
+                        key = "%s/%d/%d/%s/%s" % (which, rate, ch,
+                                                  kc.pname(patch), evname)
+                        if placement == "back":
+                            key += "/back"
+                        try:
+                            verdict, digest = measure(
+                                cls, rate, ch, patch, which, ev, placement,
+                                options)
+                        except Exception as exc:          # noqa: BLE001
+                            verdict, digest = "RED(raised %s: %s)" % (
+                                type(exc).__name__, exc), None
+                        cells.cell(key, verdict, digest)
+    return cells.summary()
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))

From d8e96a6fb04698b6be13943069007946c7935f00 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:49:50 -0500
Subject: [PATCH 04/76] The kit's own proof and its page

tests/test_kit.py holds every kit check red on a planted fault with its
control green on the same cell, a do-nothing class never read as a pass,
and the render checks printing the same lines on CPython, MicroPython and
CircuitPython (with a plant whose bytes differ natively to show that
agreement can fail). KIT.md says what each check measures, its bars and
conventions, and how a class declares an exception.

The ceiling's wrap rule now asks that the jump unwraps to a neighbour, so
a full-scale click followed by a delay's repeat is not read as a wrap.
---
 tests/support/KIT.md         | 181 ++++++++++++++
 tests/support/kit_ceiling.py |  16 +-
 tests/test_kit.py            | 443 +++++++++++++++++++++++++++++++++++
 3 files changed, 635 insertions(+), 5 deletions(-)
 create mode 100644 tests/support/KIT.md
 create mode 100644 tests/test_kit.py

diff --git a/tests/support/KIT.md b/tests/support/KIT.md
new file mode 100644
index 0000000..ba40d86
--- /dev/null
+++ b/tests/support/KIT.md
@@ -0,0 +1,181 @@
+# The effects kit
+
+Six mechanical checks that run on one effect class with no model in the
+loop: every verdict is arithmetic on rendered bytes, or on the source. They
+sit beside the [lifecycle matrix](LIFECYCLE.md) and catch the kinds of
+defect that kept turning up class after class: a tail that outlasts
+`tail_samples`, a planted fault a knob can reach, a docstring promise no
+test holds, a control that does not read back what it was set to, an input
+level that wraps, and a citation that no longer resolves.
+
+To run all six on one class, from the repo root:
+
+    python tests/support/kit.py DigitalDelay
+    python tests/support/kit.py DigitalDelay --only tail,ceiling --quick
+    MICROPYPATH=lib:tests/support micropython -X heapsize=256M \
+        tests/support/kit.py DigitalDelay --quick
+
+Each check also runs alone (`python tests/support/kit_tail.py
+DigitalDelay`). `--quick` trims the grid (below); `--no-run` makes the
+claims check look the tests up without running them; `--plants-module` and
+`--claims-module` name a test module other than the class's own.
+
+It prints one line per cell, `name|check|key|V:verdict[|h:digest]`, a
+`SUMMARY|name|check|cells N|red R|declared D|na A` line per check, and
+`DONE`. A verdict is `ok`, `na(...)` (the cell cannot show anything, said
+why), `RED(...)` with what was measured, or `decl`. `h:` is a CRC-32 of the
+cell's render, so two interpreters' lines agree only when their bytes do.
+
+The four render checks (tail, plants, args, ceiling) are numpy-free and
+print the same lines on CPython, MicroPython and CircuitPython. The claims
+and paperwork checks read source, unittest and git, and run on CPython
+only; a native run prints `SKIP` for them.
+
+A class that does nothing at all must not read as a pass: the tail and
+args checks print `na(silent)` for a render that was zero throughout, and
+the ceiling check is red on it.
+
+## The checks
+
+**tail** (`kit_tail.py`). The output reaches exact zero inside the tail
+the class reports, read after every event. The material: a DC step to
+-6 dBFS, noise at +-3 LSB, noise at -60 dBFS and full-scale noise, 4096
+frames each, then silence. The events are the lifecycle matrix's own
+(reset, each macro to each stop, Mix to 0, each patch change), plus none.
+The move lands inside the material; with `back` its way back lands 1536
+frames after the input stops. Bar: the output's last non-zero frame is
+within `tail_samples` (read after the last action) + `latency_samples` +
+one block of the input's end or the last action, whichever is later
+(lifecycle P2's bound). A class whose `tail_samples` is None promises no
+bound, so it must never fall silent: 3 s past the input the output must
+still be non-zero in the last second, `na(tail None)`, or the cell is red
+(the class could have stated a bound). Grid: every patch, 48 and 22.05 kHz,
+stereo and mono; `--quick` runs the full events at the defaults and the
+lifecycle's quick subset at the patches, with no `back` placements.
+
+**plants** (`kit_plants.py`). Each planted fault the class's tests use
+differs from the clean class, and no knob position or patch of the clean
+class renders what it renders. The class's test module (by default
+`tests/test_cpython_effects_<name>.py`) declares them:
+
+    KIT_PLANTS = {"T1": JumpTimeSlapback, "T3": (SplitSlapback, 4)}
+
+A value is a planted subclass, judged against the clean class at the
+defaults, or `(plant, patch)`, judged at that patch (a class with two
+characters plants faults in the one the defaults do not use); a third
+element, a dict, may give `rate`, `channels` and constructor `options`. The
+digest covers the render (an 8192-frame click and noise train, then
+silence to the clean class's tail, 16384 frames to 4 s) and the reported
+`tail_samples` and `latency_samples`. The walk: the clean class at the
+defaults, each macro alone at each stop (0 and 127, and 64 for a bipolar
+macro), and every patch. A module that does not import on an interpreter
+prints `na(...)`; plants kept in a numpy-free module check natively.
+
+**claims** (`kit_claims.py`). Every docstring sentence that makes a claim
+names a test, which exists and passes. The class's test module holds a
+`CLAIMS` table, one row per sentence, word for word:
+
+    CLAIMS = (
+        ("Level 0 is a wire.", "test_level_zero_is_a_wire"),
+        ("Time runs from 40 to 250 ms.",
+         ("TestKnobs.test_the_spans", "test_the_time_law")),
+        ("A control that jumps makes the output step: ...",
+         "DECLARED:TapeDelay,E4-m2=,P5"),
+    )
+
+A test is a method name (any TestCase that defines it), `Class.test_name`,
+a tuple of those, or `DECLARED:<NAME>,<event prefix>,<property>`, a row of
+the lifecycle matrix's DECLARED table. "Exists" is an AST lookup in the test
+module; "passes" runs that test alone under unittest (a skip is not a pass).
+The text is the class's module docstring and then its class docstring. A
+sentence is a claim if it holds a digit, a number word, or a bound or
+absolute word (always, never, exactly, every, each, all, no, only, at most,
+at least, up to, within, under, over, same, unchanged, ...: `CLAIM_WORDS`).
+The rule errs on catching too much: a sentence it catches that asserts
+nothing is reworded or struck. Cells: `table`, `row<N>` per row, and
+`loose<N>` per claim-shaped sentence no row covers.
+
+**args** (`kit_args.py`). What the control surface does with what a host
+hands it:
+
+- `rt-m<i>`: `set_macro(i, get_macro(i))` mid-stream changes no byte, at
+  the defaults and every patch.
+- `stops-m<i>`: 0, 64 and 127 are accepted and read back within 1e-4.
+- `bad-m<i>`: NaN, +-inf, -1 and 128. The contract
+  ([audio-component-api.md](../../docs/audio-component-api.md)) does not
+  say whether an out-of-range macro value raises or clamps, so either
+  passes: a raise is ValueError or TypeError and moves no macro (`r`); a
+  clamp reads back a finite 0..127 (0 below, 127 above) and renders
+  exactly what `set_macro(i, readback)` renders (`c`).
+- `patch-p<k>`: `program_change(k)` sets `patch_index` and reads back the
+  patch's values, and `program_change(0)` reads back what a fresh instance
+  read (the contract: a fresh component and one given patch 0 are the
+  same).
+- `ctor-<option>`: each numeric keyword of `_build` at 0 and NaN. A raise is
+  ValueError or TypeError; a build reports readable latency and tail,
+  finite macros, renders without raising or sitting on a rail the input
+  was not on; and a NaN build renders exactly what the defaults or the
+  option at 0 render.
+
+**ceiling** (`kit_ceiling.py`). At the level the class says it is clean
+at, on the worst material, the output does not wrap, sit on a rail, or go
+silent. The class states `INPUT_CEILING_DBFS` (dBFS, 0 or below); with
+none it is held to 0 dBFS. The material, 2 s at the peak: a 100 Hz square,
+a 50 Hz sine, one-sample clicks of alternating sign, noise, and a DC step,
+at the defaults, every patch and each macro alone at each stop, at 48 and
+22.05 kHz, stereo and mono (`--quick`: 48 kHz stereo). The bars:
+
+- `wrap`: neighbouring samples of opposite sign more than 32768 apart,
+  where the second, moved by 65536, lands within a quarter of the jump of
+  the first and the signal runs the same way either side, and the input
+  made no such jump: an int16 sum that overflowed. Not judged on the
+  noise. A flat signal that wraps is not caught.
+- `rail`: more than 8 frames in a row at |y| >= 32767 where the input was
+  not.
+- `silent`: the last second exactly zero while the input played through
+  it (not judged on the DC step, which a high-pass rightly takes to zero).
+
+**paperwork** (`kit_paperwork.py`). CHANGELOG.md has a bullet starting
+``- **`<NAME>`**``, and every citation in the class's module
+(`file.c:NN`, `path/file.h:NN-MM`, `file.py:NN`, and a bare `` `:NN` ``
+citing the file named last) names lines inside a file of audiodsp at the
+commit in `AUDIODSP_PIN`, or of this repository. The pinned audiodsp is
+read from a checkout (`KIT_AUDIODSP`, or an `audiodsp` directory beside
+this repository or a parent), never changed; with no checkout, or without
+the pinned commit in it, an audiodsp citation prints `na(...)`. Line
+numbers are all it can know: a citation whose lines moved still resolves.
+
+## Options
+
+`kit_options.py` holds `KIT_OPTIONS`, the constructor options the kit
+builds a class with, by `NAME`; every other class is built at its defaults.
+It is for a class whose defaults are trivial, such as the generic `Rack`,
+whose default chain is empty.
+
+## Declaring an exception
+
+A class that cannot meet a cell by design adds a row to `DECLARED` in
+`kit_common.py`:
+
+    DECLARED = {
+        ("TapeDelay", "ceiling", "sine/"): "the tape saturates by design",
+    }
+
+The key is (class `NAME`, check, cell key prefix); a matching red cell
+prints `decl` and counts as declared. Nothing else skips a cell.
+
+## The plants
+
+`tests/test_kit.py` holds every check red on a planted fault and its
+control green on the same cell, with the plants in `kit_planted.py`
+(a Waveshaper and a level around the source; `KitPlain` is the control):
+`ShortTail` and `EventTail` (tail; `EchoTail` the control), `NoneSilent`
+and `NoneDC` (a None tail), `Inert`, `KnobReach` and `SoftOnly` (plants),
+a fixture test module with a missing sentence, a missing test, a failing
+and a skipped test and a loose claim (claims), `ReadbackOff`,
+`StopRaises`, `NanLevel`, `PatchStale` and `CtorNan` (args), `WrapKit`,
+`ClipKit` and `DeadStop` (ceiling), a missing CHANGELOG line and citations
+past the end of a file or to no file (paperwork), and `Silent`, which does
+nothing. Its native half holds the render checks to the same lines on all
+three interpreters, and shows that agreement can fail with `ImplKit`,
+whose level differs off CPython.
diff --git a/tests/support/kit_ceiling.py b/tests/support/kit_ceiling.py
index 1b2ccd2..d917d67 100644
--- a/tests/support/kit_ceiling.py
+++ b/tests/support/kit_ceiling.py
@@ -16,11 +16,13 @@
 **The bars**, each its own clause in a RED verdict:
 
 - `wrap`: two neighbouring samples of opposite sign more than 32768 apart,
-  with the signal running the same way on both sides of the jump (into it
-  before, out of it after), as an int16 sum that overflowed runs, and the
-  input, `latency_samples` earlier, made no such jump. A square's edge
-  is flat on both sides, so it is not one. Not judged on the noise, whose
-  jumps run every way.
+  where the second, moved by 65536, lands within a quarter of the jump of
+  the first, and the signal runs the same way on both sides of the jump
+  (into it before, out of it after): an int16 sum that overflowed, and
+  the input, `latency_samples` earlier, made no such jump. A square's edge
+  is flat on both sides and a click's return lands far from its peak, so
+  neither is one. Not judged on the noise, whose jumps run every way. A
+  flat signal that wraps (a square at twice full scale) is not caught.
 - `rail`: more than 8 frames in a row on a rail (|y| >= 32767) where the
   input, `latency_samples` earlier, was not.
 - `silent`: the last second exactly zero while the input played through
@@ -87,6 +89,10 @@ def wrap_at(out, values, channels, lat):
             jump = b - a
             if jump < WRAP_JUMP and -jump < WRAP_JUMP:
                 continue
+            # Unwrapped, b lands next to a: within a quarter of the jump.
+            near = b + 65536 if jump < 0 else b - 65536
+            if 4 * abs(near - a) > abs(jump):
+                continue
             before = a - out[(f - 2) * channels + ch]
             after = out[(f + 1) * channels + ch] - b
             if jump < 0 and not (before > 0 and after > 0):
diff --git a/tests/test_kit.py b/tests/test_kit.py
new file mode 100644
index 0000000..2946a50
--- /dev/null
+++ b/tests/test_kit.py
@@ -0,0 +1,443 @@
+"""The effects kit's own proof: every check goes red on a planted fault and
+its control is green on the same cell, and a class that does nothing at
+all is never read as a pass.
+
+The plants are the tiny components in `tests/support/kit_planted.py`;
+`KIT.md` beside the kit says what each check measures. The native half
+runs the kit's render checks under MicroPython and CircuitPython and holds
+them to CPython's lines, and shows that a plant whose output depends on
+the interpreter is caught; it skips when a binary is missing.
+
+    OMP_NUM_THREADS=1 python -m unittest tests.test_kit
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+import textwrap
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(ROOT, "lib"))
+sys.path.insert(0, os.path.join(ROOT, "tests", "support"))
+
+import kit_args                                           # noqa: E402
+import kit_ceiling                                        # noqa: E402
+import kit_claims                                         # noqa: E402
+import kit_common as kc                                   # noqa: E402
+import kit_paperwork                                      # noqa: E402
+import kit_planted as kp                                  # noqa: E402
+import kit_plants                                         # noqa: E402
+import kit_tail                                           # noqa: E402
+import lifecycle                                          # noqa: E402
+
+#: `_component` reads VENDOR off the module a class is defined in.
+VENDOR = "PyDevices"
+
+
+def cells_of(fn, *args, **kw):
+    lines = []
+    fn(*args, emit=lines.append, **kw)
+    return kc.parse(lines)
+
+
+def verdict(cells, name, check, key):
+    return cells[(name, check, key)]["V"]
+
+
+def tail_cell(cls, key="fs/48000/2/d/none", **kw):
+    """One tail cell (material/rate/channels/patch/event)."""
+    which, rate, ch, patch, event = key.split("/")[:5]
+    cells = cells_of(kit_tail.run, cls, rates=(int(rate),),
+                     channels=(int(ch),),
+                     patches=[None if patch == "d" else int(patch[1:])],
+                     materials=(which,), events=(event,), quick=True, **kw)
+    return verdict(cells, cls.NAME, "tail", key)
+
+
+def red(v):
+    return v.startswith("RED")
+
+
+class TestTail(unittest.TestCase):
+
+    def test_a_short_tail_is_red_and_a_true_one_green(self):
+        for key in ("fs/48000/2/d/none", "lsb3/22050/1/d/none",
+                    "dc/48000/1/d/none"):
+            with self.subTest(key=key):
+                self.assertTrue(red(tail_cell(kp.ShortTail, key)))
+                self.assertEqual(tail_cell(kp.EchoTail, key), "ok")
+
+    def test_the_tail_is_read_after_every_event(self):
+        # EventTail tells the truth until a control moves.
+        self.assertEqual(tail_cell(kp.EventTail, "fs/48000/2/d/none"), "ok")
+        for event in ("E4-m1=127", "E5-mix0", "E6-p1"):
+            key = "fs/48000/2/d/" + event
+            with self.subTest(event=event):
+                self.assertTrue(red(tail_cell(kp.EventTail, key)))
+                self.assertEqual(tail_cell(kp.EchoTail, key), "ok")
+
+    def test_the_events_are_lifecycles(self):
+        names = [n for n, _ev, _p in kit_tail.tail_events(kp.KitPlain, None,
+                                                         False)]
+        for ev in lifecycle.events(kp.KitPlain, None):
+            if lifecycle._starts(ev.name, kit_tail.EVENT_PREFIXES):
+                self.assertIn(ev.name, names)
+        self.assertIn("none", names)
+
+    def test_tail_none_must_never_fall_silent(self):
+        self.assertTrue(tail_cell(kp.NoneSilent).startswith(
+            "RED(tail None, silent"))
+        self.assertEqual(tail_cell(kp.NoneDC), "na(tail None)")
+
+    def test_a_silent_class_is_not_a_pass(self):
+        self.assertEqual(tail_cell(kp.Silent), "na(silent)")
+
+    def test_a_declared_cell_prints_decl(self):
+        kc.DECLARED[("ShortTail", "tail", "fs/48000")] = "planted"
+        try:
+            self.assertEqual(tail_cell(kp.ShortTail), "decl")
+        finally:
+            del kc.DECLARED[("ShortTail", "tail", "fs/48000")]
+
+
+class TestPlants(unittest.TestCase):
+
+    def setUp(self):
+        self.cells = cells_of(kit_plants.run, kp.KitPlain,
+                              plants=kp.KIT_PLANTS)
+
+    def v(self, key):
+        return verdict(self.cells, "KitPlain", "plants", key)
+
+    def test_an_inert_plant_is_red(self):
+        self.assertEqual(self.v("inert/48000/2/d"),
+                         "RED(same as clean at the defaults)")
+
+    def test_a_plant_a_knob_reaches_is_red(self):
+        self.assertEqual(self.v("knob/48000/2/d"),
+                         "RED(reproduced by m1=0)")
+
+    def test_a_real_plant_is_green(self):
+        self.assertEqual(self.v("valid/48000/2/d"), "ok")
+
+    def test_a_plant_judged_at_its_patch(self):
+        # The same plant: invisible at the defaults, a fault at patch 1.
+        self.assertEqual(self.v("soft-at-d/48000/2/d"),
+                         "RED(same as clean at the defaults)")
+        self.assertEqual(self.v("soft/48000/2/p1"), "ok")
+
+    def test_a_patch_reproducing_a_plant_is_red(self):
+        class AtSoft(kp.KitPlain):
+            def _build(self, mix=1.0, gain=1.0, patch=None):
+                kp.KitPlain._build(self, mix, gain, 1)
+        cells = cells_of(kit_plants.run, kp.KitPlain,
+                         plants={"soft": AtSoft})
+        self.assertEqual(verdict(cells, "KitPlain", "plants",
+                                 "soft/48000/2/d"),
+                         "RED(reproduced by patch 1)")
+
+    def test_a_missing_table_says_so(self):
+        cells = cells_of(kit_plants.run, kp.KitPlain, module="kit_common")
+        self.assertTrue(verdict(cells, "KitPlain", "plants", "-")
+                        .startswith("na(kit_common has no KIT_PLANTS"))
+
+
+class TestArgs(unittest.TestCase):
+
+    CASES = (
+        (kp.ReadbackOff, "rt-m1/48000/d", kit_args.roundtrip,
+         (1, 48000, None)),
+        (kp.StopRaises, "stops-m1", kit_args.stops_cell, (1,)),
+        (kp.NanLevel, "bad-m1", kit_args.bad_cell, (1,)),
+        (kp.PatchStale, "patch-p1", kit_args.patch_cell, (1,)),
+        (kp.CtorNan, "ctor-gain", kit_args.ctor_cell, ("gain",)),
+    )
+
+    @staticmethod
+    def call(fn, cls, args):
+        got = fn(cls, *args)
+        return got[0] if isinstance(got, tuple) else got
+
+    def test_each_plant_is_red_and_the_control_green(self):
+        for plant, key, fn, args in self.CASES:
+            with self.subTest(cell=key):
+                self.assertTrue(red(self.call(fn, plant, args)), plant.NAME)
+                self.assertTrue(self.call(fn, kp.KitPlain, args)
+                                .startswith("ok"), key)
+
+    def test_a_clamp_is_read_as_one(self):
+        self.assertEqual(kit_args.bad_cell(kp.KitPlain, 1),
+                         "ok(nan:c inf:c -inf:c -1:c 128:c)")
+
+    def test_a_silent_class_is_not_a_pass(self):
+        self.assertEqual(kit_args.roundtrip(kp.Silent, 1, 48000, None)[0],
+                         "na(silent)")
+
+    def test_the_options_are_read_from_the_source(self):
+        self.assertEqual(kit_args.options_of(kp.KitPlain),
+                         [("mix", 1.0), ("gain", 1.0)])
+        self.assertEqual(kit_args.options_of(kp.CtorNan),
+                         [("mix", 1.0), ("gain", 1.0)])
+
+
+class TestCeiling(unittest.TestCase):
+
+    def v(self, cls, which="sine", patch=None, knob=None):
+        return kit_ceiling.measure(cls, 48000, 2, which, patch, knob)[0]
+
+    def test_a_wrap_is_red(self):
+        self.assertTrue(self.v(kp.WrapKit).startswith("RED(wrap"))
+        self.assertEqual(self.v(kp.KitPlain), "ok")
+
+    def test_the_stated_level_is_the_one_rendered(self):
+        self.assertEqual(kit_ceiling.peak(kp.WrapKitQuiet), 14636)
+        self.assertEqual(self.v(kp.WrapKitQuiet), "ok")
+
+    def test_a_click_is_not_a_wrap(self):
+        # A full-scale click, then the repeat starting: a jump of 34817
+        # with the signal falling on both sides, which a delay plays.
+        click = [0, 0, 0, -32767, 2050, 1661, 77, 0]
+        self.assertIsNone(kit_ceiling.wrap_at(click, [0] * 8, 1, 0))
+        wrapped = [32000, 32400, 32760, -32760, -32400, -32000]
+        self.assertEqual(kit_ceiling.wrap_at(wrapped, [0] * 6, 1, 0),
+                         (3, 0))
+
+    def test_a_rail_is_red(self):
+        self.assertTrue(self.v(kp.ClipKit).startswith("RED(rail"))
+        # A square at full scale sits on the rail because the input does.
+        self.assertEqual(self.v(kp.KitPlain, "square"), "ok")
+
+    def test_silence_at_a_stop_is_red(self):
+        self.assertTrue(self.v(kp.DeadStop, knob=(1, 0)).startswith(
+            "RED(silent"))
+        self.assertEqual(self.v(kp.KitPlain, knob=(1, 0)), "ok")
+        self.assertEqual(self.v(kp.DeadStop), "ok")
+
+    def test_a_silent_class_is_red(self):
+        self.assertTrue(self.v(kp.Silent).startswith("RED(silent"))
+
+
+FIXTURE_TESTS = '''
+import unittest
+
+CLAIMS = %s
+
+
+class Things(unittest.TestCase):
+    def test_passes(self):
+        pass
+
+    def test_fails(self):
+        self.fail("planted")
+
+    @unittest.skip("planted")
+    def test_skipped(self):
+        pass
+'''
+
+
+class TestClaims(unittest.TestCase):
+
+    DOC = ("A plain wire. **Controls.** Gain sets the level. The output is "
+           "the input at Gain 1.")
+
+    def run_claims(self, claims, doc=None):
+        with tempfile.TemporaryDirectory() as scratch:
+            name = "kitfixture_%d" % abs(hash((repr(claims), doc)))
+            path = os.path.join(scratch, name + ".py")
+            with open(path, "w") as f:
+                f.write(textwrap.dedent(FIXTURE_TESTS % repr(claims)))
+            sys.path.insert(0, scratch)
+            try:
+                module = __import__(name)
+                lines = []
+                kit_claims.check("Fixture", self.DOC if doc is None else doc,
+                                 module, path, lines.append)
+            finally:
+                sys.path.remove(scratch)
+                sys.modules.pop(name, None)
+        cells = kc.parse(lines)
+        return dict((k[2], v["V"]) for k, v in cells.items())
+
+    def test_the_control_is_green(self):
+        got = self.run_claims((("The output is the input at Gain 1.",
+                                "test_passes"),))
+        self.assertEqual(got, {"table": "ok", "row0": "ok"})
+
+    def test_each_fault_is_red(self):
+        cases = (
+            ("not in the docstring", (("The output is twice the input.",
+                                       "test_passes"),)),
+            ("no test test_absent", (("The output is the input at Gain 1.",
+                                      "test_absent"),)),
+            ("Things.test_fails fails", ((
+                "The output is the input at Gain 1.", "test_fails"),)),
+            ("Things.test_skipped skipped", ((
+                "The output is the input at Gain 1.",
+                ("test_passes", "Things.test_skipped")),)),
+            ("no lifecycle row", (("The output is the input at Gain 1.",
+                                   "DECLARED:Fixture,E1-,P4"),)),
+        )
+        for why, claims in cases:
+            with self.subTest(why=why):
+                got = self.run_claims(claims)
+                self.assertIn(why, got["row0"])
+
+    def test_a_declared_row_counts(self):
+        key = next(iter(lifecycle.DECLARED))
+        got = self.run_claims((("The output is the input at Gain 1.",
+                                "DECLARED:%s,%s,%s" % key),))
+        self.assertEqual(got["row0"], "ok")
+
+    def test_a_claim_with_no_row_is_red(self):
+        got = self.run_claims((), self.DOC + " It never clips.")
+        self.assertEqual(sorted(got), ["loose0", "loose1", "table"])
+        self.assertIn("at Gain 1", got["loose0"])
+        self.assertIn("never clips", got["loose1"])
+
+    def test_no_table_and_no_docstring(self):
+        lines = []
+        kit_claims.check("Fixture", self.DOC, None, None, lines.append)
+        self.assertTrue(lines[0].endswith("V:RED(no CLAIMS table in the "
+                                          "test module)"))
+        lines = []
+        kit_claims.check("Fixture", None, None, None, lines.append)
+        self.assertTrue(lines[0].endswith("V:RED(no docstring)"))
+
+    def test_the_claim_rule(self):
+        for sentence in ("Time runs to 800 ms.", "It never clips.",
+                         "Mix is at most unity.", "Two heads play."):
+            self.assertTrue(kit_claims.is_claim(sentence), sentence)
+        for sentence in ("Gain sets the level.", "The repeats get darker."):
+            self.assertFalse(kit_claims.is_claim(sentence), sentence)
+
+
+class TestPaperwork(unittest.TestCase):
+
+    CHANGELOG = "## Unreleased\n\n- **`KitPlain` (rebuilt):** a wire.\n"
+
+    def cells(self, text, pin, changelog=None):
+        lines = []
+        kit_paperwork.check("KitPlain", text, changelog or self.CHANGELOG,
+                            pin, lines.append)
+        return dict((k[2], v["V"]) for k, v in kc.parse(lines).items())
+
+    def test_the_changelog_line(self):
+        pin = kit_paperwork.Pin(None, None)
+        self.assertEqual(self.cells("", pin)["changelog"], "ok")
+        self.assertTrue(red(self.cells("", pin, "- **`Other`**")
+                            ["changelog"]))
+
+    def test_citations_against_the_pin(self):
+        pin = kit_paperwork.Pin(kit_paperwork.find_checkout(),
+                                kit_paperwork.pin_commit())
+        if pin.files is None:
+            self.skipTest("audiodsp at the pin: %s" % pin.why)
+        got = self.cells("see `audiodsp_feedback_delay.c:157`, `:99999` "
+                         "and nosuchfile.c:3", pin)
+        self.assertEqual(got["cite:audiodsp_feedback_delay.c:157"], "ok")
+        self.assertTrue(red(got["cite:audiodsp_feedback_delay.c:99999"]))
+        self.assertTrue(red(got["cite:nosuchfile.c:3"]))
+
+    def test_citations_to_this_repository(self):
+        pin = kit_paperwork.Pin(None, None)
+        got = self.cells("(`_component.py:10`, `_component.py:999999`, "
+                         "`audiodsp_tank.c:1`)", pin)
+        self.assertEqual(got["cite:_component.py:10"], "ok")
+        self.assertTrue(red(got["cite:_component.py:999999"]))
+        self.assertEqual(got["cite:audiodsp_tank.c:1"],
+                         "na(no audiodsp checkout)")
+
+    def test_the_citation_forms(self):
+        found = kit_paperwork.citations(
+            "`src/shared/a.c:344`, called at :529 (`b.h:3-5`, `:7`); "
+            "a ratio 3:2 and x[:10] are not citations")
+        self.assertEqual(found, [("src/shared/a.c", 344, 344),
+                                 ("src/shared/a.c", 529, 529),
+                                 ("b.h", 3, 5), ("b.h", 7, 7)])
+
+
+# --------------------------------------------------------------------------
+# The native half
+
+
+def native_binaries():
+    """{"micropython": path or None, "circuitpython": path or None}: the
+    LIFECYCLE_MICROPYTHON / LIFECYCLE_CIRCUITPYTHON binaries, or the
+    workspace's `bin/`."""
+    found = {}
+    here = ROOT
+    bindir = None
+    for _up in range(5):
+        here = os.path.dirname(here)
+        if os.path.isfile(os.path.join(here, "bin", "micropython")):
+            bindir = os.path.join(here, "bin")
+            break
+    for family in ("micropython", "circuitpython"):
+        path = os.environ.get("LIFECYCLE_" + family.upper())
+        if path is None and bindir is not None:
+            path = os.path.join(bindir, family)
+        found[family] = path if path and os.path.isfile(path) else None
+    return found
+
+
+def run_kit(binary, args):
+    with tempfile.TemporaryDirectory() as scratch:
+        env = dict(os.environ, MICROPYPATH="lib:tests/support",
+                   GCOV_PREFIX=scratch, PYTHONDONTWRITEBYTECODE="1",
+                   OMP_NUM_THREADS="1")
+        cmd = [binary]
+        if binary != sys.executable:
+            cmd += ["-X", "heapsize=256M"]
+        done = subprocess.run(cmd + ["tests/support/kit.py"] + args,
+                              capture_output=True, text=True, cwd=ROOT,
+                              env=env)
+    lines = done.stdout.splitlines()
+    if done.returncode != 0 or not lines or lines[-1] != "DONE":
+        raise AssertionError("%s: %s%s" % (binary, done.stdout[-1500:],
+                                           done.stderr[-1500:]))
+    return lines
+
+
+RENDER = ["--quick", "--plants-module=kit_planted",
+          "--only=args,plants,ceiling,tail"]
+
+
+class TestNative(unittest.TestCase):
+    """The render checks print the same lines on all three interpreters,
+    and that agreement can fail."""
+
+    def binary(self, family):
+        path = native_binaries()[family]
+        if path is None:
+            self.skipTest("no %s binary: set LIFECYCLE_%s" % (
+                family, family.upper()))
+        return path
+
+    def agree(self, family):
+        theirs = run_kit(self.binary(family), ["KitPlain", "EventTail"]
+                         + RENDER)
+        ours = run_kit(sys.executable, ["KitPlain", "EventTail"] + RENDER)
+        self.assertEqual(ours, theirs)
+
+    def test_micropython_agrees(self):
+        self.agree("micropython")
+
+    def test_circuitpython_agrees(self):
+        self.agree("circuitpython")
+
+    def test_agreement_can_fail(self):
+        binary = self.binary("micropython")
+        args = ["ImplKit", "--only=args", "--quick"]
+        ours = kc.parse(run_kit(sys.executable, args))
+        theirs = kc.parse(run_kit(binary, args))
+        self.assertNotEqual(ours, theirs)
+        # Every verdict is the same; the bytes are not.
+        self.assertEqual(dict((k, v["V"]) for k, v in ours.items()),
+                         dict((k, v["V"]) for k, v in theirs.items()))
+
+
+if __name__ == "__main__":
+    unittest.main()

From f8e1f5b5f06f9dac60cd17a0464406bf90f90f95 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:50:45 -0500
Subject: [PATCH 05/76] Kit: read sources as UTF-8 on every platform

---
 tests/support/kit_args.py      | 4 ++--
 tests/support/kit_claims.py    | 2 +-
 tests/support/kit_paperwork.py | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/support/kit_args.py b/tests/support/kit_args.py
index 41ae01e..1df533f 100644
--- a/tests/support/kit_args.py
+++ b/tests/support/kit_args.py
@@ -239,8 +239,8 @@ def options_of(cls):
     if owner is None:
         return []
     module = sys.modules[owner.__module__]
-    with open(module.__file__) as f:
-        text = f.read()
+    with open(module.__file__, "rb") as f:
+        text = f.read().decode("utf-8")
     at = text.find("class %s(" % owner.__name__)
     at = text.find("def _build(", at if at >= 0 else 0)
     if at < 0:
diff --git a/tests/support/kit_claims.py b/tests/support/kit_claims.py
index 4e37c23..64de191 100644
--- a/tests/support/kit_claims.py
+++ b/tests/support/kit_claims.py
@@ -94,7 +94,7 @@ def sentences(text):
 
 def test_index(path):
     """{method name: [TestCase class names]} by an AST read of `path`."""
-    with open(path) as f:
+    with open(path, encoding="utf-8") as f:
         tree = ast.parse(f.read(), path)
     index = {}
     for node in tree.body:
diff --git a/tests/support/kit_paperwork.py b/tests/support/kit_paperwork.py
index 4d9c4ff..eef7f69 100644
--- a/tests/support/kit_paperwork.py
+++ b/tests/support/kit_paperwork.py
@@ -51,7 +51,7 @@ def pin_commit(root=ROOT):
     if not os.path.isfile(path):
         return None
     commit = None
-    with open(path) as f:
+    with open(path, encoding="utf-8") as f:
         for line in f:
             line = line.strip()
             if line and not line.startswith("#"):
@@ -199,9 +199,9 @@ def check(name, text, changelog_text, pin, emit=print, root=ROOT):
 
 def run(cls, emit=print, name=None, **_):
     module = sys.modules[cls.__module__]
-    with open(module.__file__) as f:
+    with open(module.__file__, encoding="utf-8") as f:
         text = f.read()
-    with open(os.path.join(ROOT, "CHANGELOG.md")) as f:
+    with open(os.path.join(ROOT, "CHANGELOG.md"), encoding="utf-8") as f:
         changelog = f.read()
     pin = Pin(find_checkout(), pin_commit())
     return check(name or cls.NAME, text, changelog, pin, emit)

From 3cb10753cc007fee270e2df2a61bcf78ab871645 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 22:51:16 -0500
Subject: [PATCH 06/76] Node matrix: the comparator and all-pass the Octaver
 stands on

---
 tests/support/node_matrix.py | 61 +++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
index 879b0b4..9335df0 100644
--- a/tests/support/node_matrix.py
+++ b/tests/support/node_matrix.py
@@ -348,10 +348,69 @@ def _apply_macro(self, index, position):
             self._node.decay = decay
 
 
+class NodeComparator(_Node):
+    """`audioshaper.Waveshaper` with a step curve: the Octaver's comparator
+    ahead of its divider."""
+    NAME = "NodeComparator"
+    REQUIRES = ("audioshaper",)
+    MACRO_LABELS = ("Mix", "Drive")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (1.0, 8.0))
+    PATCHES = {0: ("Square", (127, 0)), 1: ("Driven, half", (64, 127))}
+    _TAIL_S = 0.01
+
+    def _build(self, mix=1.0, drive=1.0, patch=None):
+        from array import array
+        import audioshaper
+        half = 128
+        curve = array("h", [-16000] * half + [0] + [16000] * half)
+        self._node = self._register(audioshaper.Waveshaper(
+            sample_rate=self._sample_rate, curve=curve, oversample=1,
+            channel_count=self._channel_count, mix=mix, pre_gain=drive))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, drive), patch)
+
+    def _apply_macro(self, index, position):
+        mix, drive = self._values()
+        if index == 0:
+            self._node.set(mix=mix)
+        else:
+            self._node.set(pre_gain=drive)
+
+
+class NodeAllPass(_Node):
+    """`audiobiquad.AllPass`, two stages: the Octaver's signal-path phase
+    match."""
+    NAME = "NodeAllPass"
+    REQUIRES = ("audiobiquad",)
+    MACRO_LABELS = ("Mix", "Frequency")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (60.0, 4000.0, "log"))
+    PATCHES = {0: ("Low", (127, 30)), 1: ("High, half", (64, 110))}
+    _TAIL_S = 0.1
+
+    def _build(self, mix=1.0, frequency=300.0, patch=None):
+        self._node = self._register(audiobiquad.AllPass(
+            stages=2, frequency=frequency, mix=mix,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._node.play(self._source)
+        self._output = self._node
+        self._init_macros((mix, frequency), patch)
+
+    def _apply_macro(self, index, position):
+        mix, frequency = self._values()
+        if index == 0:
+            self._node.mix = mix
+        else:
+            self._node.frequency = self._hz(frequency)
+
+
 NODES = {}
 for _cls in (NodePitchShift, NodeGranularPitchShift, NodeShimmerLoop,
              NodeSubOctave, NodeSquare, NodeMidSide, NodeSplitMix,
-             NodeBiquad, NodeEcho):
+             NodeBiquad, NodeEcho, NodeComparator, NodeAllPass):
     NODES[_cls.NAME] = _cls
 
 

From 626b7e6ba9c5d73d14b934825a2f41e1cb2f7805 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:05:41 -0500
Subject: [PATCH 07/76] Node matrix: the shimmer loop's and Echo's by-design
 cells

---
 tests/support/node_matrix.py | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
index 9335df0..58c85b8 100644
--- a/tests/support/node_matrix.py
+++ b/tests/support/node_matrix.py
@@ -427,6 +427,24 @@ def _apply_macro(self, index, position):
         " never-reset one and flip one LSB now and then for good",
     ("NodeBiquad", "E6-", "P4"):
         "as E2: one ulp of filter state after a move and back",
+    ("NodeShimmerLoop", "E1-", "P4"):
+        "clear() restarts the loop shifter's crossfade phase, so the node is"
+        " never in phase with one that was never cleared",
+    ("NodeShimmerLoop", "E2-", "P4"):
+        "as E1: the host reset restarts the loop shifter's phase",
+    ("NodeShimmerLoop", "E4-", "P4"):
+        "a Semitones move runs the free-running shifter phase at another rate",
+    ("NodeShimmerLoop", "E6-", "P4"):
+        "a patch with other semitones moves the free-running shifter phase",
+    ("NodeShimmerLoop", "E11-", "P4"):
+        "moves of Semitones before a pull move the shifter phase",
+    ("NodeEcho", "E4-m0", "P3"):
+        "upstream's Echo holds its line still at mix 0 and plays it when mix"
+        " comes back; a class routes around and rejoins clean",
+    ("NodeEcho", "E5-", "P3"):
+        "as E4: the line held at mix 0 plays when mix comes back",
+    ("NodeEcho", "E9-", "P3"):
+        "as E4, at every source buffer size",
 }
 
 import lifecycle  # noqa: E402

From 40ec61a1ec7a8f9ff88321f6e62c258e1b9eb935 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:08:43 -0500
Subject: [PATCH 08/76] StereoWidener (rebuilt, Phase 6): Haas and Mid/Side on
 Width, Delay and Character

Haas crossfades the right channel toward a copy of itself 1 to 40 ms late
and turns the left down above Width 1; Mid/Side scales the difference
between the channels on audioroute.MidSide. A mono source is a wire, a
Delay move glides, and the six traits each have a test shown red on a
planted fault (KIT_PLANTS), with every docstring claim in CLAIMS. The
lifecycle matrix declares the family's control-jump step and one glide
cell; the kit declares the slew plant, which only a moving control shows.
---
 CHANGELOG.md                                |    7 +
 lib/audioeffects/rebuilt/stereowidener.py   |  366 +++++++
 tests/support/kit_common.py                 |    4 +
 tests/support/lifecycle.py                  |   19 +
 tests/test_cpython_effects_stereowidener.py | 1021 +++++++++++++++++++
 5 files changed, 1417 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/stereowidener.py
 create mode 100644 tests/test_cpython_effects_stereowidener.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..f010a30 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`StereoWidener` (rebuilt, Phase 6):** two characters on a Width, Delay
+  and Character surface. Haas delays the right channel 1 to 40 ms behind the
+  left, crossfading the right toward its late copy up to Width 1 and turning
+  the left down above it; Mid/Side scales the difference between the
+  channels and leaves the sum alone. A mono source passes untouched, and a
+  Delay move glides instead of clicking. The old `delay_ms=`/`width=`
+  options keep their names with these meanings.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/stereowidener.py b/lib/audioeffects/rebuilt/stereowidener.py
new file mode 100644
index 0000000..5760787
--- /dev/null
+++ b/lib/audioeffects/rebuilt/stereowidener.py
@@ -0,0 +1,366 @@
+"""`StereoWidener` - a stereo widener with Haas and Mid/Side characters.
+
+The player's text is the class docstring; the `CLAIMS` table in the class's
+test file ties its claim sentences to tests.
+"""
+
+VENDOR = "PyDevices"
+
+from array import array
+
+import audiocore
+
+from .. import _component
+
+try:
+    from .digitaldelay import whole_frames
+except ImportError:                     # pragma: no cover - after it lands
+    from ..digitaldelay import whole_frames
+
+try:
+    import audioecho
+    import audiomixer
+    import audioroute
+except ImportError:                     # pragma: no cover - a stock board
+    audioecho = audiomixer = audioroute = None
+
+
+#: The Delay span, in ms, swept by ratio.
+DELAY_MIN_MS = 1.0
+DELAY_MAX_MS = 40.0
+
+#: The line: Delay's top plus 1 ms, so the node never clamps the read.
+LINE_MS = DELAY_MAX_MS + 1.0
+
+#: How fast a Delay move walks the read head, in delay-seconds per second:
+#: 3/16, exact in every float format, a pitch bend of x1.1875 while it moves.
+SLEW = 0.1875
+
+#: The hardest a Mixer voice pans: the right (or left) scale is then exactly
+#: 0, where a panning of -1 or +1 leaves one LSB of it.
+HARD = 32767.0 / 32768.0
+
+#: The frames a mixer pull hands out, and so the frames each voice and each
+#: Splitter tap take per pull.
+BLOCK = 256
+
+#: How close, as a 0..1 knob position, Delay must sit to the grid step the
+#: constructor's `delay_ms` seeded for that exact value to play: 1e-6 is
+#: 1/7 874 of one MIDI step, and holds a single-precision round trip.
+ECHO_TOLERANCE = 1e-6
+
+WIDTH_I, DELAY_I, CHARACTER_I = range(3)
+
+CHARACTERS = ("haas", "mid_side")
+
+#: The constructor defaults, which NaN falls back to.
+DEFAULT_WIDTH = 1.0
+DEFAULT_DELAY_MS = 14.0
+
+
+def _option(value, default):
+    """A constructor option as a float; NaN is the option's default."""
+    value = float(value)
+    if value != value:
+        return default
+    return value
+
+
+def _between(value, low, high):
+    if value < low:
+        return low
+    if value > high:
+        return high
+    return value
+
+
+def haas_voices(width):
+    """((lead level, lead panning), (copy level, copy panning)) for a Haas
+    Width: up to 1 the lead keeps the left at unity and turns its right down
+    by the Width while the copy comes up in the right; above 1 the copy
+    stays at unity and the lead turns down to 1/Width."""
+    if width <= 1.0:
+        return (1.0, -min(width, HARD)), (width, HARD)
+    return (1.0 / width, -HARD), (1.0, HARD)
+
+
+class StereoWidener(_component.Component):
+    """Widen a stereo part: Haas delays the right channel a few milliseconds
+    behind the left, and Mid/Side scales the difference between the channels.
+
+    **The controls.** Width runs from 0 to 2, with its centre detent at 1.
+    Delay runs from 1 to 40 ms, and only Haas uses it.
+    Character picks Haas or Mid/Side.
+
+    **Haas.** The ear places a sound by the first arrival and hears the late
+    copy as width.
+    At Width 1 the left channel passes untouched and the right channel is
+    your right channel, exactly Delay late.
+    Between Width 0 and 1 the right channel crossfades from itself to its
+    late copy, which colours it most at 0.5.
+    Width 0 is a wire.
+    Above Width 1 the copy stays where it is and the left turns down, 6 dB
+    at Width 2, to pull back the image the left's early arrival leans its
+    way.
+    Turning Delay glides the copy to the new time instead of clicking,
+    bending its pitch while it moves.
+    Haas folds to mono as a comb filter: at Width 1 with the default 14 ms,
+    the mono sum has full-depth notches at 35.7, 107 and 179 Hz and on up.
+    Use Mid/Side when the mix may be summed.
+
+    **Mid/Side.** Summed to mono, the output is the same at every Width,
+    within one LSB.
+    Width 0 is mono, 1 is a wire and 2 doubles the sides.
+    Above Width 1, a part panned hard left shows up inverted on the right.
+    A part that is the same in both channels comes out unchanged.
+    Peaks up to half of full scale never clip at any Width.
+
+    **Mono, latency, tail.** A one-channel source comes out exactly as it
+    went in, whatever the controls say.
+    To widen a mono part, make it stereo first (a stereo chorus, say) and
+    put this after it.
+    A click in the left comes out on the frame it went in: there is no
+    latency.
+    `tail_samples` is the copy's reach in Haas, and 0 in Mid/Side or at
+    Width 0.
+    `reset()` empties the line and returns to patch 0.
+    The class never reads the host's tempo.
+
+    **Limits shared by the family.**
+    A control that jumps, Width or Character, makes the output step: move it
+    in small steps from the host if you need it smooth.
+    """
+
+    NAME = 'StereoWidener'
+    DISPLAY_NAME = 'Stereo Widener'
+    CATEGORIES = ('Spatial',)
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioecho", "audioroute")
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    TAIL_SAMPLES = None
+
+    #: Half of full scale, rounded down a step: Mid/Side at Width 2 doubles
+    #: an anti-phase pair's side, and 2 x 16 383 still fits.
+    INPUT_CEILING_DBFS = -6.03
+
+    MACRO_LABELS = ("Width", "Delay", "Character")
+    MACRO_MODES = {
+        0: "BIPOLAR",
+        1: "UNIPOLAR",
+        2: "TOGGLE",
+    }
+    _MACRO_RANGES = (
+        (0.0, 2.0),                               # 0  Width; MIDI 64 is 1.0
+        (DELAY_MIN_MS, DELAY_MAX_MS, "log"),      # 1  Delay, ms
+        (0.0, 1.0),                               # 2  Character
+    )
+
+    #: `_component.macro_of` of the card's patch settings.
+    PATCHES = {
+        0: ("Haas 14 ms", (64, 91, 0)),
+        1: ("Haas Tight", (64, 62, 0)),
+        2: ("Haas Wide", (64, 111, 0)),
+        3: ("Haas Recentred", (96, 91, 0)),
+        4: ("Mid/Side Wide", (96, 91, 127)),
+        5: ("Mid/Side Narrow", (32, 91, 127)),
+        6: ("Mono", (0, 91, 127)),
+    }
+
+    def _build(self, width=DEFAULT_WIDTH, delay_ms=DEFAULT_DELAY_MS,
+               character="haas", patch=None):
+        if character not in CHARACTERS:
+            raise ValueError("character must be %r or %r, not %r"
+                             % (CHARACTERS[0], CHARACTERS[1], character))
+        width = _between(_option(width, DEFAULT_WIDTH), 0.0, 2.0)
+        delay_ms = _between(_option(delay_ms, DEFAULT_DELAY_MS),
+                            DELAY_MIN_MS, DELAY_MAX_MS)
+        #: The constructor's Delay, exactly, and the grid step it seeds.
+        #: That exact value plays whenever Delay sits on that step, so a
+        #: fresh instance, its patch 0 and a host echoing `get_macro(1)` all
+        #: play 14.0 ms, not the step's 14.06.
+        self._delay_exact = delay_ms
+        span = self._MACRO_RANGES[DELAY_I]
+        self._delay_seed = _component.position_of_midi(
+            "UNIPOLAR", _component.macro_of(span, delay_ms))
+        self._frames = 1
+        #: The longest delay, in frames, the read head may still sit at: a
+        #: falling move walks the head down, so the old Delay holds until
+        #: the line is next emptied. None while the line is empty and no
+        #: Delay has been set since: an emptied line snaps onto its Delay.
+        self._reach = None
+        self._wired = False
+        self._ready = False
+        self._ms = None
+        if self._channel_count == 2:
+            self._build_graph()
+        else:
+            # One channel has no width to work on: the output is the source.
+            self._output = self._source
+        values = (width, delay_ms,
+                  1.0 if character == CHARACTERS[1] else 0.0)
+        self._init_macros(values)
+        self._macros[DELAY_I] = self._delay_seed
+        self._ready = True
+        self._refresh()
+        if patch is not None:
+            self.program_change(patch)
+
+    def _build_graph(self):
+        rate = self._sample_rate
+        # The borrowed source's only reader, at Width 1 in Haas and so the
+        # source byte for byte: a switch between the characters re-points
+        # the output and never skips or repeats a source frame.
+        self._ms = self._own(audioroute.MidSide(
+            self._source, width=1.0, sample_rate=rate, channel_count=2),
+            reset=False)
+        # A MidSide with no source: one block of zeros per pull, which the
+        # voices prime from when they are wired (`_wire`).
+        self._hush = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=2), reset=False)
+        self._in = self._own(audioroute.Port(self._hush), reset=False)
+        self._split = self._own(audioroute.Splitter(self._in, taps=2),
+                                reset=False)
+        self._line = self._own(audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=2, max_delay_ms=LINE_MS,
+            delay_frames=1, feedback=0.0, mix=2.0, damping_hz=0.0,
+            cut_hz=0.0, delay_slew=SLEW), reset=self._clear)
+        self._line.play(self._split.tap(1))
+        # Not reset by the walk: a voice resets its source, and neither
+        # voice holds a block between two pulls (`_wire`).
+        self._mixer = self._own(audiomixer.Mixer(
+            voice_count=2, buffer_size=BLOCK * 2 * 4, channel_count=2,
+            bits_per_sample=16, samples_signed=True, sample_rate=rate),
+            reset=False)
+        # The Haas output: a width-1 MidSide, byte for byte, whose reset
+        # forwards nothing. A host's reset of the output (a mixer voice's
+        # `play()` does one) would otherwise reach the Mixer, and
+        # CircuitPython's own Mixer handles that differently from
+        # audiodsp's, so the interpreters would part ways.
+        self._tail = self._own(audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate, channel_count=2),
+            reset=False)
+        self._silence = audiocore.RawSample(
+            array("h", bytes(2 * 2 * 2)), sample_rate=rate, channel_count=2)
+        self._output = self._ms
+
+    def _wire(self):
+        """Play the voices, the first time the output reaches the mixer.
+
+        A voice's `play()` primes a block from its source. With the
+        Splitter on `_hush` that block is zeros, and one pull of the mixer
+        hands it out, so wiring takes nothing from the borrowed source and
+        leaves no voice holding a block: whatever the MidSide has handed
+        out, the output has played, at every Width and Character. Without
+        `audiocore.get_buffer` the voices prime the source's next block,
+        which the next pull plays."""
+        pull = getattr(audiocore, "get_buffer", None)
+        voices = self._mixer.voice
+        self._levels()
+        _component.open_level_gates(self._mixer, voices, self._silence)
+        if pull is None:
+            self._in.play(self._ms)
+        voices[0].play(self._split.tap(0))
+        voices[1].play(self._line)
+        if pull is not None:
+            pull(self._mixer)
+            self._in.play(self._ms)
+            self._clear()
+        self._wired = True
+
+    def _clear(self):
+        self._line.clear()
+        self._reach = None
+
+    # -- the maps ------------------------------------------------------
+
+    def _value(self, index):
+        return _component.macro_value(self._MACRO_RANGES[index],
+                                      self._macros[index])
+
+    def _width(self):
+        return _between(self._value(WIDTH_I), 0.0, 2.0)
+
+    def _mid_side(self):
+        return self._macros[CHARACTER_I] >= 0.5
+
+    def _delay_ms(self):
+        if abs(self._macros[DELAY_I] - self._delay_seed) <= ECHO_TOLERANCE:
+            return self._delay_exact
+        return self._value(DELAY_I)
+
+    def _levels(self):
+        lead, copy = haas_voices(self._width())
+        voices = self._mixer.voice
+        voices[0].level, voices[0].panning = lead
+        voices[1].level, voices[1].panning = copy
+
+    # -- applying ------------------------------------------------------
+
+    def _apply_macro(self, index, position):
+        del index, position
+        if self._ready:
+            self._refresh()
+
+    def program_change(self, index, channel=0, note_id=-1,
+                       sample_position=0):
+        """Apply patch `index` whole, then refresh the graph once."""
+        ready = self._ready
+        self._ready = False
+        try:
+            _component.Component.program_change(
+                self, index, channel, note_id, sample_position)
+        finally:
+            self._ready = ready
+        if ready and type(self).PATCHES.get(index) is not None:
+            self._refresh()
+
+    def _refresh(self):
+        if self._ms is None:
+            return
+        self._frames = max(1, whole_frames(self._delay_ms(),
+                                           self._sample_rate))
+        self._line.set(delay_frames=self._frames)
+        self._route()
+        if self._reach is None or self._frames > self._reach:
+            self._reach = self._frames
+
+    def _route(self):
+        """Point the output at the MidSide (Mid/Side, or Haas Width 0) or
+        at the Haas mixer, emptying the line when the mixer comes back."""
+        width = self._width()
+        if self._mid_side():
+            self._ms.set(width=width)
+            self._route_around(self._ms)
+            return
+        self._ms.set(width=1.0)
+        if width <= 0.0:
+            self._route_around(self._ms)
+            return
+        if not self._wired:
+            self._wire()
+        else:
+            self._levels()
+            self._rejoin(keep=(self._ms,))
+        self._output = self._tail
+
+    def _haas_live(self):
+        return (self._ms is not None and not self._mid_side()
+                and self._width() > 0.0)
+
+    @property
+    def tail_samples(self):
+        """What this bound promises is in the class docstring."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        """`tail_samples` without the liveness check: a plain method, so a
+        subclass can reach it on MicroPython, whose `property` has no
+        `fget`."""
+        if not self._haas_live():
+            return 0
+        return (self._reach or self._frames) + 1
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..9656954 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,10 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("StereoWidener", "plants", "H3/"):
+        "delay_slew acts only while a Delay move walks the read head, and"
+        " the kit's render never moves a control; H3's own test shows the"
+        " plant red on a move, and no macro or patch sets the slew",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..3cd664c 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,6 +75,25 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
+    ("StereoWidener", "E4-m0=", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Width: the copy's level, or the route to"
+        " the wire at 0)",
+    ("StereoWidener", "E4-m2=", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Character swaps Haas and Mid/Side)",
+    ("StereoWidener", "E6-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (a patch change moves Width or Character)",
+    ("StereoWidener", "E11-2patch", "P4"):
+        "a Delay move glides by design (the card's H3): from patch 1 or 2,"
+        " Mid/Side and then patch 0 empty the line and land it at 14 ms, and"
+        " the way back walks the read head at 0.1875, 384 frames of delay in"
+        " 2048 at 48 kHz, past the copy's reach that bounds P4; it matches"
+        " once the head lands",
+    ("StereoWidener", "E11-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Width, Character or a patch change)",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
diff --git a/tests/test_cpython_effects_stereowidener.py b/tests/test_cpython_effects_stereowidener.py
new file mode 100644
index 0000000..fa7f005
--- /dev/null
+++ b/tests/test_cpython_effects_stereowidener.py
@@ -0,0 +1,1021 @@
+"""`StereoWidener`'s trait and planted-fault tests.
+
+Six traits: H1-H3 for Haas, M1-M2 for Mid/Side, W for the wire. Each has
+its measurement, run over the cells listed with it, and the same
+measurement shown red on a planted fault of the same kind. `KIT_PLANTS`
+hands the plants to the kit, which shows each one differs from the clean
+class and that no knob stop or patch reproduces it.
+
+Every law a measurement checks against is written out here, never taken
+from the class: the whole-frame Delay, the Haas levels, the Mid/Side
+matrix.
+
+The module is numpy-free and imports on MicroPython and CircuitPython,
+where `unittest` is absent: the kit reads `KIT_PLANTS` there, and running
+the file prints each trait's figures on whichever interpreter runs it:
+
+    MICROPYPATH=lib:tests/support micropython \\
+        tests/test_cpython_effects_stereowidener.py
+"""
+
+import math
+import sys
+from array import array
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                     # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    import os
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.join(_HERE, "..", "lib"))
+except (ImportError, AttributeError, NameError):   # no os.path natively
+    pass
+
+import audiocore                                            # noqa: E402
+import audioecho                                            # noqa: E402
+import audiomixer                                           # noqa: E402
+from audioeffects import _component                         # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+VENDOR = "PyDevices"
+
+RATES = (48000, 22050)
+BLOCK = 256
+WIDTH_I, DELAY_I, CHARACTER_I = range(3)
+
+StereoWidener = rebuilt.module_class("StereoWidener")
+
+
+# --------------------------------------------------------------------------
+# The card's laws, written out independently of the class
+
+
+def law_frames(ms, rate):
+    """Section 2: tau = max(1, round(Delay ms x rate / 1000))."""
+    return max(1, int(math.floor(ms * rate / 1000.0 + 0.5)))
+
+
+def law_delay_ms(midi):
+    """Section 3: Delay is 1-40 ms, log, on the 0-127 grid."""
+    return 40.0 ** (midi / 127.0)
+
+
+def delay_midi(ms):
+    """The float MIDI position that stands for `ms` exactly."""
+    return 127.0 * math.log(ms) / math.log(40.0)
+
+
+def width_midi(width):
+    """The float MIDI position for a Width, by the BIPOLAR law (MIDI 64 is
+    1.0, each half its own slope)."""
+    position = width / 2.0
+    if position >= 0.5:
+        return 64.0 + (position - 0.5) * 126.0
+    return 64.0 - (0.5 - position) * 128.0
+
+
+def haas_expect(width):
+    """Section 2's Haas law, per unit input: (left gain, right's own gain,
+    the copy's gain)."""
+    return min(1.0, 1.0 / width), max(0.0, 1.0 - width), min(width, 1.0)
+
+
+# --------------------------------------------------------------------------
+# Material and rendering: integer arithmetic, the same on every interpreter
+
+
+def lcg_noise(frames, channels, seed, peak=32767):
+    """Seeded noise in -peak-1 .. peak (full scale at 32767), each channel
+    its own draw."""
+    out = array("h", bytes(2 * frames * channels))
+    state = (seed * 2654435761 + 1) & 0x7FFFFFFF
+    span = 2 * peak + 2 if peak == 32767 else 2 * peak + 1
+    low = -peak - 1 if peak == 32767 else -peak
+    for i in range(frames * channels):
+        state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+        out[i] = low + (state >> 7) % span
+    return out
+
+
+def rint(x):
+    """Round half away from zero, symmetric, so -x rounds to -round(x)."""
+    if x >= 0:
+        return int(x + 0.5)
+    return -int(-x + 0.5)
+
+
+def sine(frames, hz, rate, amp, start=0.0, channels=2):
+    """The same sine in every channel; `start` shifts its phase in frames."""
+    out = array("h", bytes(2 * frames * channels))
+    w = 2.0 * math.pi * hz / rate
+    for n in range(frames):
+        v = rint(amp * math.sin(w * (n - start)))
+        for c in range(channels):
+            out[channels * n + c] = v
+    return out
+
+
+def source(values, rate, channels=2):
+    return audiocore.RawSample(values, sample_rate=rate,
+                               channel_count=channels)
+
+
+def pull(effect, frames, moves=None):
+    """Render `frames` frames of `effect.output`; `moves` maps a block
+    index to a callable run on the effect before that block is pulled."""
+    channels = effect.channel_count
+    out = array("h")
+    block = 0
+    done = False
+    while len(out) < frames * channels:
+        if moves and block in moves:
+            moves[block](effect)
+        if done:
+            out.extend(array("h", bytes(2 * BLOCK * channels)))
+        else:
+            result, data = audiocore.get_buffer(effect.output)
+            out.extend(array("h", bytes(data)))
+            done = result == GET_BUFFER_DONE
+        block += 1
+    return out[:frames * channels]
+
+
+def render(cls, values, rate, channels=2, frames=None, moves=None,
+           **options):
+    if frames is None:
+        frames = len(values) // channels
+    e = cls(source(values, rate, channels), **options)
+    try:
+        return pull(e, frames, moves)
+    finally:
+        e.deinit()
+
+
+# --------------------------------------------------------------------------
+# Planted faults
+
+
+class CopyFromMid(StereoWidener):
+    """H1: the copy is built from the mid (`input_pan=+1`), not the right."""
+
+    def _build_graph(self):
+        StereoWidener._build_graph(self)
+        self._line.set(input_pan=1.0)
+
+
+class BackwardsPan(StereoWidener):
+    """H2: the lead voice's panning sign flipped, so it turns the left down
+    where it should turn the right down."""
+
+    def _levels(self):
+        StereoWidener._levels(self)
+        voice = self._mixer.voice[0]
+        voice.panning = -voice.panning
+
+
+class JumpDelay(StereoWidener):
+    """H3: `delay_slew=0`, so a Delay move jumps the read head."""
+
+    def _build_graph(self):
+        StereoWidener._build_graph(self)
+        self._line.set(delay_slew=0.0)
+
+
+class LevelWidth(StereoWidener):
+    """M1: Mid/Side Width done as a Mixer level, 1 - |w - 1| / 2, on the
+    unwidened pair, instead of the MidSide matrix."""
+
+    def _build_graph(self):
+        StereoWidener._build_graph(self)
+        self._flat = self._own(audiomixer.Mixer(
+            voice_count=1, buffer_size=BLOCK * 2 * 4, channel_count=2,
+            bits_per_sample=16, samples_signed=True,
+            sample_rate=self._sample_rate), reset=False)
+        self._flat_wired = False
+
+    def _route(self):
+        StereoWidener._route(self)
+        if not self._mid_side():
+            return
+        width = self._width()
+        self._ms.set(width=1.0)
+        voice = self._flat.voice[0]
+        voice.level = 1.0 - abs(width - 1.0) / 2.0
+        if not self._flat_wired:
+            _component.open_level_gates(self._flat, self._flat.voice,
+                                        self._silence)
+            voice.play(self._ms)
+            self._flat_wired = True
+        self._output = self._flat
+
+
+class LateMatrix(StereoWidener):
+    """M2: the Mid/Side matrix composed through a one-frame line, so the
+    widened pair comes out a frame late, at every Width but the wire."""
+
+    def _build_graph(self):
+        StereoWidener._build_graph(self)
+        self._late = self._own(audioecho.FeedbackDelay(
+            sample_rate=self._sample_rate, channel_count=2, max_delay_ms=2.0,
+            delay_frames=1, feedback=0.0, mix=2.0), reset=self._late_clear)
+        self._late.play(self._ms)
+
+    def _late_clear(self):
+        self._late.clear()
+
+    def _route(self):
+        StereoWidener._route(self)
+        if self._mid_side() and self._width() != 1.0:
+            self._output = self._late
+
+
+class FixedCopy(StereoWidener):
+    """W: the old class's copy at a fixed level of 0.8 whatever the Width,
+    with no route around the copy at Width 0."""
+
+    def _levels(self):
+        StereoWidener._levels(self)
+        self._mixer.voice[1].level = 0.8
+
+    def _route(self):
+        if self._mid_side() or self._width() > 0.0:
+            StereoWidener._route(self)
+            return
+        self._ms.set(width=1.0)
+        if not self._wired:
+            self._wire()
+        else:
+            self._levels()
+            self._rejoin(keep=(self._ms,))
+        self._output = self._tail
+
+
+#: The kit's plant table: a plant for a Mid/Side trait is judged at patch 4,
+#: the first Mid/Side patch.
+KIT_PLANTS = {
+    "H1": CopyFromMid,
+    "H2": BackwardsPan,
+    "H3": JumpDelay,
+    "M1": (LevelWidth, 4),
+    "M2": (LateMatrix, 4),
+    "W": FixedCopy,
+}
+
+
+# --------------------------------------------------------------------------
+# The measurements
+
+
+def h1_read(cls, rate, seed, frames=4096, width=None, delay_ms=None,
+            patch=None, delay_grid=None):
+    """H1(b): (left frames differing, right frames differing from R(n - tau)
+    and zero before tau, tau) on seeded full-scale noise."""
+    values = lcg_noise(frames, 2, seed)
+    options = {}
+    if width is not None:
+        options["width"] = width
+    if delay_ms is not None:
+        options["delay_ms"] = delay_ms
+    if patch is not None:
+        options["patch"] = patch
+    moves = None
+    if delay_grid is not None:
+        moves = {0: lambda e: e.set_macro(DELAY_I, delay_grid)}
+    e = cls(source(values, rate), **options)
+    try:
+        if delay_grid is not None:
+            ms = law_delay_ms(delay_grid)
+        elif patch is not None:
+            midi = StereoWidener.PATCHES[patch][1][DELAY_I]
+            ms = 14.0 if midi == 91 else law_delay_ms(midi)
+        else:
+            ms = 14.0 if delay_ms is None else delay_ms
+        tau = law_frames(ms, rate)
+        out = pull(e, frames, moves)
+    finally:
+        e.deinit()
+    left = right = 0
+    for n in range(frames):
+        if out[2 * n] != values[2 * n]:
+            left += 1
+        want = values[2 * (n - tau) + 1] if n >= tau else 0
+        if out[2 * n + 1] != want:
+            right += 1
+    return left, right, tau
+
+
+def fold_rms(cls, rate, hz, frames=8192, amp=8192, **options):
+    """H1(b), the mono fold: RMS of L' + R' (integers) after tau frames,
+    for a centred sine at `hz`."""
+    values = sine(frames, hz, rate, amp)
+    e = cls(source(values, rate), **options)
+    try:
+        tau = law_frames(options.get("delay_ms", 14.0), rate)
+        out = pull(e, frames)
+    finally:
+        e.deinit()
+    total = 0
+    count = 0
+    for n in range(tau + 1024, frames):
+        s = out[2 * n] + out[2 * n + 1]
+        total += s * s
+        count += 1
+    return math.sqrt(total / count)
+
+
+def notch_hz(rate, tau, k):
+    """The mono fold's k-th notch: fs / (2 tau) x (2k + 1)."""
+    return rate / (2.0 * tau) * (2 * k + 1)
+
+
+def h2_read(cls, rate, width, delay_ms, click=16384):
+    """H2(b): (L'[100], R'[300], R'[300 + tau]) for a click of `click` in
+    the left at frame 100 and in the right at frame 300."""
+    frames = 300 + law_frames(delay_ms, rate) + 512
+    values = array("h", bytes(4 * frames))
+    values[200] = click
+    values[601] = click
+    tau = law_frames(delay_ms, rate)
+    out = render(cls, values, rate, frames=frames, width=width,
+                 delay_ms=delay_ms)
+    return out[200], out[601], out[2 * (300 + tau) + 1]
+
+
+def h2_errors(cls, rate, delay_ms, widths=(0.25, 0.5, 0.75, 1.0, 1.5, 2.0),
+              click=16384):
+    """H2(d): the largest error, in LSB, of the three reads against the law,
+    over `widths`."""
+    worst = 0.0
+    for w in widths:
+        got = h2_read(cls, rate, w, delay_ms, click)
+        want = [click * g for g in haas_expect(w)]
+        for g, x in zip(got, want):
+            worst = max(worst, abs(g - x))
+    return worst
+
+
+#: H3's half cycle of 1 kHz, in frames, and the window the peak sits in.
+H3_HALF = {48000: 24, 22050: 11}
+H3_WINDOW = {48000: 4, 22050: 2}
+
+
+def h3_read(cls, rate, seed, up):
+    """H3(b): (ratio of the largest step over the move to the largest
+    steady step before it, frames differing from R(n - tau') after
+    B + 1024). Patch 0, a 1 kHz sine at -6 dBFS; the Delay move lands at a
+    block boundary B, with a peak of the copy within the window of B."""
+    state = (seed * 2654435761 + 7) & 0x7FFFFFFF
+    state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+    window = H3_WINDOW[rate]
+    offset = (state >> 8) % (2 * window + 1) - window
+    state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+    tau = law_frames(14.0, rate)
+    first = (tau + 1024) // BLOCK + 1
+    block = first + (state >> 8) % 8
+    b = block * BLOCK
+    quarter = rate / 4000.0
+    # The copy at frame b + offset is the source at b + offset - tau: put a
+    # peak of the sine there.
+    start = b + offset - tau - quarter
+    frames = b + 4096
+    values = sine(frames, 1000.0, rate, 16384, start=start)
+    new_tau = tau + (H3_HALF[rate] if up else -H3_HALF[rate])
+    target = new_tau * 1000.0 / rate
+    moves = {block: lambda e: e.set_macro(DELAY_I, delay_midi(target))}
+    out = render(cls, values, rate, frames=frames, moves=moves, patch=0)
+    steady = 0
+    for n in range(b - 512, b):
+        steady = max(steady, abs(out[2 * n + 1] - out[2 * n - 1]))
+    moving = 0
+    for n in range(b, b + 1024):
+        moving = max(moving, abs(out[2 * n + 1] - out[2 * n - 1]))
+    late = 0
+    for n in range(b + 1024, frames):
+        if out[2 * n + 1] != values[2 * (n - new_tau) + 1]:
+            late += 1
+    ratio = float("inf") if steady == 0 else moving / steady
+    return ratio, late
+
+
+def side_target(width):
+    """M1(d): the side's gain, the node's Q14 width."""
+    return rint(width * 16384) / 16384.0
+
+
+def m1_read(cls, rate, seed, width, frames=4096, patch=None):
+    """M1(b): (largest |(L' + R') - (L + R)|, largest |(L' - R') - g (L - R)|)
+    on seeded independent noise peaking at -6.02 dBFS. Built at `patch`
+    (or in Mid/Side), with Width set before the first pull."""
+    values = lcg_noise(frames, 2, seed, peak=16384)
+    if patch is None:
+        e = cls(source(values, rate), width=width, character="mid_side")
+    else:
+        e = cls(source(values, rate), patch=patch)
+        e.set_macro(WIDTH_I, width_midi(width))
+    try:
+        out = pull(e, frames)
+    finally:
+        e.deinit()
+    g = side_target(width)
+    worst_sum = 0
+    worst_side = 0.0
+    for n in range(frames):
+        l, r = values[2 * n], values[2 * n + 1]
+        lo, ro = out[2 * n], out[2 * n + 1]
+        worst_sum = max(worst_sum, abs((lo + ro) - (l + r)))
+        worst_side = max(worst_side, abs((lo - ro) - g * (l - r)))
+    return worst_sum, worst_side
+
+
+M1_WIDTHS = (0.0, 0.25, 0.5, 1.0, 1.5, 2.0)
+
+
+def m1_random_width(seed):
+    state = (seed * 2654435761 + 3) & 0x7FFFFFFF
+    state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+    return ((state >> 8) % 2001) / 1000.0
+
+
+def m2_read(cls, rate, width, click=8192, at=100):
+    """M2(b): (L', R') at a hard-left click of `click`."""
+    frames = at + 512
+    values = array("h", bytes(4 * frames))
+    values[2 * at] = click
+    out = render(cls, values, rate, frames=frames, width=width,
+                 character="mid_side")
+    return out[2 * at], out[2 * at + 1]
+
+
+M2_WIDTHS = (0.0, 0.5, 1.0, 1.5, 2.0)
+
+
+def m2_errors(cls, rate, click=8192):
+    """M2(d): (largest error against (1 +- w) / 2 x click, the R' read at
+    1.5 and 2)."""
+    worst = 0.0
+    inverted = []
+    for w in M2_WIDTHS:
+        lo, ro = m2_read(cls, rate, w, click)
+        worst = max(worst, abs(lo - (1.0 + w) / 2.0 * click),
+                    abs(ro - (1.0 - w) / 2.0 * click))
+        if w > 1.0:
+            inverted.append(ro)
+    return worst, inverted
+
+
+def w_differing(cls, rate, seed, channels, frames=4096, **options):
+    """W(b): samples differing from the input, on seeded full-scale noise."""
+    values = lcg_noise(frames, channels, seed)
+    out = render(cls, values, rate, channels, frames=frames, **options)
+    return sum(1 for i in range(len(values)) if out[i] != values[i])
+
+
+def w_mono_cells():
+    """W(c), mono: every patch, both characters, Width 0 and 2, Delay 1 and
+    40 ms."""
+    cells = []
+    for patch in sorted(StereoWidener.PATCHES):
+        cells.append({"patch": patch})
+    for character in ("haas", "mid_side"):
+        for width in (0.0, 2.0):
+            for delay in (1.0, 40.0):
+                cells.append({"character": character, "width": width,
+                              "delay_ms": delay})
+    return cells
+
+
+SEEDS = tuple(range(1, 9))
+
+#: `audiocore.GET_BUFFER_DONE`, which a native audiocore does not export.
+GET_BUFFER_DONE = getattr(audiocore, "GET_BUFFER_DONE", 0)
+
+
+# --------------------------------------------------------------------------
+# The tests
+
+
+def _same_after(a, b):
+    return sum(1 for i in range(len(a)) if a[i] != b[i])
+
+
+class TheSurface(TestCase):
+    def test_macros_patches_tier_latency(self):
+        self.assertEqual(StereoWidener.MACRO_LABELS,
+                         ("Width", "Delay", "Character"))
+        self.assertEqual(StereoWidener.MACRO_MODES,
+                         {0: "BIPOLAR", 1: "UNIPOLAR", 2: "TOGGLE"})
+        self.assertEqual(StereoWidener.TIER, _component.AUDIODSP)
+        e = StereoWidener(source(array("h", bytes(16)), 48000))
+        try:
+            self.assertEqual(e.latency_samples, 0)
+            self.assertEqual(e.capabilities, ())
+        finally:
+            e.deinit()
+
+    def test_the_spans(self):
+        e = StereoWidener(source(array("h", bytes(16)), 48000))
+        try:
+            e.set_macro(WIDTH_I, 0)
+            self.assertEqual(e.macro(WIDTH_I), 0.0)
+            e.set_macro(WIDTH_I, 64)
+            self.assertEqual(e.macro(WIDTH_I), 1.0)
+            e.set_macro(WIDTH_I, 127)
+            self.assertEqual(e.macro(WIDTH_I), 2.0)
+            e.set_macro(DELAY_I, 0)
+            self.assertAlmostEqual(e.macro(DELAY_I), 1.0, places=9)
+            e.set_macro(DELAY_I, 127)
+            self.assertAlmostEqual(e.macro(DELAY_I), 40.0, places=9)
+        finally:
+            e.deinit()
+
+    def test_patches_are_the_card_settings_on_the_grid(self):
+        table = {0: (1.0, 14.0, 0), 1: (1.0, 6.0, 0), 2: (1.0, 25.0, 0),
+                 3: (1.5, 14.0, 0), 4: (1.5, 14.0, 1), 5: (0.5, 14.0, 1),
+                 6: (0.0, 14.0, 1)}
+        spans = StereoWidener._MACRO_RANGES
+        for patch, (w, ms, ch) in table.items():
+            want = (_component.macro_of(spans[0], w, "BIPOLAR"),
+                    _component.macro_of(spans[1], ms),
+                    127 * ch)
+            self.assertEqual(StereoWidener.PATCHES[patch][1], want, patch)
+
+    def test_a_fresh_instance_reads_patch_0(self):
+        e = StereoWidener(source(array("h", bytes(16)), 48000))
+        try:
+            fresh = [e.get_macro(i) for i in range(3)]
+            self.assertEqual(fresh, [float(v) for v in
+                                     StereoWidener.PATCHES[0][1]])
+        finally:
+            e.deinit()
+
+    def test_the_constructor_delay_plays_exactly(self):
+        # 14.0 ms is 672 frames at 48 kHz; its grid step, 14.06 ms, is 675.
+        for rate in (48000, 44100, 22050):
+            for patch in (None, 0):
+                left, right, tau = h1_read(StereoWidener, rate, 1, 2048,
+                                           patch=patch)
+                self.assertEqual((left, right), (0, 0), (rate, patch))
+                self.assertEqual(tau, law_frames(14.0, rate))
+
+    def test_delay_does_nothing_in_mid_side(self):
+        values = lcg_noise(2048, 2, 5, peak=16384)
+        base = render(StereoWidener, values, 48000, width=1.5,
+                      character="mid_side")
+        for midi in (0, 40, 127):
+            moved = render(StereoWidener, values, 48000, width=1.5,
+                           character="mid_side",
+                           moves={0: lambda e: e.set_macro(DELAY_I, midi)})
+            self.assertEqual(_same_after(base, moved), 0, midi)
+
+    def test_bad_character_raises(self):
+        with self.assertRaises(ValueError):
+            StereoWidener(source(array("h", bytes(16)), 48000),
+                          character="wide")
+
+    def test_tail_samples(self):
+        values = array("h", bytes(16))
+        e = StereoWidener(source(values, 48000))
+        try:
+            self.assertEqual(e.tail_samples, 673)
+            e.set_macro(DELAY_I, 0)                  # falling: keeps 672
+            self.assertEqual(e.tail_samples, 673)
+            e.set_macro(DELAY_I, 127)                # 40 ms, 1920 frames
+            self.assertEqual(e.tail_samples, 1921)
+            e.set_macro(WIDTH_I, 0)
+            self.assertEqual(e.tail_samples, 0)
+            e.set_macro(WIDTH_I, 96)
+            e.set_macro(CHARACTER_I, 127)
+            self.assertEqual(e.tail_samples, 0)
+            e.reset()
+            self.assertEqual(e.tail_samples, 673)
+        finally:
+            e.deinit()
+        mono = StereoWidener(source(array("h", bytes(8)), 48000, 1))
+        try:
+            self.assertEqual(mono.tail_samples, 0)
+        finally:
+            mono.deinit()
+
+    def test_the_output_is_silent_after_the_tail(self):
+        for rate in RATES:
+            for patch in sorted(StereoWidener.PATCHES):
+                # Noise, then silence: a RawSample asked again after its
+                # end plays again, so the silence is part of the material.
+                frames = 2048 + 4096
+                values = lcg_noise(frames, 2, 3)
+                for i in range(2 * 2048, 2 * frames):
+                    values[i] = 0
+                e = StereoWidener(source(values, rate), patch=patch)
+                try:
+                    out = pull(e, frames)
+                    bound = 2048 + e.tail_samples + e.latency_samples
+                finally:
+                    e.deinit()
+                last = max([n for n in range(frames)
+                            if out[2 * n] or out[2 * n + 1]] or [0])
+                self.assertLess(last, bound, (rate, patch))
+
+    def test_reset_empties_the_line_and_returns_to_patch_0(self):
+        rate = 48000
+        values = lcg_noise(4096, 2, 9)
+        e = StereoWidener(source(values, rate), patch=2)
+        try:
+            pull(e, 1024)
+            e.reset()
+            self.assertEqual(e.patch_index, 0)
+            self.assertEqual([e.get_macro(i) for i in range(3)],
+                             [float(v) for v in StereoWidener.PATCHES[0][1]])
+            out = pull(e, 1024)
+        finally:
+            e.deinit()
+        tau = law_frames(14.0, rate)
+        # The right comes back out of silence tau frames later, then plays
+        # the source's own right channel tau late.
+        for n in range(tau):
+            self.assertEqual(out[2 * n + 1], 0, n)
+        for n in range(tau, 1024):
+            self.assertEqual(out[2 * n + 1],
+                             values[2 * (1024 + n - tau) + 1], n)
+
+    def test_the_tempo_is_never_read(self):
+        reads = []
+
+        def transport():
+            reads.append(1)
+            return (True, 0.0, 120.0, 4, 4)
+
+        e = StereoWidener.create(source(array("h", bytes(16)), 48000),
+                                 48000, transport=transport)
+        try:
+            for i in range(3):
+                for v in (0, 64, 127):
+                    e.set_macro(i, v)
+                    e.transport_changed()
+            for patch in StereoWidener.PATCHES:
+                e.program_change(patch)
+            e.reset()
+            self.assertEqual(e.capabilities, ())
+        finally:
+            e.deinit()
+        self.assertEqual(reads, [])
+
+    def test_no_latency_in_either_character(self):
+        for character in ("haas", "mid_side"):
+            values = array("h", bytes(4 * 512))
+            values[200] = 12000
+            out = render(StereoWidener, values, 48000, character=character)
+            self.assertEqual(out[200], 12000, character)
+            self.assertEqual(out[198], 0, character)
+            e = StereoWidener(source(values, 48000), character=character)
+            try:
+                self.assertEqual(e.latency_samples, 0)
+            finally:
+                e.deinit()
+
+
+class H1TheCopy(TestCase):
+    def test_the_copy_is_the_right_exactly_delay_late(self):
+        cells = []
+        for rate in RATES:
+            for patch in (0, 1, 2):
+                cells.append(dict(rate=rate, patch=patch))
+            for ms in (1.0, 5.0, 14.0, 30.0, 40.0):
+                cells.append(dict(rate=rate, delay_ms=ms))
+        for seed in SEEDS:
+            for cell in cells:
+                left, right, tau = h1_read(StereoWidener, seed=seed,
+                                           frames=2048 + 2048, **cell)
+                self.assertEqual((left, right), (0, 0), (seed, cell, tau))
+
+    def test_random_grid_delays(self):
+        for seed in SEEDS:
+            midi = (seed * 37 + 11) % 128
+            for rate in RATES:
+                left, right, tau = h1_read(StereoWidener, rate, seed,
+                                           frames=4096, delay_grid=midi)
+                self.assertEqual((left, right), (0, 0), (seed, rate, midi))
+
+    def test_the_right_half_above_width_1(self):
+        for seed in SEEDS[:4]:
+            for rate in RATES:
+                for width in (1.5, 2.0):
+                    _, right, tau = h1_read(StereoWidener, rate, seed,
+                                            width=width)
+                    self.assertEqual(right, 0, (seed, rate, width))
+
+    def test_the_mono_fold_notches(self):
+        for rate in RATES:
+            tau = law_frames(14.0, rate)
+            for k in range(4):
+                self.assertLessEqual(
+                    fold_rms(StereoWidener, rate, notch_hz(rate, tau, k)),
+                    1.0, (rate, k))
+            peak = fold_rms(StereoWidener, rate, rate / tau)
+            self.assertGreater(peak, 11000.0, rate)
+
+    def test_the_default_notches_are_where_the_text_says(self):
+        tau = law_frames(14.0, 48000)
+        self.assertEqual([round(notch_hz(48000, tau, k), 1)
+                          for k in range(3)], [35.7, 107.1, 178.6])
+
+    def test_copy_from_mid_is_red(self):
+        _, right, _ = h1_read(CopyFromMid, 48000, 1)
+        self.assertGreater(right, 1000)
+        left, _, _ = h1_read(CopyFromMid, 48000, 1)
+        self.assertEqual(left, 0)
+        tau = law_frames(14.0, 48000)
+        self.assertLessEqual(
+            fold_rms(CopyFromMid, 48000, notch_hz(48000, tau, 0)), 1.0)
+
+
+class H2TheWidthLaw(TestCase):
+    def test_width_moves_the_right_to_its_copy(self):
+        for rate in RATES:
+            for ms in (1.0, 14.0):
+                self.assertLessEqual(h2_errors(StereoWidener, rate, ms), 1.0,
+                                     (rate, ms))
+
+    def test_six_db_down_at_width_2(self):
+        left, own, copy = h2_read(StereoWidener, 48000, 2.0, 14.0)
+        self.assertEqual((left, own, copy), (8192, 0, 16384))
+
+    def test_backwards_pan_is_red(self):
+        for w in (0.25, 0.5, 0.75, 1.0, 1.5, 2.0):
+            got = h2_read(BackwardsPan, 48000, w, 14.0)
+            want = [16384 * g for g in haas_expect(w)]
+            self.assertGreater(max(abs(g - x) for g, x in zip(got, want)),
+                               1000.0, w)
+
+    def test_the_comb_is_deepest_at_half_width(self):
+        rate = 48000
+        tau = law_frames(14.0, rate)
+        hz = notch_hz(rate, tau, 0)
+        rms = {}
+        for w in (0.25, 0.5, 0.75):
+            values = sine(8192, hz, rate, 8192)
+            out = render(StereoWidener, values, rate, width=w)
+            total = sum(out[2 * n + 1] ** 2 for n in range(tau + 1024, 8192))
+            rms[w] = math.sqrt(total / (8192 - tau - 1024))
+        self.assertLessEqual(rms[0.5], 1.0)
+        self.assertGreater(rms[0.25], 2000.0)
+        self.assertGreater(rms[0.75], 2000.0)
+
+
+class H3TheGlide(TestCase):
+    def test_a_delay_move_glides(self):
+        for rate in RATES:
+            for up in (True, False):
+                for seed in SEEDS:
+                    ratio, late = h3_read(StereoWidener, rate, seed, up)
+                    self.assertLessEqual(ratio, 1.25, (rate, up, seed))
+                    self.assertEqual(late, 0, (rate, up, seed))
+
+    def test_jump_delay_is_red(self):
+        for rate in RATES:
+            for up in (True, False):
+                ratio, _ = h3_read(JumpDelay, rate, 1, up)
+                self.assertGreater(ratio, 1.25, (rate, up))
+
+
+class M1TheMonoSum(TestCase):
+    def test_the_sum_holds_and_the_side_follows(self):
+        for rate in RATES:
+            for seed in SEEDS:
+                widths = M1_WIDTHS + (m1_random_width(seed),)
+                for w in widths:
+                    s, side = m1_read(StereoWidener, rate, seed, w)
+                    self.assertLessEqual(s, 1, (rate, seed, w))
+                    self.assertLessEqual(side, 1.0, (rate, seed, w))
+
+    def test_at_the_mid_side_patches(self):
+        for patch in (4, 5, 6):
+            for w in (0.0, 1.0, 2.0):
+                s, side = m1_read(StereoWidener, 48000, patch, w,
+                                  patch=patch)
+                self.assertLessEqual(s, 1, (patch, w))
+                self.assertLessEqual(side, 1.0, (patch, w))
+
+    def test_a_centred_part_is_unchanged(self):
+        values = lcg_noise(2048, 1, 4)
+        pair = array("h", bytes(4 * 2048))
+        for n in range(2048):
+            pair[2 * n] = pair[2 * n + 1] = values[n]
+        for w in M1_WIDTHS:
+            out = render(StereoWidener, pair, 48000, width=w,
+                         character="mid_side")
+            self.assertEqual(_same_after(out, pair), 0, w)
+
+    def test_half_scale_never_clips(self):
+        peak = 16383
+        for character in ("haas", "mid_side"):
+            for w in (0.0, 0.5, 1.0, 1.5, 2.0):
+                for shape in ("anti", "left", "noise"):
+                    if shape == "noise":
+                        values = lcg_noise(2048, 2, 6, peak=peak)
+                    else:
+                        values = array("h", bytes(4 * 2048))
+                        for n in range(2048):
+                            v = peak if (n // 37) % 2 else -peak
+                            values[2 * n] = v
+                            values[2 * n + 1] = -v if shape == "anti" else 0
+                    out = render(StereoWidener, values, 48000, width=w,
+                                 character=character)
+                    self.assertLess(max(abs(x) for x in out), 32767,
+                                    (character, w, shape))
+
+    def test_level_width_is_red(self):
+        for w in M1_WIDTHS:
+            s, side = m1_read(LevelWidth, 48000, 1, w)
+            if w == 1.0:
+                self.assertLessEqual(max(s, side), 1.0)
+            else:
+                self.assertGreater(max(s, side), 1.0, w)
+
+
+class M2TheMatrix(TestCase):
+    def test_the_textbook_matrix(self):
+        for rate in RATES:
+            worst, inverted = m2_errors(StereoWidener, rate)
+            self.assertLessEqual(worst, 1.0, rate)
+            self.assertTrue(all(r < 0 for r in inverted), inverted)
+
+    def test_late_matrix_is_red(self):
+        for w in M2_WIDTHS:
+            lo, ro = m2_read(LateMatrix, 48000, w)
+            err = max(abs(lo - (1.0 + w) / 2.0 * 8192),
+                      abs(ro - (1.0 - w) / 2.0 * 8192))
+            if w == 1.0:
+                self.assertLessEqual(err, 1.0)
+            else:
+                self.assertGreater(err, 1.0, w)
+
+
+class WTheWire(TestCase):
+    def test_a_mono_source_is_a_wire(self):
+        for rate in RATES:
+            for seed in SEEDS[:2]:
+                for cell in w_mono_cells():
+                    self.assertEqual(
+                        w_differing(StereoWidener, rate, seed, 1, 1024,
+                                    **cell), 0, (rate, seed, cell))
+
+    def test_the_neutral_widths_are_wires(self):
+        for rate in RATES:
+            for seed in SEEDS:
+                self.assertEqual(w_differing(StereoWidener, rate, seed, 2,
+                                             width=0.0), 0, (rate, seed))
+                self.assertEqual(w_differing(StereoWidener, rate, seed, 2,
+                                             width=1.0,
+                                             character="mid_side"),
+                                 0, (rate, seed))
+
+    def test_fixed_copy_is_red(self):
+        self.assertGreater(w_differing(FixedCopy, 48000, 1, 2, width=0.0),
+                           1000)
+
+
+#: Every claim sentence of the class docstring and the test that holds it.
+CLAIMS = (
+    ("Width runs from 0 to 2, with its centre detent at 1.",
+     "test_the_spans"),
+    ("Delay runs from 1 to 40 ms, and only Haas uses it.",
+     ("test_the_spans", "test_delay_does_nothing_in_mid_side")),
+    ("At Width 1 the left channel passes untouched and the right channel is "
+     "your right channel, exactly Delay late.",
+     ("test_the_copy_is_the_right_exactly_delay_late",
+      "test_random_grid_delays", "test_copy_from_mid_is_red")),
+    ("Between Width 0 and 1 the right channel crossfades from itself to its "
+     "late copy, which colours it most at 0.5.",
+     ("test_width_moves_the_right_to_its_copy",
+      "test_the_comb_is_deepest_at_half_width", "test_backwards_pan_is_red")),
+    ("Width 0 is a wire.",
+     ("test_the_neutral_widths_are_wires", "test_fixed_copy_is_red")),
+    ("Above Width 1 the copy stays where it is and the left turns down, "
+     "6 dB at Width 2, to pull back the image the left's early arrival "
+     "leans its way.",
+     ("test_width_moves_the_right_to_its_copy", "test_six_db_down_at_width_2",
+      "test_the_right_half_above_width_1")),
+    ("Turning Delay glides the copy to the new time instead of clicking, "
+     "bending its pitch while it moves.",
+     ("test_a_delay_move_glides", "test_jump_delay_is_red")),
+    ("Haas folds to mono as a comb filter: at Width 1 with the default "
+     "14 ms, the mono sum has full-depth notches at 35.7, 107 and 179 Hz "
+     "and on up.",
+     ("test_the_mono_fold_notches",
+      "test_the_default_notches_are_where_the_text_says")),
+    ("Summed to mono, the output is the same at every Width, within one "
+     "LSB.",
+     ("test_the_sum_holds_and_the_side_follows", "test_at_the_mid_side_patches",
+      "test_level_width_is_red")),
+    ("Width 0 is mono, 1 is a wire and 2 doubles the sides.",
+     ("test_the_textbook_matrix", "test_the_neutral_widths_are_wires",
+      "test_the_sum_holds_and_the_side_follows")),
+    ("Above Width 1, a part panned hard left shows up inverted on the right.",
+     ("test_the_textbook_matrix", "test_late_matrix_is_red")),
+    ("A part that is the same in both channels comes out unchanged.",
+     "test_a_centred_part_is_unchanged"),
+    ("Peaks up to half of full scale never clip at any Width.",
+     "test_half_scale_never_clips"),
+    ("A one-channel source comes out exactly as it went in, whatever the "
+     "controls say.",
+     "test_a_mono_source_is_a_wire"),
+    ("A click in the left comes out on the frame it went in: there is no "
+     "latency.",
+     ("test_no_latency_in_either_character",
+      "test_width_moves_the_right_to_its_copy")),
+    ("`tail_samples` is the copy's reach in Haas, and 0 in Mid/Side or at "
+     "Width 0.",
+     ("test_tail_samples", "test_the_output_is_silent_after_the_tail")),
+    ("`reset()` empties the line and returns to patch 0.",
+     "test_reset_empties_the_line_and_returns_to_patch_0"),
+    ("The class never reads the host's tempo.",
+     "test_the_tempo_is_never_read"),
+    ("A control that jumps, Width or Character, makes the output step: move "
+     "it in small steps from the host if you need it smooth.",
+     "DECLARED:StereoWidener,E4-m0=,P5"),
+)
+
+
+# --------------------------------------------------------------------------
+# The figures on whichever interpreter runs this file
+
+
+def figures(seeds=SEEDS):
+    """Print each trait's numbers: the evidence pack's per-interpreter
+    rows."""
+    name = sys.implementation.name
+    for rate in RATES:
+        worst = [0, 0]
+        cells = 0
+        for seed in seeds:
+            for ms in (1.0, 5.0, 14.0, 30.0, 40.0):
+                left, right, _ = h1_read(StereoWidener, rate, seed,
+                                         delay_ms=ms)
+                worst[0] += left
+                worst[1] += right
+                cells += 1
+        tau = law_frames(14.0, rate)
+        notches = [fold_rms(StereoWidener, rate, notch_hz(rate, tau, k))
+                   for k in range(4)]
+        print("%s|H1|%d|cells %d|left differing %d|right differing %d|"
+              "fold notch rms max %.3f|peak %.1f"
+              % (name, rate, cells, worst[0], worst[1], max(notches),
+                 fold_rms(StereoWidener, rate, rate / tau)))
+        print("%s|H1-plant|%d|right differing %d" % (
+            name, rate, h1_read(CopyFromMid, rate, 1)[1]))
+        print("%s|H2|%d|worst err 1ms %.3f|14ms %.3f|plant %.1f" % (
+            name, rate, h2_errors(StereoWidener, rate, 1.0),
+            h2_errors(StereoWidener, rate, 14.0),
+            h2_errors(BackwardsPan, rate, 14.0)))
+        for up in (True, False):
+            ratios = []
+            lates = 0
+            for seed in seeds:
+                ratio, late = h3_read(StereoWidener, rate, seed, up)
+                ratios.append(ratio)
+                lates += late
+            print("%s|H3|%d|%s|ratio %.3f-%.3f|late mismatches %d|plant "
+                  "%.2f" % (name, rate, "up" if up else "down", min(ratios),
+                            max(ratios), lates,
+                            h3_read(JumpDelay, rate, 1, up)[0]))
+        sums = 0
+        sides = 0.0
+        for seed in seeds:
+            for w in M1_WIDTHS + (m1_random_width(seed),):
+                s, side = m1_read(StereoWidener, rate, seed, w)
+                sums = max(sums, s)
+                sides = max(sides, side)
+        plant = min(max(m1_read(LevelWidth, rate, 1, w)) for w in M1_WIDTHS
+                    if w != 1.0)
+        print("%s|M1|%d|sum worst %d|side worst %.4f|plant min %.1f"
+              % (name, rate, sums, sides, plant))
+        worst, inverted = m2_errors(StereoWidener, rate)
+        print("%s|M2|%d|worst %.3f|R' at 1.5, 2: %r" % (name, rate, worst,
+                                                          inverted))
+        mono = 0
+        for cell in w_mono_cells():
+            mono += w_differing(StereoWidener, rate, 1, 1, 1024, **cell)
+        stereo = 0
+        for seed in seeds:
+            stereo += w_differing(StereoWidener, rate, seed, 2, width=0.0)
+            stereo += w_differing(StereoWidener, rate, seed, 2, width=1.0,
+                                  character="mid_side")
+        print("%s|W|%d|mono differing %d|stereo differing %d|plant %d"
+              % (name, rate, mono, stereo,
+                 w_differing(FixedCopy, rate, 1, 2, width=0.0)))
+
+
+if __name__ == "__main__":
+    if unittest is not None and "--figures" not in sys.argv:
+        unittest.main()
+    else:
+        # By name, not as __main__: a plant reads VENDOR from the module
+        # that defines it, and natively __main__ is not one it can find.
+        import test_cpython_effects_stereowidener as module
+        module.figures()

From 7a057e0224aa602fd48768fe1dc3105d0beb5696 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:10:16 -0500
Subject: [PATCH 09/76] Node matrix: the pitch nodes' by-design cells

---
 tests/support/node_matrix.py | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
index 58c85b8..16f0d3e 100644
--- a/tests/support/node_matrix.py
+++ b/tests/support/node_matrix.py
@@ -445,6 +445,24 @@ def _apply_macro(self, index, position):
         "as E4: the line held at mix 0 plays when mix comes back",
     ("NodeEcho", "E9-", "P3"):
         "as E4, at every source buffer size",
+    ("NodePitchShift", "E2-", "P4"):
+        "reset_buffer restarts the splice phase, so the node matches a fresh"
+        " one, not the uninterrupted control",
+    ("NodePitchShift", "E4-m1", "P4"):
+        "a Semitones move runs the read position at another rate, so the"
+        " splice phase lands elsewhere; putting it back would click",
+    ("NodePitchShift", "E6-", "P4"):
+        "as E4: a patch with other semitones moves the splice phase",
+    ("NodePitchShift", "E11-", "P4"):
+        "as E4: moves before a pull move the splice phase",
+    ("NodeGranularPitchShift", "E1-", "P4"):
+        "a reset restarts the grain clock, so grains never line up with the"
+        " uninterrupted control again",
+    ("NodeGranularPitchShift", "E2-", "P4"):
+        "as E1: the host reset restarts the grain clock",
+    ("NodeGranularPitchShift", "E6-", "P4"):
+        "a Spread move to 0 draws no jitter, so the random sequence falls"
+        " behind the control's",
 }
 
 import lifecycle  # noqa: E402

From a95af9f8c362f13ffcb94263abdd409cd29a0df6 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:16:14 -0500
Subject: [PATCH 10/76] One path for a patch and a restore:
 Component._apply_positions

program_change's body moves into a private _apply_positions(positions,
patch_index), which program_change calls with a patch's positions. A rack
calls it to put a child back exactly as it built it, which the public
set_macro cannot do for a measured ConvolutionReverb or a setting off the
0-127 grid. The classes that wrapped program_change to do work once per
patch (the deferred refreshes, the lean re-routes, GraphicEQ's clean bank,
the old Reverb's single rebuild) now wrap _apply_positions, so a patch and
a restore take the same path. The test plants that stood for the base's
per-macro path move with them.
---
 lib/audioeffects/_component.py                | 25 +++++++++++++++----
 lib/audioeffects/_core.py                     | 16 +++++++++---
 lib/audioeffects/compressor.py                |  5 ++--
 lib/audioeffects/fuzz.py                      |  6 ++---
 lib/audioeffects/graphiceq.py                 | 15 +++--------
 lib/audioeffects/rebuilt/analogdelay.py       | 12 ++++-----
 lib/audioeffects/rebuilt/convolutionreverb.py | 11 ++++----
 lib/audioeffects/rebuilt/digitaldelay.py      | 12 ++++-----
 lib/audioeffects/rebuilt/multitapdelay.py     | 12 ++++-----
 lib/audioeffects/rebuilt/pingpongdelay.py     | 12 ++++-----
 lib/audioeffects/rebuilt/reverb.py            | 12 ++++-----
 lib/audioeffects/rebuilt/slapbackdelay.py     | 12 ++++-----
 lib/audioeffects/rebuilt/tapedelay.py         | 12 ++++-----
 lib/audioeffects/reverb.py                    |  9 ++-----
 lib/audioeffects/saturation.py                |  6 ++---
 tests/test_cpython_effects_analogdelay.py     |  5 +---
 tests/test_cpython_effects_digitaldelay.py    |  2 +-
 tests/test_cpython_effects_graphiceq.py       | 11 +++++---
 18 files changed, 93 insertions(+), 102 deletions(-)

diff --git a/lib/audioeffects/_component.py b/lib/audioeffects/_component.py
index 09bd800..909be61 100644
--- a/lib/audioeffects/_component.py
+++ b/lib/audioeffects/_component.py
@@ -1027,11 +1027,26 @@ def program_change(self, index, channel=0, note_id=-1,
         patch = type(self).PATCHES.get(index)
         if patch is None:
             return
-        for macro in range(len(patch[1])):
-            self._macros[macro] = position_of_midi(self._mode(macro),
-                                                   patch[1][macro])
-            self._apply_macro(macro, self._macros[macro])
-        self._patch_index = index
+        self._apply_positions([position_of_midi(self._mode(macro), value)
+                               for macro, value in enumerate(patch[1])],
+                              index)
+
+    def _apply_positions(self, positions, patch_index):
+        """Set the macros to `positions` (0..1, one per macro from index 0),
+        apply each, and record `patch_index`.
+
+        This is the body of `program_change`, and the one path a patch and a
+        restore share: a rack puts a child back as it built it by handing
+        this the positions and patch index it recorded, which the public
+        `set_macro` cannot do for a class whose grid is coarser than its
+        positions or whose macros are not all live. A class that does work
+        once per patch (a refresh, a re-route) does it here, not in
+        `program_change`, so both paths get it.
+        """
+        for macro in range(len(positions)):
+            self._macros[macro] = positions[macro]
+            self._apply_macro(macro, positions[macro])
+        self._patch_index = patch_index
 
     def pitch_bend(self, value, channel=0, sample_position=0):
         self._check_live()
diff --git a/lib/audioeffects/_core.py b/lib/audioeffects/_core.py
index 46b3fea..87d067a 100644
--- a/lib/audioeffects/_core.py
+++ b/lib/audioeffects/_core.py
@@ -368,10 +368,18 @@ def program_change(self, index, channel=0, note_id=-1,
         patch = self.PATCHES.get(index)
         if patch is None:
             return
-        for macro, value in enumerate(patch[1]):
-            self._macros[macro] = min(1.0, max(0.0, float(value) / 127.0))
-            self._apply_macro(macro, self._macros[macro])
-        self._patch_index = index
+        self._apply_positions([min(1.0, max(0.0, float(value) / 127.0))
+                               for value in patch[1]], index)
+
+    def _apply_positions(self, positions, patch_index):
+        """Set the macros to `positions` (0..1), apply each, and record
+        `patch_index`: `program_change`'s body, which a rack also calls to
+        put a child back as it built it (`_component.Component`'s
+        counterpart says why)."""
+        for macro in range(len(positions)):
+            self._macros[macro] = positions[macro]
+            self._apply_macro(macro, positions[macro])
+        self._patch_index = patch_index
 
     def macro(self, index):
         """What macro `index` currently stands for, in its own units."""
diff --git a/lib/audioeffects/compressor.py b/lib/audioeffects/compressor.py
index 58cb305..e9ec578 100644
--- a/lib/audioeffects/compressor.py
+++ b/lib/audioeffects/compressor.py
@@ -486,9 +486,8 @@ def _push_emphasis(self):
         else:
             self._fast.set(sidechain_hz=self._hz(self.macro(11) * emphasis))
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        super().program_change(index, channel, note_id, sample_position)
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
         self._route()
 
     def _lean(self):
diff --git a/lib/audioeffects/fuzz.py b/lib/audioeffects/fuzz.py
index caa63d2..1ebc574 100644
--- a/lib/audioeffects/fuzz.py
+++ b/lib/audioeffects/fuzz.py
@@ -1016,10 +1016,8 @@ def _rearm(self):
             self._tone_mix.voice[1].play(self._tone_hp)
             self._tone_mix.voice[2].play(self._dry)
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        _component.Component.program_change(self, index, channel, note_id,
-                                            sample_position)
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
         self._route()
         self._refresh_output()
 
diff --git a/lib/audioeffects/graphiceq.py b/lib/audioeffects/graphiceq.py
index f4fe4b4..a7fe9ab 100644
--- a/lib/audioeffects/graphiceq.py
+++ b/lib/audioeffects/graphiceq.py
@@ -411,9 +411,9 @@ def _level(self, node, index):
         node.gain_db = gain_db
         node.mix = 1.0
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Jump to a patch, and start the new curve from a clean bank.
+    def _apply_positions(self, positions, patch_index):
+        """Jump to a patch (or a rack's restore), and start the new curve
+        from a clean bank.
 
         The difference between this and `set_macro` is deliberate, and it is
         the difference between a jump and a sweep. A slider being pushed
@@ -424,16 +424,9 @@ def program_change(self, index, channel=0, note_id=-1,
         peaks at **32767 and stays above its own steady level for 306 ms**
         without this, and at **5826 for 8 ms** with it.
         """
-        if type(self).PATCHES.get(index) is None:
-            return _component.Component.program_change(
-                self, index, channel=channel, note_id=note_id,
-                sample_position=sample_position)
-        result = _component.Component.program_change(
-            self, index, channel=channel, note_id=note_id,
-            sample_position=sample_position)
+        _component.Component._apply_positions(self, positions, patch_index)
         for node in self._nodes:
             node.clear()
-        return result
 
     @property
     def tail_samples(self):
diff --git a/lib/audioeffects/rebuilt/analogdelay.py b/lib/audioeffects/rebuilt/analogdelay.py
index e10dcbc..0581cba 100644
--- a/lib/audioeffects/rebuilt/analogdelay.py
+++ b/lib/audioeffects/rebuilt/analogdelay.py
@@ -413,18 +413,16 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh once, so Time is read
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh once, so Time is read
         against the new patch's Sync and moves (and walks) once."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def reset(self):
         _component.Component.reset(self)
diff --git a/lib/audioeffects/rebuilt/convolutionreverb.py b/lib/audioeffects/rebuilt/convolutionreverb.py
index a8baaff..5780aaf 100644
--- a/lib/audioeffects/rebuilt/convolutionreverb.py
+++ b/lib/audioeffects/rebuilt/convolutionreverb.py
@@ -471,20 +471,19 @@ def _refresh(self):
         # halving is a power of two, so it adds no rounding of its own.
         self._node.set(mix=self._value(MIX_I) * 0.5)
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then synthesize once. In measured
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then synthesize once. In measured
         mode only its Mix is audible; the synthesis positions are stored
         and inert. Inside the constructor the one synthesis is the
         constructor's own."""
         outer = self._deferred
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = outer
-        if not outer and type(self).PATCHES.get(index) is not None:
+        if not outer:
             self._refresh()
 
     def _macro_index(self, index):
diff --git a/lib/audioeffects/rebuilt/digitaldelay.py b/lib/audioeffects/rebuilt/digitaldelay.py
index e8e8cfd..f44b2f1 100644
--- a/lib/audioeffects/rebuilt/digitaldelay.py
+++ b/lib/audioeffects/rebuilt/digitaldelay.py
@@ -514,20 +514,18 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh once. The base applies
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh once. The base applies
         the macros in index order, so a refresh per macro would read Time
         against the outgoing patch's Sync and, with a host transport, keep
         its synced Time instead of the new patch's own."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def reset(self):
         _component.Component.reset(self)
diff --git a/lib/audioeffects/rebuilt/multitapdelay.py b/lib/audioeffects/rebuilt/multitapdelay.py
index 209b40d..1a1bfce 100644
--- a/lib/audioeffects/rebuilt/multitapdelay.py
+++ b/lib/audioeffects/rebuilt/multitapdelay.py
@@ -564,19 +564,17 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh once, so Time is never
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh once, so Time is never
         read against the outgoing patch's Sync and the graph re-plugs at
         most once."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def _refresh(self):
         rate = self._sample_rate
diff --git a/lib/audioeffects/rebuilt/pingpongdelay.py b/lib/audioeffects/rebuilt/pingpongdelay.py
index 500fcee..7f9d42b 100644
--- a/lib/audioeffects/rebuilt/pingpongdelay.py
+++ b/lib/audioeffects/rebuilt/pingpongdelay.py
@@ -380,18 +380,16 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the node once. A refresh
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh the node once. A refresh
         per macro would read Time against the outgoing patch's Sync."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def reset(self):
         _component.Component.reset(self)
diff --git a/lib/audioeffects/rebuilt/reverb.py b/lib/audioeffects/rebuilt/reverb.py
index cb5ef91..9bcb6fe 100644
--- a/lib/audioeffects/rebuilt/reverb.py
+++ b/lib/audioeffects/rebuilt/reverb.py
@@ -461,18 +461,16 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the Tank once, so a
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh the Tank once, so a
         patch that moves Character and Size rebuilds it once."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def _refresh(self):
         fs = self._sample_rate
diff --git a/lib/audioeffects/rebuilt/slapbackdelay.py b/lib/audioeffects/rebuilt/slapbackdelay.py
index 59bb943..015a208 100644
--- a/lib/audioeffects/rebuilt/slapbackdelay.py
+++ b/lib/audioeffects/rebuilt/slapbackdelay.py
@@ -323,17 +323,15 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the node once."""
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh the node once."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def reset(self):
         _component.Component.reset(self)
diff --git a/lib/audioeffects/rebuilt/tapedelay.py b/lib/audioeffects/rebuilt/tapedelay.py
index dcc53a5..41463a7 100644
--- a/lib/audioeffects/rebuilt/tapedelay.py
+++ b/lib/audioeffects/rebuilt/tapedelay.py
@@ -604,18 +604,16 @@ def _apply_macro(self, index, position):
         if not self._deferred:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the node once, so Time
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh the node once, so Time
         is read against the new patch's Sync and moves once."""
         self._deferred = True
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._deferred = False
-        if type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        self._refresh()
 
     def reset(self):
         _component.Component.reset(self)
diff --git a/lib/audioeffects/reverb.py b/lib/audioeffects/reverb.py
index ce5dca9..f63dc1b 100644
--- a/lib/audioeffects/reverb.py
+++ b/lib/audioeffects/reverb.py
@@ -162,17 +162,12 @@ def decay_seconds(self):
     def set_mix(self, mix):
         self.node.set(mix=mix)
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
+    def _apply_positions(self, positions, patch_index):
         # Suppress the per-macro rebuild and do one at the end. A patch moves
         # every knob, and four of the five reshape the impulse.
-        if int(index) not in self.PATCHES:
-            return
         self._ready = False
         try:
-            _core.Effect.program_change(self, index, channel=channel,
-                                         note_id=note_id,
-                                         sample_position=sample_position)
+            _core.Effect._apply_positions(self, positions, patch_index)
         finally:
             self._ready = True
         self._rebuild()
diff --git a/lib/audioeffects/saturation.py b/lib/audioeffects/saturation.py
index d055278..8c0a5f8 100644
--- a/lib/audioeffects/saturation.py
+++ b/lib/audioeffects/saturation.py
@@ -1189,10 +1189,8 @@ def _rearm(self):
             self._silence)
         self._attached = False
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        _component.Component.program_change(self, index, channel, note_id,
-                                            sample_position)
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
         self._route()
         self._refresh_output()
 
diff --git a/tests/test_cpython_effects_analogdelay.py b/tests/test_cpython_effects_analogdelay.py
index 328c602..e24c6a4 100644
--- a/tests/test_cpython_effects_analogdelay.py
+++ b/tests/test_cpython_effects_analogdelay.py
@@ -430,10 +430,7 @@ class PerMacroPatch(AnalogDelay):
 
     NAME = 'AnalogDelay'
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        _component.Component.program_change(self, index, channel, note_id,
-                                            sample_position)
+    _apply_positions = _component.Component._apply_positions
 
 
 # --------------------------------------------------------------------------
diff --git a/tests/test_cpython_effects_digitaldelay.py b/tests/test_cpython_effects_digitaldelay.py
index fe87b2e..1b539cf 100644
--- a/tests/test_cpython_effects_digitaldelay.py
+++ b/tests/test_cpython_effects_digitaldelay.py
@@ -650,7 +650,7 @@ class PerMacroPatchDelay(DigitalDelay):
     Time is read against the outgoing patch's Sync."""
 
     NAME = 'DigitalDelay'
-    program_change = _component.Component.program_change
+    _apply_positions = _component.Component._apply_positions
 
 
 # --------------------------------------------------------------------------
diff --git a/tests/test_cpython_effects_graphiceq.py b/tests/test_cpython_effects_graphiceq.py
index 7bbbd2e..b078758 100644
--- a/tests/test_cpython_effects_graphiceq.py
+++ b/tests/test_cpython_effects_graphiceq.py
@@ -710,10 +710,13 @@ def _transition(self, before, after, clear=True):
             if clear:
                 effect.program_change(after)
             else:
-                # The planted fault: the contract's own program_change,
-                # which leaves every section holding the old curve.
-                audioeffects._component.Component.program_change(
-                    effect, after)
+                # The planted fault: the contract's own patch body, which
+                # leaves every section holding the old curve.
+                component = audioeffects._component
+                audioeffects._component.Component._apply_positions(
+                    effect, [component.position_of_midi(effect._mode(m), v)
+                             for m, v in enumerate(
+                                 type(effect).PATCHES[after][1])], after)
             post = render(effect.output, 48000)
         finally:
             effect.deinit()

From 265982d5af1b21aa9883c9a69873d389f30eeadd Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:16:15 -0500
Subject: [PATCH 11/76] Rack (rebuilt): the serial chain on the contract's base

rebuilt/rack.py beside the old class. The chain renders exactly the same
pedals patched by hand; latency_samples and tail_samples are live sums;
reset() is each child's reset then patch 0, which puts every child back as
built; deinit() releases every child and a failed build releases what it
built; children get the rack's transport and transport_changed() reaches
nested racks; capabilities is the union of the children's. Tests for T1-T6
with their planted faults, the CLAIMS table and KIT_PLANTS.

The kit runs Rack on the probe chain K (KIT_OPTIONS), and the lifecycle
CLI reads the same table; the lifecycle skips its macro events for a class
with no macros. Declared: the plant cells whose faults no render reaches,
ConvolutionReverb's own 0 dBFS sine ceiling, and the E1 P4 cells Vibrato
and Fuzz are red on alone.
---
 CHANGELOG.md                       |   12 +
 lib/audioeffects/rebuilt/rack.py   |  202 +++++
 tests/support/kit_common.py        |   16 +
 tests/support/kit_options.py       |    9 +-
 tests/support/lifecycle.py         |   15 +-
 tests/test_cpython_effects_rack.py | 1258 ++++++++++++++++++++++++++++
 6 files changed, 1507 insertions(+), 5 deletions(-)
 create mode 100644 lib/audioeffects/rebuilt/rack.py
 create mode 100644 tests/test_cpython_effects_rack.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..806b807 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,18 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`Rack` (rebuilt, Phase 6):** the serial chain on the contract's base, in
+  `rebuilt/rack.py` beside the old class, which stays until the rebuild is
+  promoted. `chain=` keeps its meaning and also takes a bare effect class. It
+  renders exactly the same pedals patched by hand; `latency_samples` and
+  `tail_samples` are live sums; `reset()` clears every pedal and puts each
+  back to the settings the rack built it with; `deinit()` releases every
+  pedal, and a chain that fails part-way releases what it built; each pedal
+  gets the rack's transport and `transport_changed()` reaches nested racks;
+  `capabilities` is the union of the pedals'. `effects` is a tuple. Patches
+  and a rack's restore now share one private path in the base,
+  `_apply_positions`, which the classes that did work once per patch moved
+  onto.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/rack.py b/lib/audioeffects/rebuilt/rack.py
new file mode 100644
index 0000000..1a34a26
--- /dev/null
+++ b/lib/audioeffects/rebuilt/rack.py
@@ -0,0 +1,202 @@
+"""`Rack` - a serial chain of effects, as a single effect.
+
+The player's text is the class docstring, and the sentences in it that make
+a claim are tied to tests by the `CLAIMS` table in the class's test file.
+"""
+
+VENDOR = "PyDevices"
+
+from .. import _component
+
+
+class Rack(_component.Component):
+    """A pedalboard cable run: name the effects in order and get a single
+    effect back.
+
+    For example:
+
+        rack = Rack.create(source, 48000, chain=(
+            ("Fuzz", {}),
+            ("DigitalDelay", {"mix": 0.3, "feedback": 0.4}),
+            ("ConvolutionReverb", {}),
+        ))
+        audio_out.play(rack.output)
+
+    `chain` is a tuple of entries, each an effect name, a `(name, options)`
+    pair whose options are that effect's constructor keywords, or an effect
+    class in place of a name. `("Rack", {"chain": ...})` nests a rack.
+
+    A rack adds no sound of its own: it sounds exactly like the same pedals
+    patched by hand, one into the next. Empty, it is a patch cable, and its
+    output is your source. A mono source gives a mono rack.
+
+    Order matters as soon as one pedal isn't a plain filter: drive into a
+    reverb isn't a reverb into drive.
+
+    `latency_samples` and `tail_samples` are the sums of the pedals' own,
+    read live, so they follow a pedal's knobs; the tail is `None` as soon as
+    one pedal's is.
+
+    There is no rack Mix, Bypass or Output knob, and patch 0 is its only
+    patch. Turn a pedal's own Mix down; `ShimmerHall` and `AirSpace` are
+    racks with knobs. The chain is set when the rack is built: to change
+    pedals, build a new rack. To turn a pedal's knob, reach it through
+    `rack.effects`, a tuple of the pedals in chain order.
+
+    `reset()` clears every pedal and puts each back to the settings the
+    rack built it with, undoing knob moves made since. `program_change(0)`
+    does the putting back alone, without clearing anything.
+
+    A host's `audiocore.reset_buffer(rack.output)` clears the last pedal
+    only, and on an empty rack it rewinds your own source, because the
+    output is your source. Call `rack.reset()` instead.
+
+    A tempo-synced pedal follows the song's tempo wherever it sits, nested
+    racks included: each pedal gets the rack's transport unless its entry
+    names its own, and `transport_changed()` reaches every pedal.
+    `capabilities` is the union of the pedals' own, set when the rack is
+    built.
+
+    A rack builds nothing of its own, so it costs what its pedals cost.
+    Heavy pedals add up quickly on a small board: if the sound breaks up,
+    trim the chain. The class itself runs on a stock board; a built rack
+    needs whatever modules its pedals need.
+
+    `deinit()` releases every pedal, nested racks included, and never your
+    source. If an entry fails to build, the pedals built before it are
+    released before the error reaches you.
+    """
+
+    NAME = 'Rack'
+    DISPLAY_NAME = 'Effect Rack'
+    CATEGORIES = ('Effect Rack',)
+    VERSION = '0.1.0'
+
+    TIER = _component.STOCK
+
+    MACRO_LABELS = ()
+    MACRO_MODES = {}
+    _MACRO_RANGES = ()
+    PATCHES = {0: ("Default", ())}
+
+    def _build(self, chain=(), patch=None):
+        built = []
+        tail = self._source
+        try:
+            for entry in chain:
+                name, options = _entry(entry)
+                child = self._child(name, tail, options)
+                built.append(child)
+                tail = child.output
+        except BaseException:
+            # The constructor never returns, so nobody else can release
+            # what was built: do it here, tail first, and re-raise.
+            for child in reversed(built):
+                child.deinit()
+            raise
+        self._effects = tuple(built)
+        # What patch 0 restores: each child's positions, whole, and its
+        # patch index, as the rack built it.
+        self._built = tuple((list(child._macros), child._patch_index)
+                            for child in built)
+        capabilities = []
+        for child in built:
+            for capability in child.capabilities:
+                if capability not in capabilities:
+                    capabilities.append(capability)
+        self._capabilities = tuple(capabilities)
+        # No port of its own: the rack's output IS the last child's output
+        # (its port), and an empty rack's IS the source. Set directly,
+        # around the `_output` property, which would wrap it in a new port.
+        self._port = tail
+        self._init_macros((), patch)
+
+    def _child(self, name, source, options):
+        """One chain entry built around `source`, with the rack's transport
+        unless the entry names its own."""
+        transport = options.pop("transport", self._transport)
+        if isinstance(name, str):
+            if name == Rack.NAME:
+                name = Rack
+            else:
+                import audioeffects
+                return audioeffects.create(name, source, self._sample_rate,
+                                           transport=transport, **options)
+        return name.create(source, self._sample_rate, transport=transport,
+                           **options)
+
+    # -- the reads ------------------------------------------------------
+
+    @property
+    def effects(self):
+        """The children, in chain order."""
+        self._check_live()
+        return self._effects
+
+    @property
+    def latency_samples(self):
+        self._check_live()
+        total = 0
+        for child in self._effects:
+            total += child.latency_samples
+        return total
+
+    @property
+    def tail_samples(self):
+        self._check_live()
+        total = 0
+        for child in self._effects:
+            tail = child.tail_samples
+            if tail is None:
+                return None
+            total += tail
+        return total
+
+    @property
+    def capabilities(self):
+        self._check_live()
+        return self._capabilities
+
+    # -- the surface ----------------------------------------------------
+
+    def _apply_positions(self, positions, patch_index):
+        """Patch 0: every child back to the positions and patch index the
+        rack built it with. A nested rack restores inside itself."""
+        _component.Component._apply_positions(self, positions, patch_index)
+        for child, (macros, index) in zip(self._effects, self._built):
+            child._apply_positions(list(macros), index)
+
+    def transport_changed(self):
+        self._check_live()
+        for child in self._effects:
+            child.transport_changed()
+
+    def reset(self):
+        """Each child's own reset, tail first, then patch 0. The borrowed
+        source is never named."""
+        self._check_live()
+        for child in reversed(self._effects):
+            child.reset()
+        _component.Component.reset(self)
+
+    def deinit(self):
+        """Every child's own deinit, tail first. The port is never released
+        here: it is the last child's, or, for an empty rack, the source."""
+        if self._deinited:
+            return
+        for child in reversed(self._effects):
+            child.deinit()
+        self._port = None
+        self._deinited = True
+
+
+def _entry(entry):
+    """(name or class, options dict) for one chain entry."""
+    if isinstance(entry, (str, type)):
+        return entry, {}
+    try:
+        name, options = entry
+    except (TypeError, ValueError):
+        raise ValueError("a chain entry is a NAME, an effect class or a "
+                         "(NAME, options) pair, not %r" % (entry,))
+    return name, dict(options)
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..7eca674 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,22 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("Rack", "plants", "T1/"):
+        "T1's faults are the empty rack's identity and its port, which a"
+        " render at the probe chain cannot see; the trait test holds them red",
+    ("Rack", "plants", "T4/"):
+        "T4's faults live in reset() and patch 0, which the plant render"
+        " never calls; the trait test holds them red",
+    ("Rack", "plants", "T5/"):
+        "T5's faults live in deinit() and a failed build, which the plant"
+        " render never reaches; the trait test holds them red",
+    ("Rack", "plants", "T6/"):
+        "T6's faults need a host transport and a tempo change, which the"
+        " plant render does not give; the trait test holds them red",
+    ("Rack", "ceiling", "sine/48000/2/"):
+        "the probe chain ends in ConvolutionReverb, which rails this 0 dBFS"
+        " sine at its own defaults (its own ceiling cell sine/48000/2/d); a"
+        " rack is exactly its pedals",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/kit_options.py b/tests/support/kit_options.py
index 4c4fb74..120abbc 100644
--- a/tests/support/kit_options.py
+++ b/tests/support/kit_options.py
@@ -6,8 +6,13 @@
 """
 
 KIT_OPTIONS = {
-    # Filled with a real chain when the Rack's kit run is set up.
-    "Rack": {"chain": ()},
+    # The Rack card's probe chain K: a nested rack, a delay line mid-chain,
+    # latency in three children, finite tails and one tempo-synced child.
+    "Rack": {"chain": (
+        ("Fuzz", {}),
+        ("Rack", {"chain": (("DigitalDelay", {"mix": 0.3, "feedback": 0.4}),
+                            ("Vibrato", {}))}),
+        ("ConvolutionReverb", {}))},
 }
 
 
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..3375c81 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,6 +75,10 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
+    ("Rack", "E1-", "P4"):
+        "a rack is exactly its pedals, and two of the probe chain's are E1 P4"
+        " red alone at their defaults, Vibrato ('differs at +4917, bound"
+        " +2870' at 48 kHz stereo) and Fuzz ('+26883, bound +24836')",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
@@ -549,15 +553,17 @@ def events(cls, patch, quick=False):
     out.append(Event("E10-patch", [("patch", npatch - 1 if patch != npatch - 1
                                     else 0)], [("restore",)],
                      moves_mix=True, first=True))
-    if full:
+    if full and labels:
         out.append(Event("E11-2macro", [("macro", 0, 0), ("macro", 0, 127)],
                          [("restore",)], moves_mix=(mix == 0)))
         if mix is not None:
             out.append(Event("E11-mix+patch",
                              [("macro", mix, 0), ("patch", npatch - 1)],
                              [("restore",)], moves_mix=True))
+    if full:
         out.append(Event("E11-2patch", [("patch", npatch - 1), ("patch", 0)],
                          [("restore",)], moves_mix=True))
+    if full and labels:
         out.append(Event("E11-3moves",
                          [("macro", 0, 0), ("macro", 0, 127),
                           ("patch", npatch - 1)],
@@ -1339,8 +1345,11 @@ def _cli(argv):
             if cls is None:
                 print("MISSING|%s" % name)
                 continue
-        run_class(cls, only=only, quick=quick, name=name if name in PLANTS
-                  else None)
+        # The kit's options table: a class whose defaults are trivial (the
+        # generic Rack's empty chain) runs on something real.
+        import kit_options
+        run_class(cls, options=kit_options.options_for(cls.NAME), only=only,
+                  quick=quick, name=name if name in PLANTS else None)
     print("DONE")
 
 
diff --git a/tests/test_cpython_effects_rack.py b/tests/test_cpython_effects_rack.py
new file mode 100644
index 0000000..0a76c3a
--- /dev/null
+++ b/tests/test_cpython_effects_rack.py
@@ -0,0 +1,1258 @@
+"""The rebuilt `Rack`: a serial chain of effects as one effect.
+
+One test per trait of the class card (T1-T6), each shown red on the card's
+planted faults, and the `CLAIMS` table that ties every claim in the class
+docstring to a test. Numpy-free: the planted classes and the trait checks
+import on MicroPython and CircuitPython too, and T5 runs on all three
+interpreters (`python tests/test_cpython_effects_rack.py` natively, from the
+repository root with `MICROPYPATH=lib:tests/support`).
+
+Most traits run on the card's probe chain K, which has a nested rack, a
+delay line mid-chain, latency in three children and one tempo-synced
+child. Every K check first asserts four leaves and a nonzero latency, so a
+rack that builds nothing fails rather than passes. Expected sums and node
+lists come from the same leaves built by hand, never from `rack.effects`.
+"""
+
+import os
+import sys
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                          # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    from array import array
+except ImportError:                          # pragma: no cover
+    array = None
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+elif sys.implementation.name == "cpython":
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.dirname(_HERE))       # for `tools`
+
+import audiocore
+import audioeffects
+from audioeffects import _component
+from audioeffects import rebuilt
+
+VENDOR = "PyDevices"
+
+Rack = rebuilt.module_class("Rack")
+
+CPYTHON = sys.implementation.name == "cpython"
+RATES = (48000, 22050)
+CHANNELS = (2, 1)
+SEEDS = (1, 2, 3, 4, 5, 6, 7, 8)
+BLOCK = 256
+
+K = (("Fuzz", {}),
+     ("Rack", {"chain": (("DigitalDelay", {"mix": 0.3, "feedback": 0.4}),
+                         ("Vibrato", {}))}),
+     ("ConvolutionReverb", {}))
+
+#: K's leaves, in order, and the macros the card moves.
+FUZZ, DELAY, VIBRATO, REVERB = range(4)
+FUZZ_FUZZ = 0
+FUZZ_MIX = 5
+DELAY_FEEDBACK = 1
+VIBRATO_DELAY = 4
+
+
+def impulse():
+    """2000 frames, int16 mono, clicks at 0, 700 and 1500."""
+    ir = array("h", bytes(4000))
+    ir[0] = 16384
+    ir[700] = 8192
+    ir[1500] = 4096
+    return ir
+
+
+#: A child built at a setting off the 0-127 grid (Reverb's Size 1.0), which
+#: patch 0 must put back exactly, not on the grid.
+OFF_GRID = (("Reverb", {"character": "chamber", "size": 1.0}),
+            ("DigitalDelay", {"mix": 0.3}))
+
+
+def c2():
+    return (("CabinetSim", {}), ("ConvolutionReverb", {"impulse": impulse()}))
+
+
+# --------------------------------------------------------------------------
+# Material and rendering (the same protocol as kit_probes, numpy-free)
+
+
+class Source:
+    """int16 frames, BLOCK of them per `get_buffer`, counting rewinds."""
+
+    def __init__(self, data, rate, channels):
+        self.sample_rate = rate
+        self.channel_count = channels
+        self.bits_per_sample = 16
+        self.samples_signed = True
+        self._pcm = bytes(data)
+        self._stride = BLOCK * channels * 2
+        self._position = 0
+        self.rewinds = 0
+
+    def _reset_buffer(self, single_channel_output=False, audio_channel=0):
+        self.rewinds += 1
+        self._position = 0
+
+    def _get_buffer(self, single_channel_output=False, audio_channel=0):
+        chunk = self._pcm[self._position:self._position + self._stride]
+        self._position += len(chunk)
+        return (1 if self._position < len(self._pcm) else 0), chunk
+
+
+class Switchable:
+    """The rack's borrowed source, with a different source behind it.
+    `swap` rewinds the new inner source itself, so `rewinds` counts only
+    what the rack asked of the source it holds."""
+
+    def __init__(self, inner):
+        self.inner = inner
+        self.sample_rate = inner.sample_rate
+        self.channel_count = inner.channel_count
+        self.bits_per_sample = 16
+        self.samples_signed = True
+        self.rewinds = 0
+
+    def swap(self, source):
+        self.inner = source
+
+    def _reset_buffer(self, single_channel_output=False, audio_channel=0):
+        self.rewinds += 1
+        self.inner._reset_buffer(single_channel_output, audio_channel)
+
+    def _get_buffer(self, single_channel_output=False, audio_channel=0):
+        return self.inner._get_buffer(single_channel_output, audio_channel)
+
+
+def noise_det(frames, seed, channels, dbfs=-12.0):
+    """kit_probes.noise_det, the same bytes on every interpreter."""
+    amplitude = 10 ** (dbfs / 20.0) * 32767.0
+    state = seed
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(frames):
+        state = (1103515245 * state + 12345) & 0x7fffffff
+        value = int(round(amplitude * ((state / 0x3fffffff) - 1.0)))
+        for ch in range(channels):
+            out[i * channels + ch] = value
+    return out
+
+
+def material(seed, channels, frames=48000):
+    """4096 frames of silence, 8192 of noise at -12 dBFS, then silence."""
+    out = array("h", bytes(2 * frames * channels))
+    burst = noise_det(8192, seed, channels)
+    start = 4096 * channels
+    for i in range(min(len(burst), len(out) - start)):
+        out[start + i] = burst[i]
+    return out
+
+
+def clicks(frames, channels, at, level=16384):
+    out = array("h", bytes(2 * frames * channels))
+    for frame in at:
+        for ch in range(channels):
+            out[frame * channels + ch] = level
+    return out
+
+
+def pull(node, frames, channels):
+    """`frames` frames of `node` as bytes, padded with silence when it runs
+    dry."""
+    want = frames * channels * 2
+    out = bytearray()
+    while len(out) < want:
+        data = bytes(audiocore.get_buffer(node)[1])
+        if not data:
+            out.extend(bytes(want - len(out)))
+            break
+        out.extend(data)
+    return bytes(out[:want])
+
+
+def fnv(data):
+    """FNV-1a, 32 bits."""
+    h = 0x811c9dc5
+    for byte in data:
+        h = ((h ^ byte) * 0x01000193) & 0xFFFFFFFF
+    return h
+
+
+def samples(data):
+    values = array("h")
+    try:
+        values.frombytes(bytes(data))
+        return values
+    except AttributeError:                       # MicroPython's array
+        pass
+    import struct
+    values.extend(struct.unpack("<%dh" % (len(data) // 2), bytes(data)))
+    return values
+
+
+def silent(data):
+    return not any(data)
+
+
+# --------------------------------------------------------------------------
+# The same leaves, by hand
+
+
+def hand(source, rate, chain, transport=None):
+    """(leaves, output): each leaf built around the previous output, a
+    nested rack's entries inline."""
+    leaves = []
+    out = source
+    for entry in chain:
+        if isinstance(entry, str):
+            name, options = entry, {}
+        else:
+            name, options = entry
+        if name == "Rack":
+            inner, out = hand(out, rate, options.get("chain", ()), transport)
+            leaves.extend(inner)
+            continue
+        leaf = audioeffects.create(name, out, rate, transport=transport,
+                                   **dict(options))
+        leaves.append(leaf)
+        out = leaf.output
+    return leaves, out
+
+
+def leaves(rack):
+    """The leaf effects of a rack, nested racks walked in order."""
+    found = []
+    for child in rack.effects:
+        if isinstance(child, Rack):
+            found.extend(leaves(child))
+        else:
+            found.append(child)
+    return found
+
+
+def release(effects):
+    for effect in reversed(effects):
+        effect.deinit()
+
+
+def live_reads(leaf):
+    """{macro index: get_macro} over the indices this leaf has live."""
+    reads = {}
+    for index in range(len(type(leaf).MACRO_LABELS)):
+        try:
+            reads[index] = leaf.get_macro(index)
+        except IndexError:
+            pass
+    return reads
+
+
+def state_of(leaf):
+    return (list(leaf._macros), leaf.patch_index, live_reads(leaf))
+
+
+def is_released(node):
+    """Released on this interpreter: the CPython twins mark `_deinited`; a
+    native node raises on a guarded getter."""
+    if getattr(node, "_deinited", False):
+        return True
+    try:
+        node.channel_count
+    except Exception:                                # noqa: BLE001
+        return True
+    return False
+
+
+#: What `nodes_of` left out because it has no `deinit` on this interpreter
+#: (Vibrato's ramp tap and splitter output, Python objects on CPython): named
+#: in the evidence, not claimed.
+NO_DEINIT = set()
+
+#: How many nodes T5's last clean run found through the rack.
+COUNTED = []
+
+
+def nodes_of(leaf):
+    """The nodes a leaf built that can be released: on CPython the kit's
+    enumeration (its register and anything outside it), natively the
+    register."""
+    if CPYTHON:
+        from tools.effect_measurements import enumerate_nodes
+        found = enumerate_nodes(leaf)
+    else:
+        found = [("_nodes[%d]" % i, node)
+                 for i, node in enumerate(leaf._nodes)]
+    nodes = []
+    for name, node in found:
+        if hasattr(node, "deinit"):
+            nodes.append(node)
+        else:
+            NO_DEINIT.add("%s.%s" % (type(leaf).NAME, name))
+    return nodes
+
+
+# --------------------------------------------------------------------------
+# The planted faults
+
+
+class MixerRack(Rack):
+    """T1: an empty rack wraps its source in a one-voice unity Mixer."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, chain, patch)
+        if not self._effects:
+            import audiomixer
+            mixer = audiomixer.Mixer(voice_count=1, **self._pcm(BLOCK))
+            mixer.voice[0].level = 1.0
+            mixer.voice[0].play(self._source, loop=False)
+            self._own(mixer)
+            self._port = mixer
+
+
+class PortFreeingRack(Rack):
+    """T1: deinit is Component's, which releases the port first."""
+
+    def deinit(self):
+        _component.Component.deinit(self)
+
+
+class ReversedRack(Rack):
+    """T2: the entries built in reverse order."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, tuple(reversed(tuple(chain))), patch)
+
+
+class BareNestedRack(Rack):
+    """T2: a nested rack's entries built without their options."""
+
+    def _child(self, name, source, options):
+        if name == "Rack":
+            options = dict(options)
+            options["chain"] = tuple(
+                entry if isinstance(entry, str) else entry[0]
+                for entry in options.get("chain", ()))
+        return Rack._child(self, name, source, options)
+
+
+class CachedLatencyRack(Rack):
+    """T3: latency summed once, at construction; the tail stays live."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, chain, patch)
+        self._cached = Rack.latency_samples.fget(self)
+
+    @property
+    def latency_samples(self):
+        self._check_live()
+        return self._cached
+
+
+class CachedTailRack(Rack):
+    """T3: tail summed once, at construction."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, chain, patch)
+        self._cached = Rack.tail_samples.fget(self)
+
+    @property
+    def tail_samples(self):
+        self._check_live()
+        return self._cached
+
+
+class SkipNoneRack(Rack):
+    """T3: a child whose tail is None is skipped instead of making the
+    rack's None."""
+
+    @property
+    def tail_samples(self):
+        self._check_live()
+        total = 0
+        for child in self._effects:
+            tail = child.tail_samples
+            if tail is not None:
+                total += tail
+        return total
+
+
+class ZeroLatencyRack(Rack):
+    """T3: reports no latency (the old class did, when no child declared
+    any)."""
+
+    @property
+    def latency_samples(self):
+        self._check_live()
+        return 0
+
+
+class LastOutputResetRack(Rack):
+    """T4: reset clears only the last child's output (the old class's
+    shape), then patch 0."""
+
+    def reset(self):
+        self._check_live()
+        if self._effects:
+            audiocore.reset_buffer(
+                _component.port_target(self._effects[-1].output))
+        _component.Component.reset(self)
+
+
+class ChildResetOnlyRack(Rack):
+    """T4: each child's own reset and nothing after it."""
+
+    def reset(self):
+        self._check_live()
+        for child in reversed(self._effects):
+            child.reset()
+
+
+class PublicRestoreRack(Rack):
+    """T4: patch 0 restores through the public `set_macro`."""
+
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
+        for child, (macros, index) in zip(self._effects, self._built):
+            for macro in range(len(macros)):
+                child.set_macro(macro, _component.midi_of_position(
+                    child._mode(macro), macros[macro]))
+
+
+class SkipNestedRack(Rack):
+    """T4: patch 0 leaves nested racks' children alone."""
+
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
+        for child, (macros, index) in zip(self._effects, self._built):
+            if not isinstance(child, Rack):
+                child._apply_positions(list(macros), index)
+
+
+class NoRestoreRack(Rack):
+    """T4: `program_change(0)` applies nothing."""
+
+    def _apply_positions(self, positions, patch_index):
+        _component.Component._apply_positions(self, positions, patch_index)
+
+
+class LastOnlyDeinitRack(Rack):
+    """T5: deinit releases the last child only."""
+
+    def deinit(self):
+        if self._deinited:
+            return
+        if self._effects:
+            self._effects[-1].deinit()
+        self._port = None
+        self._deinited = True
+
+
+class OutputNodeDeinitRack(Rack):
+    """T5: deinit releases each child's output node, not the child (the old
+    class's shape)."""
+
+    def deinit(self):
+        if self._deinited:
+            return
+        for child in reversed(self._effects):
+            node = _component.port_target(child.output)
+            if node is not child._source and hasattr(node, "deinit"):
+                node.deinit()
+        self._port = None
+        self._deinited = True
+
+
+class LeakyBuildRack(Rack):
+    """T5: a build that raises part-way releases nothing."""
+
+    def _build(self, chain=(), patch=None):
+        built = []
+        tail = self._source
+        for entry in chain:
+            name, options = (entry, {}) if isinstance(entry, (str, type)) \
+                else (entry[0], dict(entry[1]))
+            child = self._child(name, tail, options)
+            built.append(child)
+            tail = child.output
+        self._effects = tuple(built)
+        self._built = ()
+        self._capabilities = ()
+        self._port = tail
+        self._init_macros((), patch)
+
+
+class NoTransportRack(Rack):
+    """T6: children built without the rack's transport."""
+
+    def _child(self, name, source, options):
+        options.pop("transport", None)
+        if isinstance(name, str):
+            if name == Rack.NAME:
+                return NoTransportRack.create(source, self._sample_rate,
+                                              **options)
+            return audioeffects.create(name, source, self._sample_rate,
+                                       **options)
+        return name.create(source, self._sample_rate, **options)
+
+
+class DeafRack(Rack):
+    """T6: `transport_changed` does nothing."""
+
+    def transport_changed(self):
+        self._check_live()
+
+
+class ClassCapabilitiesRack(Rack):
+    """T6: capabilities are the class's `()`."""
+
+    @property
+    def capabilities(self):
+        self._check_live()
+        return type(self).CAPABILITIES
+
+
+def _recording_lowpass():
+    base = audioeffects.LowPass
+
+    class RecordingLowPass(base):
+        """A LowPass that records each instance it builds."""
+
+        built = []
+
+        def _build(self, *args, **kwargs):
+            base._build(self, *args, **kwargs)
+            # The register, kept: deinit empties the instance's own.
+            RecordingLowPass.built.append(list(self._nodes))
+
+    return RecordingLowPass
+
+
+#: The kit's plant-validity table: one planted fault per trait. The traits'
+#: faults live in reset, deinit, identity and the host transport, which a
+#: render at the kit's options does not reach; those rows are declared in
+#: the kit (kit_common.DECLARED) and shown red here by the trait tests.
+KIT_PLANTS = {
+    "T1": MixerRack,
+    "T2": ReversedRack,
+    "T3": ZeroLatencyRack,
+    "T4": ChildResetOnlyRack,
+    "T5": LastOnlyDeinitRack,
+    "T6": ClassCapabilitiesRack,
+}
+
+
+# --------------------------------------------------------------------------
+# The traits, as checks that return what was wrong (empty is a pass)
+
+
+def t1(cls, rate, channels):
+    """With nothing in it, a rack is a patch cable."""
+    wrong = []
+    for build in ("direct", "create"):
+        src = Source(material(1, channels, 4096), rate, channels)
+        rack = cls(src) if build == "direct" else cls.create(src, rate)
+        if rack.output is not src:
+            wrong.append("%s: output is not the source" % build)
+        if rack.latency_samples != 0 or rack.tail_samples != 0:
+            wrong.append("%s: latency %r tail %r" % (
+                build, rack.latency_samples, rack.tail_samples))
+        if rack.capabilities != ():
+            wrong.append("%s: capabilities %r" % (build, rack.capabilities))
+        rack.reset()
+        if src.rewinds:
+            wrong.append("%s: reset rewound the source %d times"
+                         % (build, src.rewinds))
+        rack.deinit()
+    try:
+        from audioroute import Port
+    except ImportError:                              # pragma: no cover
+        return wrong
+    data = material(2, channels, 8192)
+    port = Port(Source(data, rate, channels))
+    rack = cls(port)
+    rack.deinit()
+    try:
+        got = pull(port, 8192, channels)
+    except Exception as exc:                         # noqa: BLE001
+        got = "raised %s" % type(exc).__name__
+    want = pull(Port(Source(data, rate, channels)), 8192, channels)
+    if got != want:
+        wrong.append("the Port source does not render after deinit (%s)"
+                     % (got if isinstance(got, str) else "bytes differ"))
+    return wrong
+
+
+def t2(cls, rate, channels, seeds, chain=K):
+    """A rack sounds exactly like the same effects patched by hand."""
+    wrong = []
+    for seed in seeds:
+        data = material(seed, channels)
+        rack = cls.create(Source(data, rate, channels), rate, chain=chain)
+        made, out = hand(Source(data, rate, channels), rate, chain)
+        try:
+            if len(leaves(rack)) != 4 or rack.latency_samples == 0:
+                wrong.append("seed %d: built %d leaves, latency %d" % (
+                    seed, len(leaves(rack)), rack.latency_samples))
+            ours = fnv(pull(rack.output, 48000, channels))
+            theirs = fnv(pull(out, 48000, channels))
+            if ours != theirs:
+                wrong.append("seed %d: %08x != %08x by hand"
+                             % (seed, ours, theirs))
+        finally:
+            rack.deinit()
+            release(made)
+    return wrong
+
+
+def _sums(made):
+    latency = 0
+    tail = 0
+    for leaf in made:
+        latency += leaf.latency_samples
+        t = leaf.tail_samples
+        tail = None if (tail is None or t is None) else tail + t
+    return latency, tail
+
+
+def t3(cls, rate, channels):
+    """The rack reports the delay and ring-out of the whole board."""
+    wrong = []
+    seen = []
+    src = Source(material(1, channels, 4096), rate, channels)
+    rack = cls.create(src, rate, chain=K)
+    made, _ = hand(Source(material(1, channels, 4096), rate, channels),
+                   rate, K)
+    ours = leaves(rack)
+    as_built = [(list(leaf._macros), leaf.patch_index) for leaf in made]
+    try:
+        if len(ours) != 4 or rack.latency_samples == 0:
+            return ["built %d leaves, latency %d" % (
+                len(ours), rack.latency_samples)], seen
+
+        def read(when):
+            want = _sums(made)
+            got = (rack.latency_samples, rack.tail_samples)
+            seen.append(got)
+            if got != want:
+                wrong.append("%s: rack %r, by hand %r" % (when, got, want))
+            if rack.capabilities != ("tempo_sync",):
+                wrong.append("%s: capabilities %r" % (when,
+                                                      rack.capabilities))
+
+        read("built")
+        for leaf, macro in ((FUZZ, FUZZ_MIX), (VIBRATO, VIBRATO_DELAY),
+                            (DELAY, DELAY_FEEDBACK)):
+            back = made[leaf].get_macro(macro)
+            for value in (0, 127, back):
+                ours[leaf].set_macro(macro, value)
+                made[leaf].set_macro(macro, value)
+                read("leaf %d macro %d at %r" % (leaf, macro, value))
+        # The same reset by hand: each leaf's own, tail first, then each
+        # back to the positions it was built with.
+        rack.reset()
+        for leaf in reversed(made):
+            leaf.reset()
+        for leaf, (macros, index) in zip(made, as_built):
+            leaf._apply_positions(list(macros), index)
+        read("reset")
+        if len(set(s[0] for s in seen)) < 3 or \
+                len(set(s[1] for s in seen)) < 2:
+            wrong.append("the moves did not move the reads: %r" % (seen,))
+    finally:
+        rack.deinit()
+        release(made)
+    rack = cls.create(Source(material(1, channels, 4096), rate, channels),
+                      rate, chain=(("LowPass", {}), ("LadderFilter", {})))
+    try:
+        if rack.tail_samples is not None:
+            wrong.append("LowPass into LadderFilter reports tail %r"
+                         % rack.tail_samples)
+    finally:
+        rack.deinit()
+    return wrong, seen
+
+
+def _moves(rack):
+    found = leaves(rack)
+    found[DELAY].set_macro(DELAY_FEEDBACK, 127)
+    found[FUZZ].set_macro(FUZZ_FUZZ, 0)
+
+
+def t4(cls, rate, channels, seeds, chains=("K", "C2")):
+    """Reset clears the whole board and puts every pedal back where the
+    rack set it."""
+    wrong = []
+    for which in chains:
+        chain = {"K": K, "C2": c2(), "R": OFF_GRID}[which]
+        for seed in seeds:
+            key = "%s seed %d" % (which, seed)
+            fresh_src = Switchable(Source(material(seed, channels), rate,
+                                          channels))
+            fresh = Rack.create(fresh_src, rate, chain=chain)
+            want = fnv(pull(fresh.output, 48000, channels))
+            fresh.deinit()
+
+            src = Switchable(Source(material(seed + 1, channels), rate,
+                                    channels))
+            try:
+                rack = cls.create(src, rate, chain=chain)
+            except Exception as exc:                 # noqa: BLE001
+                wrong.append("%s: build raised %r" % (key, exc))
+                continue
+            try:
+                found = leaves(rack)
+                if which == "K" and (len(found) != 4
+                                     or rack.latency_samples == 0):
+                    wrong.append("%s: built %d leaves" % (key, len(found)))
+                    continue
+                built = [state_of(leaf) for leaf in found]
+                if which == "K":
+                    _moves(rack)
+                if silent(pull(rack.output, 24000, channels)):
+                    wrong.append("%s: the first render is silent" % key)
+                try:
+                    rack.reset()
+                except Exception as exc:             # noqa: BLE001
+                    wrong.append("%s: reset raised %r" % (key, exc))
+                    continue
+                for index, leaf in enumerate(found):
+                    if state_of(leaf) != built[index]:
+                        wrong.append("%s: leaf %d reads %r, built %r" % (
+                            key, index, state_of(leaf), built[index]))
+                if src.rewinds:
+                    wrong.append("%s: reset rewound the source %d times"
+                                 % (key, src.rewinds))
+                src.swap(Source(material(seed, channels), rate, channels))
+                got = fnv(pull(rack.output, 48000, channels))
+                if got != want:
+                    wrong.append("%s: after reset %08x, fresh %08x"
+                                 % (key, got, want))
+            finally:
+                rack.deinit()
+        if which != "K":
+            continue
+        # program_change(0) alone: macros back, nothing cleared.
+        src = Switchable(Source(material(1, channels), rate, channels))
+        rack = cls.create(src, rate, chain=chain)
+        try:
+            found = leaves(rack)
+            built = [state_of(leaf) for leaf in found]
+            _moves(rack)
+            pull(rack.output, 24000, channels)
+            rack.program_change(0)
+            for index, leaf in enumerate(found):
+                if state_of(leaf) != built[index]:
+                    wrong.append("program_change(0): leaf %d reads %r, built "
+                                 "%r" % (index, state_of(leaf), built[index]))
+            if src.rewinds:
+                wrong.append("program_change(0) rewound the source")
+        finally:
+            rack.deinit()
+    return wrong
+
+
+def t5(cls):
+    """Switching the rack off releases every part of every pedal in it."""
+    wrong = []
+    rate, channels = 48000, 2
+    # A native node takes only a native source: the lifecycle matrix's
+    # Feed, a Port around a re-blocked RawSample, on every interpreter.
+    import lifecycle
+
+    def feed():
+        return lifecycle.Feed(data, rate, channels, "256", loop=False).port
+
+    data = material(1, channels, 8192)
+    src = feed()
+    rack = cls.create(src, rate, chain=K)
+    made, _ = hand(feed(), rate, K)
+    try:
+        found = leaves(rack)
+        if len(found) != 4:
+            return ["built %d leaves" % len(found)]
+        nodes = []
+        for leaf in found:
+            nodes.extend(nodes_of(leaf))
+        expected = 0
+        for leaf in made:
+            expected += len(nodes_of(leaf))
+        COUNTED[:] = [len(nodes)]
+        if len(nodes) != expected or not nodes:
+            wrong.append("found %d nodes through the rack, %d by hand"
+                         % (len(nodes), expected))
+        pull(rack.output, 4096, channels)
+        children = list(rack.effects) + found
+        rack.deinit()
+        alive = [i for i, node in enumerate(nodes) if not is_released(node)]
+        if alive:
+            wrong.append("%d of %d nodes still live: %r" % (
+                len(alive), len(nodes),
+                [type(nodes[i]).__name__ for i in alive]))
+        try:
+            if silent(pull(src, 4096, channels)):
+                wrong.append("the source renders silence after deinit")
+        except Exception as exc:                     # noqa: BLE001
+            wrong.append("the source raises after deinit: %r" % exc)
+        for child in children + [rack]:
+            try:
+                child.latency_samples
+            except RuntimeError:
+                continue
+            except Exception as exc:                 # noqa: BLE001
+                wrong.append("%s raised %s, not the contract's RuntimeError"
+                             % (type(child).__name__, type(exc).__name__))
+                continue
+            wrong.append("%s still answers after deinit"
+                         % type(child).__name__)
+        try:
+            rack.deinit()
+        except Exception as exc:                     # noqa: BLE001
+            wrong.append("a second deinit raised %r" % exc)
+    finally:
+        release(made)
+    recording = _recording_lowpass()
+    try:
+        cls(feed(), chain=(recording, "NoSuchEffect"))
+        wrong.append("a chain naming NoSuchEffect built")
+    except ImportError:
+        pass
+    if len(recording.built) != 1:
+        wrong.append("RecordingLowPass built %d times"
+                     % len(recording.built))
+    else:
+        built = recording.built[0]
+        live = [n for n in built if not is_released(n)]
+        if not built or live:
+            wrong.append("the half-built LowPass keeps %d of %d nodes live"
+                         % (len(live), len(built)))
+    return wrong
+
+
+class Host:
+    """A host transport: playing, at `bpm`."""
+
+    def __init__(self, bpm):
+        self.bpm = bpm
+
+    def __call__(self):
+        return (True, 0.0, float(self.bpm), 4, 4)
+
+
+def _echo(values, channels, click, lo, hi):
+    """Frames from `click` to the loudest sample in [click+lo, click+hi)."""
+    best = -1
+    where = None
+    for frame in range(click + lo, click + hi):
+        v = abs(values[frame * channels])
+        if v > best:
+            best, where = v, frame
+    return where - click
+
+
+def t6(cls, rate, channels=2):
+    """A tempo-synced pedal in the rack follows the song's tempo."""
+    wrong = []
+    first = 16000 if rate == 48000 else 7350
+    second = 9600 if rate == 48000 else 4410
+    click1 = 4096
+    change = ((click1 + first + 2048) // BLOCK + 1) * BLOCK
+    click2 = change + (3 * rate) // 2
+    frames = click2 + 2 * second
+    host = Host(90)
+    src = Source(clicks(frames, channels, (click1, click2)), rate, channels)
+    rack = cls.create(src, rate, transport=host, chain=(("Rack", {
+        "chain": (("DigitalDelay", {"sync": True, "division": 6,
+                                    "feedback": 0.0, "mix": 1.0,
+                                    "glide_ms": 800.0}),)}),))
+    try:
+        if rack.capabilities != ("tempo_sync",):
+            wrong.append("capabilities %r" % (rack.capabilities,))
+        head = pull(rack.output, change, channels)
+        host.bpm = 150
+        rack.transport_changed()
+        rest = pull(rack.output, frames - change, channels)
+        values = samples(head + rest)
+        got1 = _echo(values, channels, click1, 64, 2 * first)
+        got2 = _echo(values, channels, click2, 64, 2 * second)
+        if abs(got1 - first) > 2:
+            wrong.append("90 BPM: echo at %d, want %d" % (got1, first))
+        if abs(got2 - second) > 2:
+            wrong.append("150 BPM: echo at %d, want %d" % (got2, second))
+    finally:
+        rack.deinit()
+    return wrong
+
+
+# --------------------------------------------------------------------------
+# The tests
+
+
+
+def _native_binaries():
+    """{family: path or None}: LIFECYCLE_MICROPYTHON /
+    LIFECYCLE_CIRCUITPYTHON, or the workspace's `bin/`."""
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    bindir = None
+    here = root
+    for _up in range(5):
+        here = os.path.dirname(here)
+        if os.path.isfile(os.path.join(here, "bin", "micropython")):
+            bindir = os.path.join(here, "bin")
+            break
+    found = {}
+    for family in ("micropython", "circuitpython"):
+        path = os.environ.get("LIFECYCLE_" + family.upper())
+        if path is None and bindir is not None:
+            path = os.path.join(bindir, family)
+        found[family] = path if path and os.path.isfile(path) else None
+    return found, root
+
+class TestEmptyRack(TestCase):
+    """T1. With nothing in it, a rack is a patch cable."""
+
+    def test_an_empty_rack_is_a_patch_cable(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                self.assertEqual(t1(Rack, rate, channels), [],
+                                 (rate, channels))
+
+    def test_t1_faults_are_red(self):
+        for plant in (MixerRack, PortFreeingRack):
+            self.assertNotEqual(t1(plant, 48000, 2), [], plant.__name__)
+
+class TestByHand(TestCase):
+    """T2. A rack sounds exactly like the same effects patched by
+    hand."""
+
+    def test_a_rack_sounds_like_its_pedals_by_hand(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                self.assertEqual(t2(Rack, rate, channels, SEEDS), [],
+                                 (rate, channels))
+
+    def test_t2_faults_are_red(self):
+        # Reversed: drive after the reverb is a different sound.
+        for plant in (ReversedRack, BareNestedRack):
+            wrong = t2(plant, 48000, 2, (1,))
+            self.assertTrue(any("by hand" in w for w in wrong),
+                            (plant.__name__, wrong))
+
+    def test_a_mono_source_gives_a_mono_rack(self):
+        src = Source(material(1, 1, 4096), 48000, 1)
+        rack = Rack.create(src, 48000, chain=K)
+        try:
+            self.assertEqual(rack.channel_count, 1)
+            self.assertEqual(rack.output.channel_count, 1)
+            for leaf in leaves(rack):
+                self.assertEqual(leaf.channel_count, 1)
+        finally:
+            rack.deinit()
+
+    def test_effects_is_the_chain_in_order(self):
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           chain=K)
+        try:
+            self.assertIsInstance(rack.effects, tuple)
+            self.assertEqual([type(c).NAME for c in rack.effects],
+                             ["Fuzz", "Rack", "ConvolutionReverb"])
+            self.assertEqual([type(c).NAME for c in leaves(rack)],
+                             ["Fuzz", "DigitalDelay", "Vibrato",
+                              "ConvolutionReverb"])
+            self.assertIs(rack.effects[1].effects[0]._source,
+                          rack.effects[0].output)
+            self.assertIs(rack.output, rack.effects[-1].output)
+        finally:
+            rack.deinit()
+
+    def test_the_rack_builds_no_node(self):
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           chain=K)
+        try:
+            self.assertEqual(rack._nodes, [])
+            self.assertIs(rack.output, rack.effects[-1].output)
+        finally:
+            rack.deinit()
+
+    def test_the_example_plays(self):
+        src = Source(material(1, 2), 48000, 2)
+        rack = Rack.create(src, 48000, chain=(
+            ("Fuzz", {}),
+            ("DigitalDelay", {"mix": 0.3, "feedback": 0.4}),
+            ("ConvolutionReverb", {}),
+        ))
+        try:
+            self.assertEqual(len(rack.effects), 3)
+            self.assertFalse(silent(pull(rack.output, 24000, 2)))
+        finally:
+            rack.deinit()
+
+    def test_chain_entries_keep_their_meaning(self):
+        src = Source(material(1, 2, 4096), 48000, 2)
+        rack = Rack(src, chain=("LowPass", ("HighPass", {}),
+                                audioeffects.LowPass))
+        try:
+            self.assertEqual([type(c).NAME for c in rack.effects],
+                             ["LowPass", "HighPass", "LowPass"])
+        finally:
+            rack.deinit()
+        with self.assertRaises(ValueError):
+            Rack(src, chain=(42,))
+        with self.assertRaises(ImportError):
+            Rack(src, chain=("NoSuchEffect",))
+
+class TestReads(TestCase):
+    """T3. The rack reports the delay and ring-out of the whole board,
+    as it stands right now."""
+
+    def test_latency_and_tail_are_the_live_sums(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                wrong, seen = t3(Rack, rate, channels)
+                self.assertEqual(wrong, [], (rate, channels))
+
+    def test_t3_faults_are_red(self):
+        for plant in (CachedLatencyRack, CachedTailRack, SkipNoneRack,
+                      ZeroLatencyRack):
+            wrong, _ = t3(plant, 48000, 2)
+            self.assertNotEqual(wrong, [], plant.__name__)
+
+class TestReset(TestCase):
+    """T4. Reset clears the whole board and puts every pedal back where
+    the rack set it."""
+
+    def test_reset_puts_every_pedal_back(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                self.assertEqual(t4(Rack, rate, channels, SEEDS), [],
+                                 (rate, channels))
+
+    def test_t4_faults_are_red(self):
+        for plant in (LastOutputResetRack, ChildResetOnlyRack,
+                      PublicRestoreRack, SkipNestedRack, NoRestoreRack):
+            self.assertNotEqual(t4(plant, 48000, 2, (1,)), [],
+                                plant.__name__)
+        # The public surface cannot restore C2: a measured
+        # ConvolutionReverb refuses every macro but Mix.
+        wrong = t4(PublicRestoreRack, 48000, 2, (1,), chains=("C2",))
+        self.assertTrue(any("raised" in w for w in wrong), wrong)
+
+    def test_an_off_grid_child_comes_back_as_built(self):
+        for rate in RATES:
+            self.assertEqual(t4(Rack, rate, 2, (1, 2), chains=("R",)),
+                             [], rate)
+
+    def test_a_host_reset_clears_the_last_pedal_only(self):
+        # A delay into a filter: the host's reset_buffer on the output
+        # clears the filter and leaves the delay's repeats playing.
+        chain = (("DigitalDelay", {"mix": 1.0, "feedback": 0.6}),
+                 ("LowPass", {}))
+        rate, channels = 48000, 2
+        data = material(1, channels, 96000)
+        for host in (True, False):
+            rack = Rack.create(Source(data, rate, channels), rate,
+                               chain=chain)
+            try:
+                pull(rack.output, 16384, channels)
+                if host:
+                    audiocore.reset_buffer(rack.output)
+                else:
+                    rack.reset()
+                after = pull(rack.output, 24000, channels)
+                self.assertEqual(silent(after), not host, host)
+            finally:
+                rack.deinit()
+        # On an empty rack the host's reset is a rewind of the source.
+        src = Source(data, rate, channels)
+        rack = Rack.create(src, rate)
+        audiocore.reset_buffer(rack.output)
+        self.assertEqual(src.rewinds, 1)
+        rack.deinit()
+
+class TestDeinit(TestCase):
+    """T5. Switching the rack off releases every part of every pedal in
+    it, including a rack that failed half-built."""
+
+    def test_deinit_releases_every_pedal(self):
+        self.assertEqual(t5(Rack), [])
+
+    def test_t5_faults_are_red(self):
+        for plant in (LastOnlyDeinitRack, OutputNodeDeinitRack,
+                      LeakyBuildRack):
+            self.assertNotEqual(t5(plant), [], plant.__name__)
+
+    def _native(self, family):
+        import subprocess
+        import tempfile
+        binaries, root = _native_binaries()
+        binary = binaries[family]
+        if binary is None:
+            self.skipTest("no %s binary: set LIFECYCLE_%s"
+                          % (family, family.upper()))
+        with tempfile.TemporaryDirectory() as scratch:
+            env = dict(os.environ, MICROPYPATH="lib:tests/support",
+                       GCOV_PREFIX=scratch)
+            done = subprocess.run(
+                [binary, "-X", "heapsize=256M",
+                 "tests/test_cpython_effects_rack.py"],
+                capture_output=True, text=True, cwd=root, env=env)
+        lines = [line for line in done.stdout.splitlines()
+                 if not line.startswith("T5|nodes|")]
+        self.assertEqual(lines, ["T5|Rack|ok"] + [
+            "T5|%s|red" % plant.__name__ for plant in NATIVE_PLANTS]
+            + ["DONE"], done.stdout[-2000:] + done.stderr[-2000:])
+
+    def test_deinit_releases_every_pedal_micropython(self):
+        self._native("micropython")
+
+    def test_deinit_releases_every_pedal_circuitpython(self):
+        self._native("circuitpython")
+
+class TestTempo(TestCase):
+    """T6. A tempo-synced pedal in the rack follows the song's tempo,
+    wherever it sits."""
+
+    def test_a_synced_pedal_follows_the_tempo(self):
+        for rate in RATES:
+            self.assertEqual(t6(Rack, rate), [], rate)
+
+    def test_k_capabilities_are_the_union(self):
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           chain=K)
+        try:
+            self.assertEqual(rack.capabilities, ("tempo_sync",))
+        finally:
+            rack.deinit()
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           chain=("LowPass",))
+        try:
+            self.assertEqual(rack.capabilities, ())
+        finally:
+            rack.deinit()
+
+    def test_an_entry_keeps_its_own_transport(self):
+        own = Host(150)
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           transport=Host(90),
+                           chain=(("DigitalDelay", {"transport": own}),
+                                  "DigitalDelay"))
+        try:
+            self.assertIs(rack.effects[0].transport, own)
+            self.assertIs(rack.effects[1].transport, rack.transport)
+        finally:
+            rack.deinit()
+
+    def test_t6_faults_are_red(self):
+        for plant in (NoTransportRack, DeafRack, ClassCapabilitiesRack):
+            self.assertNotEqual(t6(plant, 48000), [], plant.__name__)
+
+class TestSurface(TestCase):
+    """The surface is the chain: no macros, patch 0 alone."""
+
+    def test_the_surface_is_the_chain(self):
+        self.assertEqual(Rack.MACRO_LABELS, ())
+        self.assertEqual(Rack.MACRO_MODES, {})
+        self.assertEqual(Rack.PATCHES, {0: ("Default", ())})
+        rack = Rack.create(Source(material(1, 2, 4096), 48000, 2), 48000,
+                           chain=K)
+        try:
+            rack.program_change(1)
+            self.assertEqual(rack.patch_index, 0)
+            with self.assertRaises(IndexError):
+                rack.set_macro(0, 64)
+        finally:
+            rack.deinit()
+
+    def test_the_class_is_stock_tier(self):
+        self.assertEqual(Rack.TIER, _component.STOCK)
+        self.assertEqual(Rack.REQUIRES, ())
+
+
+#: The planted faults the native half of T5 holds red.
+NATIVE_PLANTS = (LastOnlyDeinitRack, OutputNodeDeinitRack, LeakyBuildRack)
+
+
+#: Every claim sentence of the class docstring, word for word, and the
+#: tests that hold it.
+CLAIMS = (
+    ("For example: rack = Rack.create(source, 48000, chain=( (\"Fuzz\", {}), "
+     "(\"DigitalDelay\", {\"mix\": 0.3, \"feedback\": 0.4}), "
+     "(\"ConvolutionReverb\", {}), )) audio_out.play(rack.output) `chain` is "
+     "a tuple of entries, each an effect name, a `(name, options)` pair whose "
+     "options are that effect's constructor keywords, or an effect class in "
+     "place of a name.",
+     ("test_the_example_plays", "test_chain_entries_keep_their_meaning")),
+    ("A rack adds no sound of its own: it sounds exactly like the same "
+     "pedals patched by hand, one into the next.",
+     ("test_a_rack_sounds_like_its_pedals_by_hand",
+      "test_the_rack_builds_no_node")),
+    ("Empty, it is a patch cable, and its output is your source.",
+     "test_an_empty_rack_is_a_patch_cable"),
+    ("A mono source gives a mono rack.",
+     ("test_a_mono_source_gives_a_mono_rack",
+      "test_a_rack_sounds_like_its_pedals_by_hand")),
+    ("Order matters as soon as one pedal isn't a plain filter: drive into a "
+     "reverb isn't a reverb into drive.", "test_t2_faults_are_red"),
+    ("`latency_samples` and `tail_samples` are the sums of the pedals' own, "
+     "read live, so they follow a pedal's knobs; the tail is `None` as soon "
+     "as one pedal's is.", "test_latency_and_tail_are_the_live_sums"),
+    ("There is no rack Mix, Bypass or Output knob, and patch 0 is its only "
+     "patch.", "test_the_surface_is_the_chain"),
+    ("To turn a pedal's knob, reach it through `rack.effects`, a tuple of "
+     "the pedals in chain order.", "test_effects_is_the_chain_in_order"),
+    ("`reset()` clears every pedal and puts each back to the settings the "
+     "rack built it with, undoing knob moves made since.",
+     "test_reset_puts_every_pedal_back"),
+    ("`program_change(0)` does the putting back alone, without clearing "
+     "anything.", "test_reset_puts_every_pedal_back"),
+    ("A host's `audiocore.reset_buffer(rack.output)` clears the last pedal "
+     "only, and on an empty rack it rewinds your own source, because the "
+     "output is your source.", "test_a_host_reset_clears_the_last_pedal_only"),
+    ("A tempo-synced pedal follows the song's tempo wherever it sits, nested "
+     "racks included: each pedal gets the rack's transport unless its entry "
+     "names its own, and `transport_changed()` reaches every pedal.",
+     ("test_a_synced_pedal_follows_the_tempo",
+      "test_an_entry_keeps_its_own_transport")),
+    ("`capabilities` is the union of the pedals' own, set when the rack is "
+     "built.", ("test_k_capabilities_are_the_union",
+                "test_a_synced_pedal_follows_the_tempo")),
+    ("A rack builds nothing of its own, so it costs what its pedals cost.",
+     "test_the_rack_builds_no_node"),
+    ("The class itself runs on a stock board; a built rack needs whatever "
+     "modules its pedals need.", "test_the_class_is_stock_tier"),
+    ("`deinit()` releases every pedal, nested racks included, and never "
+     "your source.", ("test_deinit_releases_every_pedal",
+                      "test_an_empty_rack_is_a_patch_cable")),
+    ("If an entry fails to build, the pedals built before it are released "
+     "before the error reaches you.", "test_deinit_releases_every_pedal"),
+)
+
+
+def _native_main():
+    """T5 on this interpreter by itself: the clean class, then each plant,
+    which must be red."""
+    wrong = t5(Rack)
+    print("T5|Rack|%s" % ("ok" if not wrong else "RED(%s)" % wrong))
+    print("T5|nodes|%r|no deinit|%s" % (COUNTED, sorted(NO_DEINIT)))
+    for plant in NATIVE_PLANTS:
+        print("T5|%s|%s" % (plant.__name__, "red" if t5(plant) else "GREEN"))
+    print("DONE")
+
+
+if __name__ == "__main__":
+    if unittest is None:
+        # Run as the module, not `__main__`: `_component` reads VENDOR off
+        # the module a planted class is defined in.
+        sys.path.insert(0, "tests")
+        import test_cpython_effects_rack
+        test_cpython_effects_rack._native_main()
+    else:
+        unittest.main()

From 93dbb9bd68fb9922d350d54ce090023f48e9570c Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:28:07 -0500
Subject: [PATCH 12/76] StereoWidener: patches play their Delay on every
 instance, no stale block without get_buffer

The constructor's exact delay_ms plays until Delay moves or a patch
loads, and the patches' Delays play their round numbers by step, so
patch 0 and reset() are 14 ms whatever the constructor said. Where
audiocore.get_buffer is compiled out, a constructor patch no longer wires
Haas, and a return to Haas re-plays the voices, so a block a voice held
is dropped rather than played; the one-block skip that remains is in the
docstring. The clipping sentence says below half of full scale, tested
at the bound, and the H1, W and M1 tests run every seed and rate the
traits list.
---
 lib/audioeffects/rebuilt/stereowidener.py   |  77 +++++++--
 tests/test_cpython_effects_stereowidener.py | 173 ++++++++++++++++++--
 2 files changed, 218 insertions(+), 32 deletions(-)

diff --git a/lib/audioeffects/rebuilt/stereowidener.py b/lib/audioeffects/rebuilt/stereowidener.py
index 5760787..788324f 100644
--- a/lib/audioeffects/rebuilt/stereowidener.py
+++ b/lib/audioeffects/rebuilt/stereowidener.py
@@ -44,11 +44,20 @@
 #: Splitter tap take per pull.
 BLOCK = 256
 
-#: How close, as a 0..1 knob position, Delay must sit to the grid step the
-#: constructor's `delay_ms` seeded for that exact value to play: 1e-6 is
-#: 1/7 874 of one MIDI step, and holds a single-precision round trip.
+#: How close, as a 0..1 knob position, a Delay write must come to the grid
+#: step the constructor's `delay_ms` seeded to count as a host echoing it
+#: back: 1e-6 is 1/7 874 of one MIDI step, and holds a single-precision
+#: round trip.
 ECHO_TOLERANCE = 1e-6
 
+#: The patches' Delays, exactly, by MIDI step: Delay on one of these steps
+#: plays the round number the patch table names (14 ms, not the step's
+#: 14.06), whichever way it got there.
+DELAY_STEPS = {62: 6.0, 91: 14.0, 111: 25.0}
+
+#: How close, in MIDI steps, Delay must sit to a step in `DELAY_STEPS`.
+STEP_TOLERANCE = 1e-4
+
 WIDTH_I, DELAY_I, CHARACTER_I = range(3)
 
 CHARACTERS = ("haas", "mid_side")
@@ -113,7 +122,7 @@ class StereoWidener(_component.Component):
     Width 0 is mono, 1 is a wire and 2 doubles the sides.
     Above Width 1, a part panned hard left shows up inverted on the right.
     A part that is the same in both channels comes out unchanged.
-    Peaks up to half of full scale never clip at any Width.
+    Peaks below half of full scale never clip at any Width.
 
     **Mono, latency, tail.** A one-channel source comes out exactly as it
     went in, whatever the controls say.
@@ -126,6 +135,9 @@ class StereoWidener(_component.Component):
     `reset()` empties the line and returns to patch 0.
     The class never reads the host's tempo.
 
+    Where `audiocore.get_buffer` is compiled out, leaving Haas before its
+    first block has played skips that one block of the source.
+
     **Limits shared by the family.**
     A control that jumps, Width or Character, makes the output step: move it
     in small steps from the host if you need it smooth.
@@ -178,10 +190,10 @@ def _build(self, width=DEFAULT_WIDTH, delay_ms=DEFAULT_DELAY_MS,
         width = _between(_option(width, DEFAULT_WIDTH), 0.0, 2.0)
         delay_ms = _between(_option(delay_ms, DEFAULT_DELAY_MS),
                             DELAY_MIN_MS, DELAY_MAX_MS)
-        #: The constructor's Delay, exactly, and the grid step it seeds.
-        #: That exact value plays whenever Delay sits on that step, so a
-        #: fresh instance, its patch 0 and a host echoing `get_macro(1)` all
-        #: play 14.0 ms, not the step's 14.06.
+        #: The constructor's Delay, exactly, and the grid step it seeds, so
+        #: a fresh instance reads a whole MIDI step. The exact value plays
+        #: until Delay moves (a host echoing `get_macro(1)` does not move
+        #: it) or a patch is loaded.
         self._delay_exact = delay_ms
         span = self._MACRO_RANGES[DELAY_I]
         self._delay_seed = _component.position_of_midi(
@@ -204,10 +216,12 @@ def _build(self, width=DEFAULT_WIDTH, delay_ms=DEFAULT_DELAY_MS,
                   1.0 if character == CHARACTERS[1] else 0.0)
         self._init_macros(values)
         self._macros[DELAY_I] = self._delay_seed
-        self._ready = True
-        self._refresh()
+        # A constructor patch lands before the graph is first set up, so a
+        # Mid/Side or Width 0 patch never wires the Haas voices (`_wire`).
         if patch is not None:
             self.program_change(patch)
+        self._ready = True
+        self._refresh()
 
     def _build_graph(self):
         rate = self._sample_rate
@@ -254,9 +268,17 @@ def _wire(self):
         Splitter on `_hush` that block is zeros, and one pull of the mixer
         hands it out, so wiring takes nothing from the borrowed source and
         leaves no voice holding a block: whatever the MidSide has handed
-        out, the output has played, at every Width and Character. Without
-        `audiocore.get_buffer` the voices prime the source's next block,
-        which the next pull plays."""
+        out, the output has played, at every Width and Character.
+
+        Without `audiocore.get_buffer` (compiled out of CircuitPython's
+        default board builds) the voices prime the source's next block,
+        which the next pull plays. If the output leaves Haas before that
+        pull, the bypass starts a block later and the voices hold the block
+        it skipped; `_route` re-plays them on the way back, so that block
+        is dropped rather than played stale. The skip is disclosed. A
+        re-played voice there starts at level 0 until its signal crosses
+        zero, upstream's level gate, as every class's first block does on
+        such a build."""
         pull = getattr(audiocore, "get_buffer", None)
         voices = self._mixer.voice
         self._levels()
@@ -288,10 +310,23 @@ def _mid_side(self):
         return self._macros[CHARACTER_I] >= 0.5
 
     def _delay_ms(self):
-        if abs(self._macros[DELAY_I] - self._delay_seed) <= ECHO_TOLERANCE:
+        if self._delay_exact is not None:
             return self._delay_exact
+        midi = _component.midi_of_position("UNIPOLAR",
+                                           self._macros[DELAY_I])
+        step = int(midi + 0.5)
+        if abs(midi - step) <= STEP_TOLERANCE and step in DELAY_STEPS:
+            return DELAY_STEPS[step]
         return self._value(DELAY_I)
 
+    def macro(self, index):
+        """What macro `index` currently stands for, in its own units; for
+        Delay, the milliseconds it plays."""
+        self._check_live()
+        if index == DELAY_I:
+            return self._delay_ms()
+        return _component.Component.macro(self, index)
+
     def _levels(self):
         lead, copy = haas_voices(self._width())
         voices = self._mixer.voice
@@ -301,13 +336,17 @@ def _levels(self):
     # -- applying ------------------------------------------------------
 
     def _apply_macro(self, index, position):
-        del index, position
+        if index == DELAY_I and self._ready and (
+                abs(position - self._delay_seed) > ECHO_TOLERANCE):
+            self._delay_exact = None
         if self._ready:
             self._refresh()
 
     def program_change(self, index, channel=0, note_id=-1,
                        sample_position=0):
         """Apply patch `index` whole, then refresh the graph once."""
+        if type(self).PATCHES.get(index) is not None:
+            self._delay_exact = None
         ready = self._ready
         self._ready = False
         try:
@@ -344,7 +383,13 @@ def _route(self):
             self._wire()
         else:
             self._levels()
-            self._rejoin(keep=(self._ms,))
+            if self._rejoin(keep=(self._ms,)) and getattr(
+                    audiocore, "get_buffer", None) is None:
+                # A voice may still hold the block it primed at wiring:
+                # play() again drops it and primes the source's next block.
+                voices = self._mixer.voice
+                voices[0].play(self._split.tap(0))
+                voices[1].play(self._line)
         self._output = self._tail
 
     def _haas_live(self):
diff --git a/tests/test_cpython_effects_stereowidener.py b/tests/test_cpython_effects_stereowidener.py
index fa7f005..66ad385 100644
--- a/tests/test_cpython_effects_stereowidener.py
+++ b/tests/test_cpython_effects_stereowidener.py
@@ -66,6 +66,16 @@ def law_delay_ms(midi):
     return 40.0 ** (midi / 127.0)
 
 
+#: Section 3's patch Delays, by MIDI step: a patch plays the round number.
+PATCH_DELAYS = {62: 6.0, 91: 14.0, 111: 25.0}
+
+
+def law_step_ms(midi):
+    """What Delay on a whole MIDI step plays: a patch's round number on its
+    step, the log law elsewhere."""
+    return PATCH_DELAYS.get(midi, law_delay_ms(midi))
+
+
 def delay_midi(ms):
     """The float MIDI position that stands for `ms` exactly."""
     return 127.0 * math.log(ms) / math.log(40.0)
@@ -290,10 +300,9 @@ def h1_read(cls, rate, seed, frames=4096, width=None, delay_ms=None,
     e = cls(source(values, rate), **options)
     try:
         if delay_grid is not None:
-            ms = law_delay_ms(delay_grid)
+            ms = law_step_ms(delay_grid)
         elif patch is not None:
-            midi = StereoWidener.PATCHES[patch][1][DELAY_I]
-            ms = 14.0 if midi == 91 else law_delay_ms(midi)
+            ms = law_step_ms(StereoWidener.PATCHES[patch][1][DELAY_I])
         else:
             ms = 14.0 if delay_ms is None else delay_ms
         tau = law_frames(ms, rate)
@@ -563,6 +572,40 @@ def test_the_constructor_delay_plays_exactly(self):
                 self.assertEqual((left, right), (0, 0), (rate, patch))
                 self.assertEqual(tau, law_frames(14.0, rate))
 
+    def test_patches_play_their_delay_whatever_the_constructor_said(self):
+        for rate in (48000, 44100, 22050):
+            for ctor in (14.0, 14.03, 13.95, 20.0, 6.02, 25.0):
+                e = StereoWidener(source(array("h", bytes(16)), rate),
+                                  delay_ms=ctor)
+                try:
+                    self.assertEqual(e._frames, law_frames(ctor, rate))
+                    e.set_macro(DELAY_I, e.get_macro(DELAY_I))
+                    self.assertEqual(e._frames, law_frames(ctor, rate))
+                    for patch, (_, values) in StereoWidener.PATCHES.items():
+                        e.program_change(patch)
+                        want = law_frames(law_step_ms(values[DELAY_I]), rate)
+                        self.assertEqual(e._frames, want, (rate, ctor, patch))
+                    e.reset()
+                    self.assertEqual(e._frames, law_frames(14.0, rate))
+                finally:
+                    e.deinit()
+
+    def test_the_constructor_delay_plays_until_delay_moves(self):
+        e = StereoWidener(source(array("h", bytes(16)), 48000),
+                          delay_ms=13.95)
+        try:
+            self.assertEqual(e.get_macro(DELAY_I), 91.0)
+            self.assertEqual(e.macro(DELAY_I), 13.95)
+            self.assertEqual(e._frames, 670)
+            e.set_macro(DELAY_I, 90)
+            e.set_macro(DELAY_I, 91)
+            self.assertEqual(e.macro(DELAY_I), 14.0)
+            self.assertEqual(e._frames, 672)
+            e.set_macro(DELAY_I, 92)
+            self.assertAlmostEqual(e.macro(DELAY_I), law_delay_ms(92))
+        finally:
+            e.deinit()
+
     def test_delay_does_nothing_in_mid_side(self):
         values = lcg_noise(2048, 2, 5, peak=16384)
         base = render(StereoWidener, values, 48000, width=1.5,
@@ -643,6 +686,37 @@ def test_reset_empties_the_line_and_returns_to_patch_0(self):
             self.assertEqual(out[2 * n + 1],
                              values[2 * (1024 + n - tau) + 1], n)
 
+    def test_without_get_buffer(self):
+        # A re-played voice there starts at level 0 until its signal
+        # crosses zero (upstream's level gate, which `open_level_gates`
+        # cannot open without get_buffer), so each read starts a few frames
+        # after the return.
+        frames = 4096
+        settle = 32
+        # Leaving Haas before its first block skips that block, once, and
+        # the block is never played stale.
+        values, out = without_get_buffer(
+            StereoWidener,
+            {0: lambda e: e.program_change(4),
+             4: lambda e: e.program_change(0)})
+        self.assertEqual(left_skip(values, out, 4 * BLOCK + settle, frames),
+                         BLOCK)
+        # Built at a Mid/Side patch, Haas is never wired until it is
+        # reached, and nothing is skipped.
+        values, out = without_get_buffer(
+            lambda src: StereoWidener(src, patch=4),
+            {4: lambda e: e.program_change(0)})
+        self.assertEqual(left_skip(values, out, 4 * BLOCK + settle, frames),
+                         0)
+        # Leaving and coming back once Haas has played skips nothing.
+        values, out = without_get_buffer(
+            StereoWidener,
+            {2: lambda e: e.program_change(4),
+             6: lambda e: e.program_change(0)})
+        self.assertEqual(left_skip(values, out, 6 * BLOCK + settle, frames),
+                         0)
+        self.assertEqual(left_skip(values, out, settle, 2 * BLOCK), 0)
+
     def test_the_tempo_is_never_read(self):
         reads = []
 
@@ -679,6 +753,49 @@ def test_no_latency_in_either_character(self):
                 e.deinit()
 
 
+def without_get_buffer(build, moves, frames=4096, seed=3):
+    """Render with `audiocore.get_buffer` hidden from the class, as on a
+    CircuitPython board build, while it builds and while it moves."""
+    import types
+    from audioeffects.rebuilt import stereowidener as module
+    real = module.audiocore
+    fake = types.ModuleType("audiocore")
+    for name in dir(real):
+        if name != "get_buffer":
+            setattr(fake, name, getattr(real, name))
+
+    def hidden(action):
+        def run(e):
+            module.audiocore = _component.audiocore = fake
+            try:
+                action(e)
+            finally:
+                module.audiocore = _component.audiocore = real
+        return run
+
+    values = lcg_noise(frames, 2, seed)
+    module.audiocore = _component.audiocore = fake
+    try:
+        e = build(source(values, 48000))
+    finally:
+        module.audiocore = _component.audiocore = real
+    try:
+        out = pull(e, frames, dict((k, hidden(f)) for k, f in moves.items()))
+    finally:
+        e.deinit()
+    return values, out
+
+
+def left_skip(values, out, start, frames):
+    """The one shift, in frames, that makes the left from `start` on the
+    source's left, or None."""
+    for shift in (0, BLOCK):
+        if all(out[2 * n] == values[2 * (n + shift)]
+               for n in range(start, frames - shift)):
+            return shift
+    return None
+
+
 class H1TheCopy(TestCase):
     def test_the_copy_is_the_right_exactly_delay_late(self):
         cells = []
@@ -702,7 +819,7 @@ def test_random_grid_delays(self):
                 self.assertEqual((left, right), (0, 0), (seed, rate, midi))
 
     def test_the_right_half_above_width_1(self):
-        for seed in SEEDS[:4]:
+        for seed in SEEDS:
             for rate in RATES:
                 for width in (1.5, 2.0):
                     _, right, tau = h1_read(StereoWidener, rate, seed,
@@ -794,12 +911,16 @@ def test_the_sum_holds_and_the_side_follows(self):
                     self.assertLessEqual(side, 1.0, (rate, seed, w))
 
     def test_at_the_mid_side_patches(self):
-        for patch in (4, 5, 6):
-            for w in (0.0, 1.0, 2.0):
-                s, side = m1_read(StereoWidener, 48000, patch, w,
-                                  patch=patch)
-                self.assertLessEqual(s, 1, (patch, w))
-                self.assertLessEqual(side, 1.0, (patch, w))
+        for rate in RATES:
+            for seed in SEEDS:
+                widths = M1_WIDTHS + (m1_random_width(seed),)
+                for patch in (4, 5, 6):
+                    for w in widths:
+                        s, side = m1_read(StereoWidener, rate, seed, w,
+                                          frames=2048, patch=patch)
+                        self.assertLessEqual(s, 1, (rate, seed, patch, w))
+                        self.assertLessEqual(side, 1.0,
+                                             (rate, seed, patch, w))
 
     def test_a_centred_part_is_unchanged(self):
         values = lcg_noise(2048, 1, 4)
@@ -811,8 +932,13 @@ def test_a_centred_part_is_unchanged(self):
                          character="mid_side")
             self.assertEqual(_same_after(out, pair), 0, w)
 
-    def test_half_scale_never_clips(self):
+    def test_below_half_scale_never_clips(self):
+        # Half of full scale is 16384; below it is 16383 and down, which
+        # INPUT_CEILING_DBFS (-6.03 dBFS, 16366) sits under.
         peak = 16383
+        self.assertLessEqual(
+            rint(32767 * 10 ** (StereoWidener.INPUT_CEILING_DBFS / 20.0)),
+            peak)
         for character in ("haas", "mid_side"):
             for w in (0.0, 0.5, 1.0, 1.5, 2.0):
                 for shape in ("anti", "left", "noise"):
@@ -828,6 +954,16 @@ def test_half_scale_never_clips(self):
                                  character=character)
                     self.assertLess(max(abs(x) for x in out), 32767,
                                     (character, w, shape))
+        # At half scale itself the bound is met: anti-phase 16384 at Width
+        # 2 doubles to 32768, one past the rail.
+        values = array("h", bytes(4 * 512))
+        for n in range(512):
+            v = 16384 if (n // 37) % 2 else -16384
+            values[2 * n] = v
+            values[2 * n + 1] = -v
+        out = render(StereoWidener, values, 48000, width=2.0,
+                     character="mid_side")
+        self.assertIn(32767, out)
 
     def test_level_width_is_red(self):
         for w in M1_WIDTHS:
@@ -859,7 +995,7 @@ def test_late_matrix_is_red(self):
 class WTheWire(TestCase):
     def test_a_mono_source_is_a_wire(self):
         for rate in RATES:
-            for seed in SEEDS[:2]:
+            for seed in SEEDS:
                 for cell in w_mono_cells():
                     self.assertEqual(
                         w_differing(StereoWidener, rate, seed, 1, 1024,
@@ -920,8 +1056,11 @@ def test_fixed_copy_is_red(self):
      ("test_the_textbook_matrix", "test_late_matrix_is_red")),
     ("A part that is the same in both channels comes out unchanged.",
      "test_a_centred_part_is_unchanged"),
-    ("Peaks up to half of full scale never clip at any Width.",
-     "test_half_scale_never_clips"),
+    ("Peaks below half of full scale never clip at any Width.",
+     "test_below_half_scale_never_clips"),
+    ("Where `audiocore.get_buffer` is compiled out, leaving Haas before its "
+     "first block has played skips that one block of the source.",
+     "test_without_get_buffer"),
     ("A one-channel source comes out exactly as it went in, whatever the "
      "controls say.",
      "test_a_mono_source_is_a_wire"),
@@ -999,8 +1138,10 @@ def figures(seeds=SEEDS):
         print("%s|M2|%d|worst %.3f|R' at 1.5, 2: %r" % (name, rate, worst,
                                                           inverted))
         mono = 0
-        for cell in w_mono_cells():
-            mono += w_differing(StereoWidener, rate, 1, 1, 1024, **cell)
+        for seed in seeds:
+            for cell in w_mono_cells():
+                mono += w_differing(StereoWidener, rate, seed, 1, 1024,
+                                    **cell)
         stereo = 0
         for seed in seeds:
             stereo += w_differing(StereoWidener, rate, seed, 2, width=0.0)

From 4cdcd06fdf1485476342df9cbb6c678ba39647ec Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:32:39 -0500
Subject: [PATCH 13/76] AirSpace: a tape echo sent into a chamber, rebuilt from
 its Phase 6 card

The send runs through an audioecho.FeedbackDelay with its loop filters, an
audiobiquad Top Cut and the rebuilt Reverb as a chamber; the dry comes back
untouched beside it. Eleven macros and seven patches, the card's five
traits each tested and shown red on its planted fault (the plants live in
tests/airspace_plants.py so the kit checks them natively), every docstring
claim tied to a test. Declared: the chamber's P4 rows (a reset or a return
from Mix 0 empties the tank, which never re-converges with an uninterrupted
one) and the glide plant, which only a Time move can show.
---
 CHANGELOG.md                           |   9 +
 lib/audioeffects/rebuilt/airspace.py   | 511 +++++++++++++
 tests/airspace_plants.py               | 115 +++
 tests/support/kit_common.py            |   3 +
 tests/support/lifecycle.py             |  11 +
 tests/test_cpython_effects_airspace.py | 955 +++++++++++++++++++++++++
 6 files changed, 1604 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/airspace.py
 create mode 100644 tests/airspace_plants.py
 create mode 100644 tests/test_cpython_effects_airspace.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..267608a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,15 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`AirSpace` (rebuilt, Phase 6; not yet adopted):** a tape echo sent
+  into a chamber, with the dry untouched beside it, in
+  `audioeffects/rebuilt/airspace.py`. Eleven macros (Time, Feedback, Glide,
+  Drive, Loop Top, Loop Bass, Top Cut, Low Cut, Decay, Damping, Mix) and
+  seven patches replace the old rack's Space, Echo and Tone; the loop
+  darkens each repeat, Top Cut darkens the send once, Feedback stretches the
+  chamber's tail, and a Time move bends the repeats' pitch. The chamber is
+  the rebuilt `Reverb`, and `reset()` renders exactly as a fresh instance.
+  The old `rack.AirSpace` stays what the library serves until adoption.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
new file mode 100644
index 0000000..f9940fb
--- /dev/null
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -0,0 +1,511 @@
+"""`AirSpace` - a tape echo sent into a chamber, with the dry beside it.
+
+You send your signal to a tape echo whose repeats feed an echo chamber, and
+your dry signal comes back exactly as it went in: the filters, the drive and
+the tape act only on the send.
+
+Time (20 to 500 ms) is the gap between repeats and Feedback (0 to 0.85) how
+much of each repeat goes round again. Loop Top (1 to 16 kHz) and Loop Bass
+(20 Hz to 1 kHz) filter the loop, so each repeat is darker than the last,
+and Drive (0 to 1) saturates it. Top Cut (1 to 16 kHz) darkens everything
+sent to the chamber, once. Low Cut (20 to 500 Hz), Decay (0.3 to 10 s) and
+Damping (500 Hz to 16 kHz) set the chamber. Mix (0 to 2) is
+`audiodelays.Echo`'s: the dry at unity up to 1, the chamber alone at 2.
+
+More Feedback makes the chamber's tail longer: at Time 500 ms, Feedback 0.85
+at least triples it. At the defaults you hear the repeats as a longer
+chamber, not as a rhythm of echoes.
+
+Move Time while it plays and the repeats bend in pitch, the way tape does:
+down while it lengthens, up while it shortens. Glide (1 to 10 s) is how long
+a move across the whole Time range takes, so it sets how far they bend: 12 %
+at the default of 4 s.
+
+Keep your input at or under -6 dBFS: the dry is at unity and the chamber
+adds to it, so a hotter input can reach the rail. Latency is zero. `reset()` empties the tape and the chamber and restores
+patch 0, whose Time of 111 ms lands at once instead of gliding.
+
+The patches: Chamber Send (the defaults), Short Send, Long Send, Dark Loop,
+Bright Chamber, Driven Tape, Plain Chamber.
+
+**Limits**
+
+A control that jumps makes the output step: move it in small steps from the
+host if you need it smooth. Time is the exception: it glides.
+
+A patch that changes Time glides there too, and the repeats bend while it
+travels.
+
+At the defaults the repeats add only a little length to the tail; the
+stretch comes with Feedback above about 0.6 or a long Time.
+
+There is always at least 20 ms between the dry and the chamber.
+
+The loop's filters are gentle, and Drive's level is not compensated. The
+chamber's size is fixed, there is no tempo sync, and a mono source gets a
+mono rack.
+
+At Mix 0 the output is your input, byte for byte, and the tail that was
+ringing when Mix went to 0 is gone when it comes back.
+
+When your source ends, the tail rings out as it would on silence.
+"""
+
+VENDOR = "PyDevices"
+
+from array import array
+
+import audiocore
+
+from .. import _component
+
+try:
+    from .digitaldelay import laps_to_zero, whole_frames
+except ImportError:                     # pragma: no cover - after it lands
+    from ..digitaldelay import laps_to_zero, whole_frames
+try:
+    from .tapedelay import tone_excess
+except ImportError:                     # pragma: no cover - after it lands
+    from ..tapedelay import tone_excess
+# The module, not the class: a Component class at this module's top level
+# would be listed as a second provider here (`rebuilt.known()`).
+try:
+    from . import reverb as _reverb
+except ImportError:                     # pragma: no cover - after it lands
+    from .. import reverb as _reverb
+
+try:
+    import audioecho
+except ImportError:                     # pragma: no cover - a stock board
+    audioecho = None
+try:
+    import audiobiquad
+except ImportError:                     # pragma: no cover - a stock board
+    audiobiquad = None
+try:
+    import audioroute
+except ImportError:                     # pragma: no cover - a stock board
+    audioroute = None
+try:
+    import audiomixer
+except ImportError:                     # pragma: no cover - a stock board
+    audiomixer = None
+
+
+#: Frames per pull: the palette's block.
+BLOCK = 256
+
+TIME_MIN_MS = 20.0
+TIME_MAX_MS = 500.0
+
+#: The tape's line: Time's top plus headroom for the node's two-frame clamp
+#: (`audiodsp_feedback_delay.c:156-159`).
+LINE_MS = 505.0
+
+#: How far a move across the whole Time range runs, in ms: Glide is the
+#: time it takes, so `delay_slew` is this over Glide.
+FULL_RANGE_MS = TIME_MAX_MS - TIME_MIN_MS
+
+FEEDBACK_MAX = 0.85
+
+(TIME_I, FEEDBACK_I, GLIDE_I, DRIVE_I, LOOP_TOP_I, LOOP_BASS_I, TOP_CUT_I,
+ LOW_CUT_I, DECAY_I, DAMPING_I, MIX_I) = range(11)
+
+#: The constructor defaults, in macro order; NaN falls back to these.
+DEFAULTS = (111.0, 0.375, 4000.0, 0.2, 6000.0, 100.0, 5000.0, 100.0, 1.8,
+            4000.0, 0.35)
+
+#: Each default's step on the 0-127 grid (`_component.macro_of`): patch 0.
+#: While a macro sits on its default's step, the default itself plays, so
+#: a fresh instance, patch 0 and a host echoing `get_macro` all play
+#: exactly 111 ms, not the step's 112.08.
+DEFAULT_STEPS = (68, 56, 76, 25, 82, 52, 74, 64, 65, 76, 22)
+
+#: How close a 0..1 position must come to a default's step to play the
+#: default: far under one grid step (1/127), far over a float's rounding.
+STEP_TOLERANCE = 1e-6
+
+#: The chamber's indices in `Reverb`'s macro table that this rack drives.
+REVERB_DECAY_I = 1
+REVERB_DAMPING_I = 5
+REVERB_LOW_CUT_I = 7
+
+#: The chamber at this rack's defaults on `Reverb`'s grid: Character 85
+#: (chamber), Decay 65, Size 64 (1.004), Predelay 0 (the tape is the
+#: predelay), Diffusion 99 (0.70), Damping 76, Bandwidth 127 (Top Cut is the
+#: band), Low Cut 64, Mod Depth 19 (0.30 ms), Mod Rate 71 (0.89 Hz), Width
+#: 102 (0.80), Tone 64 (0 dB), Mix 127 (the tail alone).
+CHAMBER_PATCH = (85, 65, 64, 0, 99, 76, 127, 64, 19, 71, 102, 64, 127)
+
+#: Which of the rack's macros drive which of the chamber's.
+_CHAMBER_MACROS = ((LOW_CUT_I, REVERB_LOW_CUT_I), (DECAY_I, REVERB_DECAY_I),
+                   (DAMPING_I, REVERB_DAMPING_I))
+
+
+def _option(value, default):
+    """A constructor option as a float; NaN is the option's default."""
+    value = float(value)
+    if value != value:
+        return default
+    return value
+
+
+def _between(value, low, high):
+    if value < low:
+        return low
+    if value > high:
+        return high
+    return value
+
+
+def slew_of(glide_ms):
+    """`delay_slew` for a Glide: the whole Time range over Glide."""
+    return FULL_RANGE_MS / float(glide_ms)
+
+
+def _chamber_options():
+    """`Reverb`'s constructor options at `CHAMBER_PATCH`'s grid values, so
+    the Tank is cut once, as the chamber, and patch 0 moves no line."""
+    spans = _reverb.Reverb._MACRO_RANGES
+    names = ("decay", "size", "predelay_ms", "diffusion", "damping_hz",
+             "bandwidth_hz", "low_cut_hz", "mod_depth_ms", "mod_rate_hz",
+             "width", "tone_db", "mix")
+    options = {"character": "chamber", "patch": 0}
+    for index, name in zip(range(1, 13), names):
+        mode = _reverb.Reverb.MACRO_MODES.get(index, "UNIPOLAR")
+        position = _component.position_of_midi(mode, CHAMBER_PATCH[index])
+        options[name] = _component.macro_value(spans[index], position)
+    return options
+
+
+class AirSpace(_component.Component):
+    """A tape echo sent into a chamber. The module docstring is the
+    player's page."""
+
+    NAME = 'AirSpace'
+    DISPLAY_NAME = 'Air Space'
+    CATEGORIES = ('Effect Rack', 'Reverb')
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioecho", "audiobiquad", "audioroute", "audioverb")
+
+    class _Chamber(_reverb.Reverb):
+        """The rack's chamber: `Reverb` whose only patch is the chamber at
+        the rack's settings, so its own `reset()` lands there without a
+        re-cut. Nested, so the module holds one provider."""
+
+        PATCHES = {0: ("Chamber", CHAMBER_PATCH)}
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    INPUT_CEILING_DBFS = -6.0
+    TAIL_SAMPLES = None
+
+    MACRO_LABELS = ("Time", "Feedback", "Glide", "Drive", "Loop Top",
+                    "Loop Bass", "Top Cut", "Low Cut", "Decay", "Damping",
+                    "Mix")
+    MACRO_MODES = {
+        0: "UNIPOLAR",
+        1: "UNIPOLAR",
+        2: "UNIPOLAR",
+        3: "UNIPOLAR",
+        4: "UNIPOLAR",
+        5: "UNIPOLAR",
+        6: "UNIPOLAR",
+        7: "UNIPOLAR",
+        8: "UNIPOLAR",
+        9: "UNIPOLAR",
+        10: "UNIPOLAR",
+    }
+    _MACRO_RANGES = (
+        (TIME_MIN_MS, TIME_MAX_MS, "log"),  # 0  Time, ms
+        (0.0, FEEDBACK_MAX),                # 1  Feedback
+        (1000.0, 10000.0, "log"),           # 2  Glide, ms across the range
+        (0.0, 1.0),                         # 3  Drive, the loop's soft clip
+        (1000.0, 16000.0, "log"),           # 4  Loop Top, Hz
+        (20.0, 1000.0, "log"),              # 5  Loop Bass, Hz
+        (1000.0, 16000.0, "log"),           # 6  Top Cut, Hz
+        (20.0, 500.0, "log"),               # 7  Low Cut, Hz
+        (0.3, 10.0, "log"),                 # 8  Decay, s
+        (500.0, 16000.0, "log"),            # 9  Damping, Hz
+        (0.0, 2.0),                         # 10 Mix; dry at unity to 1
+    )
+
+    #: `_component.macro_of` of the card's settings; patch 0 is the
+    #: constructor's defaults on the grid (`DEFAULT_STEPS`).
+    PATCHES = {
+        0: ("Chamber Send", DEFAULT_STEPS),
+        1: ("Short Send", (43, 45, 76, 25, 82, 52, 82, 64, 50, 76, 22)),
+        2: ("Long Send", (107, 90, 76, 25, 82, 52, 74, 64, 77, 76, 22)),
+        3: ("Dark Loop", (68, 127, 76, 25, 32, 75, 74, 64, 65, 76, 22)),
+        4: ("Bright Chamber",
+            (68, 56, 76, 25, 82, 52, 114, 43, 72, 110, 22)),
+        5: ("Driven Tape", (68, 75, 76, 102, 64, 52, 74, 64, 65, 76, 22)),
+        6: ("Plain Chamber", (0, 0, 76, 25, 82, 52, 74, 64, 65, 76, 22)),
+    }
+
+    def _build(self, time_ms=111.0, feedback=0.375, glide_ms=4000.0,
+               drive=0.2, loop_top_hz=6000.0, loop_bass_hz=100.0,
+               top_cut_hz=5000.0, low_cut_hz=100.0, decay=1.8,
+               damping_hz=4000.0, mix=0.35, patch=None):
+        rate = self._sample_rate
+        channels = self._channel_count
+        options = (time_ms, feedback, glide_ms, drive, loop_top_hz,
+                   loop_bass_hz, top_cut_hz, low_cut_hz, decay, damping_hz,
+                   mix)
+        values = []
+        for index, value in enumerate(options):
+            span = self._MACRO_RANGES[index]
+            values.append(_between(_option(value, DEFAULTS[index]),
+                                   span[0], span[1]))
+
+        #: True once every macro has been seeded; before that a macro is
+        #: stored and not pushed.
+        self._ready = False
+        #: True once the voices have been played (`_wire`).
+        self._wired = False
+        #: What the nodes were last handed, by name.
+        self._handed = {}
+        self._frames = 1
+        #: The longest delay, in frames, the read head may still be at: a
+        #: shorter Time walks the head down, so the old one holds until the
+        #: tape is next emptied.
+        self._reach = 1
+
+        # The borrowed source's only reader: a width-1 MidSide passes it
+        # byte for byte in the palette's blocks, and Mix 0 hands it out, so
+        # whatever part of a source buffer it holds plays next whichever
+        # way the output goes. Its reset forwards nothing.
+        self._adapter = audioroute.MidSide(
+            self._source, width=1.0, sample_rate=rate, channel_count=channels)
+        # A MidSide with no source: a block of zeros per pull, which the
+        # voices prime from when they are wired (`_wire`).
+        self._hush = audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels)
+        self._in = audioroute.Port(self._hush)
+        self._split = audioroute.Splitter(self._in, taps=2)
+        self._fd = audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=channels, max_delay_ms=LINE_MS,
+            delay_frames=whole_frames(DEFAULTS[TIME_I], rate),
+            feedback=0.0, mix=2.0, damping_hz=0.0, cut_hz=0.0,
+            loop_drive=0.0, delay_slew=0.0)
+        self._fd.play(self._split.tap(1))
+        self._lp = audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=self._hz(DEFAULTS[TOP_CUT_I]),
+            sample_rate=rate, channel_count=channels)
+        self._lp.play(self._fd)
+        self._chamber = self._Chamber(self._lp, **_chamber_options())
+        self._mixer = audiomixer.Mixer(
+            voice_count=2, buffer_size=BLOCK * channels * 4,
+            channel_count=channels, bits_per_sample=16, samples_signed=True,
+            sample_rate=rate)
+        # The output: a width-1 MidSide over the mixer, byte for byte, whose
+        # reset forwards nothing. A host's reset of the output (a mixer
+        # voice's `play()` does one) would otherwise reach the Mixer, and
+        # CircuitPython's own Mixer drops frames there that audiodsp's
+        # keeps.
+        self._tail = audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate, channel_count=channels)
+        self._silence = audiocore.RawSample(
+            array("h", bytes(2 * 2 * channels)), sample_rate=rate,
+            channel_count=channels)
+
+        # Walked tail first: the Mixer and the Splitter are not reset (a
+        # voice resets its source, and neither voice holds a block between
+        # two pulls), the chamber by its own reset, the filter and the tape
+        # by their clears. Nothing here reaches the borrowed source.
+        self._own(self._silence, reset=False)
+        self._own(self._adapter, reset=False)
+        self._own(self._hush, reset=False)
+        self._own(self._in, reset=False)
+        self._own(self._split, reset=False)
+        self._own(self._fd, reset=self._clear_tape)
+        self._own(self._lp, reset=self._lp.clear)
+        self._own(self._chamber, reset=self._reset_chamber,
+                  deinit=self._chamber.deinit)
+        self._own(self._mixer, reset=False)
+        self._own(self._tail, reset=False)
+        self._output = self._adapter
+
+        self._init_macros(tuple(values))
+        # A default seeds its own step, so a fresh instance reads patch 0.
+        for index in range(len(values)):
+            if values[index] == DEFAULTS[index]:
+                self._macros[index] = _component.position_of_midi(
+                    "UNIPOLAR", DEFAULT_STEPS[index])
+        self._ready = True
+        for index in range(len(values)):
+            self._apply_macro(index, self._macros[index])
+        if patch is not None:
+            self.program_change(patch)
+
+    # -- the maps ------------------------------------------------------
+
+    def _value(self, index):
+        """Macro `index` in its own units: the default itself on the
+        default's step, the span's law elsewhere."""
+        position = self._macros[index]
+        step = DEFAULT_STEPS[index] / 127.0
+        if abs(position - step) <= STEP_TOLERANCE:
+            return DEFAULTS[index]
+        return _component.macro_value(self._MACRO_RANGES[index], position)
+
+    def macro(self, index):
+        """What macro `index` currently stands for, in its own units: what
+        plays, the default itself on the default's step."""
+        self._check_live()
+        return self._value(index)
+
+    def _dry_level(self, mix):
+        """The dry voice's level, min(1, 2 - Mix). At one channel unity is
+        handed as 1 - 2^-15, which every Mixer this class meets passes
+        through exactly: CircuitPython's own `audiomixer` turns 1.0 into
+        32768 / 32767 and puts the samples nearest the rails one LSB hot.
+        Two channels keep 1.0 (`MultiTapDelay._dry_level` has why)."""
+        level = 1.0 if mix <= 1.0 else 2.0 - mix
+        if level >= 1.0 and self._channel_count == 1:
+            return 1.0 - 2.0 ** -15
+        return level
+
+    def _levels(self):
+        mix = self._value(MIX_I)
+        voices = self._mixer.voice
+        voices[0].level = self._dry_level(mix)
+        voices[1].level = mix if mix < 1.0 else 1.0
+
+    # -- hooks a planted fault overrides --------------------------------
+
+    def _hand_tape(self, **settings):
+        """Everything the tape node is handed goes through here."""
+        self._handed.update(settings)
+        self._fd.set(**settings)
+
+    def _wet_source(self):
+        """What the wet voice plays: the chamber."""
+        return self._chamber.output
+
+    # -- applying ------------------------------------------------------
+
+    def _apply_macro(self, index, position):
+        del position
+        if not self._ready:
+            return
+        value = self._value(index)
+        if index == TIME_I:
+            frames = whole_frames(value, self._sample_rate)
+            if frames < 1:
+                frames = 1
+            self._frames = frames
+            if frames > self._reach:
+                self._reach = frames
+            self._hand_tape(delay_frames=frames)
+        elif index == FEEDBACK_I:
+            self._hand_tape(feedback=value)
+        elif index == GLIDE_I:
+            self._hand_tape(delay_slew=slew_of(value))
+        elif index == DRIVE_I:
+            self._hand_tape(loop_drive=value)
+        elif index == LOOP_TOP_I:
+            self._hand_tape(damping_hz=self._hz(value))
+        elif index == LOOP_BASS_I:
+            self._hand_tape(cut_hz=self._hz(value))
+        elif index == TOP_CUT_I:
+            frequency = self._hz(value)
+            self._handed["top_cut_hz"] = frequency
+            self._lp.frequency = frequency
+        elif index == MIX_I:
+            self._route()
+        else:
+            self._push_chamber(index)
+
+    def _push_chamber(self, index):
+        """Hand the chamber the rack's Low Cut, Decay or Damping, as the
+        unquantized position of the value the rack plays."""
+        for ours, theirs in _CHAMBER_MACROS:
+            if ours == index:
+                position = _component.macro_position(
+                    self._MACRO_RANGES[ours], self._value(ours))
+                self._chamber.set_macro(theirs, 127.0 * position)
+                self._handed["chamber_%d" % theirs] = position
+
+    def _route(self):
+        """Mix 0 points the output at the input adapter (a wire); above 0 at
+        the mixer, wiring it the first time and emptying what the graph
+        held when it was routed around."""
+        if self._value(MIX_I) <= 0.0:
+            self._route_around(self._adapter)
+            return
+        self._levels()
+        if not self._wired:
+            self._wire()
+        else:
+            self._rejoin()
+        self._output = self._tail
+
+    def _wire(self):
+        """Play the voices, the first time Mix is above 0.
+
+        A voice's `play()` primes a block from its source. With the
+        Splitter on `_hush` that block is zeros, and one pull of the mixer
+        hands it out, so wiring takes nothing from the borrowed source and
+        leaves no voice holding a block. The graph is then emptied, so the
+        chamber's modulation and the tape start where a `reset()` leaves
+        them. Without `audiocore.get_buffer` the voices prime the source's
+        next block, which the next pull plays."""
+        pull = getattr(audiocore, "get_buffer", None)
+        voices = self._mixer.voice
+        _component.open_level_gates(self._mixer, voices, self._silence)
+        if pull is None:
+            self._in.play(self._adapter)
+        voices[0].play(self._split.tap(0))
+        voices[1].play(self._wet_source())
+        if pull is not None:
+            pull(self._mixer)
+            self._in.play(self._adapter)
+            self._clear_nodes()
+        self._wired = True
+
+    def _clear_tape(self):
+        """Empty the tape. The node then lands its read head on the next
+        Time it is handed instead of gliding there."""
+        self._fd.clear()
+        self._reach = self._frames
+
+    def _reset_chamber(self):
+        """The chamber's own reset lands on its one patch; the rack's three
+        chamber macros then go back in."""
+        self._chamber.reset()
+        if self._ready:
+            for ours, _theirs in _CHAMBER_MACROS:
+                self._push_chamber(ours)
+
+    # -- the contract's reads ------------------------------------------
+
+    @property
+    def tail_samples(self):
+        """Frames until the output is exactly zero once the input stops, as
+        an upper bound: the tape's repeats, the Top Cut's ring and the
+        chamber's own tail, end to end."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        """`tail_samples` without the liveness check: a plain method, so a
+        subclass can reach it on MicroPython, whose `property` has no
+        `fget`.
+
+        `laps_to_zero` laps at the Feedback in force, each as long as the
+        longest delay the read head may be at plus one frame for the
+        interpolated read plus the memory of the loop's two one-poles;
+        then `_component.biquad_ring` of the Top Cut; then the chamber's
+        `tail_samples`. 0 at Mix 0, where the output is the input."""
+        if self._value(MIX_I) <= 0.0:
+            return 0
+        rate = self._sample_rate
+        top_memory, excess = tone_excess(self._handed["damping_hz"], rate)
+        bass_memory, _bass = tone_excess(self._handed["cut_hz"], rate)
+        laps = laps_to_zero(self._handed["feedback"], excess)
+        repeats = laps * (self._reach + 1 + top_memory + bass_memory)
+        ring = _component.biquad_ring(self._lp) or 0
+        return int(repeats + ring + self._chamber.tail_samples)
diff --git a/tests/airspace_plants.py b/tests/airspace_plants.py
new file mode 100644
index 0000000..c3bbba5
--- /dev/null
+++ b/tests/airspace_plants.py
@@ -0,0 +1,115 @@
+"""`AirSpace`'s planted faults, one or two per trait of its card.
+
+Kept apart from the test module, and free of numpy and unittest, so the
+kit's plant-validity check runs them on MicroPython and CircuitPython too
+(`tests/support/kit.py AirSpace --plants-module airspace_plants`). The test
+module imports them from here and lists them in its own `KIT_PLANTS`.
+"""
+
+import audiobiquad
+
+from audioeffects import rebuilt
+from audioeffects.rebuilt import airspace as space
+
+#: Read by `_component`'s metadata check off the module a class lives in.
+VENDOR = "PyDevices"
+
+AirSpace = rebuilt.module_class("AirSpace")
+
+
+class SendFirst(AirSpace):
+    """T1: the Top Cut ahead of the Splitter, as the old rack had it, so the
+    dry is filtered too; the send's own filter is left open."""
+
+    def _build(self, *args, **options):
+        self._pre = None
+        AirSpace._build(self, *args, **options)
+        self._pre = audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS,
+            frequency=self._hz(self._value(space.TOP_CUT_I)),
+            sample_rate=self._sample_rate, channel_count=self._channel_count)
+        self._pre.play(self._source)
+        self._adapter.play(self._pre)
+        self._own(self._pre, reset=self._pre.clear)
+        self._lp.frequency = self._hz(20000.0)
+
+    def _apply_macro(self, index, position):
+        AirSpace._apply_macro(self, index, position)
+        pre = getattr(self, "_pre", None)
+        if pre is not None and index == space.TOP_CUT_I:
+            pre.frequency = self._hz(self._value(space.TOP_CUT_I))
+            self._lp.frequency = self._hz(20000.0)
+
+
+class LoopOnSend(AirSpace):
+    """T2, first half: the loop's low-pass taken out of the loop and put on
+    the send as a second Biquad, so every repeat is darkened alike."""
+
+    def _build(self, *args, **options):
+        self._loop_lp = None
+        self._loop_hz = space.DEFAULTS[space.LOOP_TOP_I]
+        AirSpace._build(self, *args, **options)
+        self._loop_lp = audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=self._loop_hz,
+            sample_rate=self._sample_rate, channel_count=self._channel_count)
+        self._loop_lp.play(self._fd)
+        self._lp.play(self._loop_lp)
+        self._own(self._loop_lp, reset=self._loop_lp.clear)
+
+    def _hand_tape(self, **settings):
+        if "damping_hz" in settings:
+            self._loop_hz = settings["damping_hz"]
+            settings["damping_hz"] = 0.0
+            loop_lp = getattr(self, "_loop_lp", None)
+            if loop_lp is not None:
+                loop_lp.frequency = self._loop_hz
+        AirSpace._hand_tape(self, **settings)
+
+
+class TopCutInLoop(AirSpace):
+    """T2, second half: Top Cut wired to the loop's low-pass instead of the
+    send's filter, so it darkens each repeat more than the last."""
+
+    def _apply_macro(self, index, position):
+        AirSpace._apply_macro(self, index, position)
+        if self._ready and index in (space.TOP_CUT_I, space.LOOP_TOP_I):
+            self._hand_tape(damping_hz=self._hz(self._value(space.TOP_CUT_I)))
+            self._lp.frequency = self._hz(20000.0)
+
+
+class NoFeedback(AirSpace):
+    """T3: the node is handed no feedback, whatever Feedback says."""
+
+    def _hand_tape(self, **settings):
+        if "feedback" in settings:
+            settings["feedback"] = 0.0
+        AirSpace._hand_tape(self, **settings)
+
+
+class BareRepeats(AirSpace):
+    """T4: the chamber is a wire: the repeats reach the output bare."""
+
+    def _wet_source(self):
+        return self._lp
+
+
+class JumpTime(AirSpace):
+    """T5: the node is handed no slew, so a Time move jumps."""
+
+    def _hand_tape(self, **settings):
+        if "delay_slew" in settings:
+            settings["delay_slew"] = 0.0
+        AirSpace._hand_tape(self, **settings)
+
+
+#: The kit's plant table (KIT.md, plants). NoFeedback is judged at Long
+#: Send: at the defaults it is what Feedback 0 renders, a setting rather
+#: than a fault.
+KIT_PLANTS = {
+    "T1": SendFirst,
+    "T2a": LoopOnSend,
+    "T2b": TopCutInLoop,
+    "T3": (NoFeedback, 2),
+    "T4": BareRepeats,
+    "T5": JumpTime,
+}
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..21589be 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,9 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("AirSpace", "plants", "T5/"): "the glide plant changes only how a"
+    " Time move travels, and the plant check renders at fixed settings, so"
+    " it reads as the clean class; the class's T5 tests move Time",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..34d1428 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -241,6 +241,17 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (two or three moves before one pull)',
     ("PingPongDelay", 'E4-m2=', 'P5'):
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (Mix)',
+    # AirSpace: its chamber is the rebuilt Reverb, whose rows above say why
+    # a tank that was emptied, or moved in its loop, never meets an
+    # uninterrupted one byte for byte. A reset renders exactly as a fresh
+    # instance does (the class's TheReset tests); it is the control that
+    # never was reset.
+    ("AirSpace", "E1-", "P4"): "reset() empties the chamber and restarts its modulation, so it never re-converges with the uninterrupted control (Reverb's E1 P4)",
+    ("AirSpace", "E4-m10=", "P4"): "Mix to 0 and back empties the chamber and restarts its modulation (as E1)",
+    ("AirSpace", "E5-", "P4"): "Mix to 0 and back empties the chamber and restarts its modulation (as E1)",
+    ("AirSpace", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the chamber (as E1)",
+    ("AirSpace", "E6-", "P4"): "a patch move reaches the chamber's loop and leaves its tank off the control's for good (Reverb's E6 P4)",
+    ("AirSpace", "E11-", "P4"): "moves that reach the chamber's loop or empty it leave its tank off the control's for good (Reverb's E11 P4)",
 }
 
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
new file mode 100644
index 0000000..fc0603b
--- /dev/null
+++ b/tests/test_cpython_effects_airspace.py
@@ -0,0 +1,955 @@
+"""`AirSpace`'s own trait and planted-fault tests.
+
+The card (frozen 2026-10-12) has five traits, T1-T5. Each is measured here
+at a few of its cells, as the card words it, and the same measurement is
+shown red on the card's planted fault; the measurements of T2-T5 are also
+red on the class built as a wire. The full grids (every seed, both rates,
+stereo and mono) are the evidence pack's, from the probe script beside it.
+
+Every law a measurement checks against is written out here from the card,
+never taken from the class. No numpy: plain sums, a radix-2 FFT and
+Goertzel. The planted faults live in `airspace_plants.py`, which the kit
+also runs natively.
+
+The class is reached by `rebuilt.module_class("AirSpace")`.
+"""
+
+import cmath
+import math
+import os
+import sys
+import unittest
+from array import array
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "support"))
+sys.path.insert(0, os.path.dirname(__file__))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "lib"))
+
+import audiocore                                            # noqa: E402
+import airspace_plants as plants                            # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+VENDOR = "PyDevices"
+
+AirSpace = rebuilt.module_class("AirSpace")
+
+BLOCK = 256
+TIME_I, FEEDBACK_I, GLIDE_I, DRIVE_I, LOOP_TOP_I, LOOP_BASS_I, TOP_CUT_I, \
+    LOW_CUT_I, DECAY_I, DAMPING_I, MIX_I = range(11)
+
+#: The kit's plant table (KIT.md): one or two planted faults per trait.
+KIT_PLANTS = plants.KIT_PLANTS
+
+
+# --------------------------------------------------------------------------
+# The card's laws, written out independently of the class
+
+
+SPANS = {
+    TIME_I: (20.0, 500.0, True),
+    FEEDBACK_I: (0.0, 0.85, False),
+    GLIDE_I: (1000.0, 10000.0, True),
+    DRIVE_I: (0.0, 1.0, False),
+    LOOP_TOP_I: (1000.0, 16000.0, True),
+    LOOP_BASS_I: (20.0, 1000.0, True),
+    TOP_CUT_I: (1000.0, 16000.0, True),
+    LOW_CUT_I: (20.0, 500.0, True),
+    DECAY_I: (0.3, 10.0, True),
+    DAMPING_I: (500.0, 16000.0, True),
+    MIX_I: (0.0, 2.0, False),
+}
+
+#: The card's section 3 defaults, in macro order.
+CARD_DEFAULTS = (111.0, 0.375, 4000.0, 0.2, 6000.0, 100.0, 5000.0, 100.0,
+                 1.8, 4000.0, 0.35)
+
+PATCH_NAMES = ("Chamber Send", "Short Send", "Long Send", "Dark Loop",
+               "Bright Chamber", "Driven Tape", "Plain Chamber")
+
+
+def law_value(index, midi):
+    low, high, log = SPANS[index]
+    x = midi / 127.0
+    if log:
+        return low * (high / low) ** x
+    return low + (high - low) * x
+
+
+def law_midi(index, value):
+    """The 0-127 position, unquantized, of `value` on macro `index`."""
+    low, high, log = SPANS[index]
+    if log:
+        return 127.0 * math.log(value / low) / math.log(high / low)
+    return 127.0 * (value - low) / (high - low)
+
+
+def law_frames(ms, rate):
+    """Time lands on the nearest whole frame."""
+    return int(math.floor(ms * rate / 1000.0 + 0.5))
+
+
+def law_slew(glide_ms):
+    """Glide is how long a move across the whole 480 ms range takes."""
+    return 480.0 / glide_ms
+
+
+def law_levels(mix):
+    """`audiodelays.Echo`'s Mix: (dry, wet)."""
+    return (1.0 if mix <= 1.0 else 2.0 - mix, mix if mix < 1.0 else 1.0)
+
+
+# --------------------------------------------------------------------------
+# Material and rendering
+
+
+class Feed:
+    """int16 frames in 256-frame blocks, then silence for ever."""
+
+    def __init__(self, data, rate, channels):
+        self.sample_rate = rate
+        self.channel_count = channels
+        self.bits_per_sample = 16
+        self.samples_signed = True
+        self._data = data
+        self._at = 0
+        self._stride = BLOCK * channels
+
+    def _reset_buffer(self, single_channel_output=False, audio_channel=0):
+        pass
+
+    def _get_buffer(self, single_channel_output=False, audio_channel=0):
+        chunk = self._data[self._at:self._at + self._stride]
+        self._at += self._stride
+        if len(chunk) < self._stride:
+            chunk = chunk + array("h", bytes(2 * (self._stride - len(chunk))))
+        return audiocore.GET_BUFFER_MORE_DATA, memoryview(chunk)
+
+
+def lcg_noise(frames, channels, rms, seed):
+    """Uniform noise at `rms` LSB, its own stream per seed."""
+    amp = rms * math.sqrt(3.0)
+    state = (seed * 7919 + 17) & 0x7FFFFFFF
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(frames * channels):
+        state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+        out[i] = int(round((state / 2147483647.0 * 2.0 - 1.0) * amp))
+    return out
+
+
+def burst(on_frames, total_frames, channels, rms, seed):
+    data = array("h", bytes(2 * total_frames * channels))
+    data[0:on_frames * channels] = lcg_noise(on_frames, channels, rms, seed)
+    return data
+
+
+def tone(hz, frames, rate, channels, peak):
+    out = array("h", bytes(2 * frames * channels))
+    for n in range(frames):
+        v = int(round(peak * math.sin(2.0 * math.pi * hz * n / rate)))
+        for c in range(channels):
+            out[n * channels + c] = v
+    return out
+
+
+def build(cls, data, rate, channels, patch=None, **options):
+    return cls(Feed(data, rate, channels), patch=patch, **options)
+
+
+def render(effect, frames, actions=None):
+    """`frames` frames of the output, int16 interleaved. `actions` maps a
+    pull index to a callable taken before that pull."""
+    channels = effect.channel_count
+    out = array("h")
+    k = 0
+    while len(out) < frames * channels:
+        if actions and k in actions:
+            actions[k](effect)
+        _, data = audiocore.get_buffer(effect.output)
+        out.extend(array("h", bytes(data)))
+        k += 1
+    return out[:frames * channels]
+
+
+def mono(pcm, channels):
+    """Stereo read as the mean of the two channels."""
+    if channels == 1:
+        return [float(v) for v in pcm]
+    return [(pcm[i] + pcm[i + 1]) * 0.5 for i in range(0, len(pcm), 2)]
+
+
+def set_value(effect, index, value):
+    effect.set_macro(index, law_midi(index, value))
+
+
+# --------------------------------------------------------------------------
+# Readers
+
+
+def fft(values):
+    """Radix-2 FFT of a list of complex numbers whose length is a power of
+    two."""
+    n = len(values)
+    out = list(values)
+    j = 0
+    for i in range(1, n):
+        bit = n >> 1
+        while j & bit:
+            j ^= bit
+            bit >>= 1
+        j |= bit
+        if i < j:
+            out[i], out[j] = out[j], out[i]
+    size = 2
+    while size <= n:
+        step = cmath.exp(-2j * math.pi / size)
+        half = size // 2
+        for start in range(0, n, size):
+            w = 1.0
+            for k in range(half):
+                a = out[start + k]
+                b = out[start + k + half] * w
+                out[start + k] = a + b
+                out[start + k + half] = a - b
+                w *= step
+        size *= 2
+    return out
+
+
+def band_energies(x, rate, bands):
+    """Energy of `x` in each (low, high) Hz band, zero-padded to a power
+    of two."""
+    n = 1
+    while n < len(x):
+        n *= 2
+    spectrum = fft([complex(v) for v in x] + [0j] * (n - len(x)))
+    out = []
+    for low, high in bands:
+        k0 = int(math.ceil(low * n / rate))
+        k1 = int(math.floor(high * n / rate))
+        out.append(sum(abs(spectrum[k]) ** 2 for k in range(k0, k1 + 1)))
+    return out
+
+
+def goertzel_power(x, hz, rate):
+    """Goertzel under a Hann window, so a strong tone elsewhere does not
+    leak into the bin read."""
+    w = 2.0 * math.pi * hz / rate
+    coeff = 2.0 * math.cos(w)
+    s1 = s2 = 0.0
+    n = len(x)
+    step = 2.0 * math.pi / (n - 1) if n > 1 else 0.0
+    for i, v in enumerate(x):
+        s0 = v * (0.5 - 0.5 * math.cos(step * i)) + coeff * s1 - s2
+        s2 = s1
+        s1 = s0
+    return s1 * s1 + s2 * s2 - coeff * s1 * s2
+
+
+class Red(Exception):
+    """A window held no energy, or was empty or too short: red, never a
+    pass or a NaN."""
+
+
+def db_ratio(num, den):
+    if num <= 0.0 or den <= 0.0:
+        raise Red("a window held no energy")
+    return 10.0 * math.log10(num / den)
+
+
+# --------------------------------------------------------------------------
+# The traits' measurements
+
+
+def t1_mismatches(cls, rate, channels, mix, seed, patch=None, **options):
+    """T1: a noise burst 1 ms shorter than Time, output against input over
+    frames 0 to Time; the count of frames that differ."""
+    probe = cls(Feed(array("h", bytes(2 * channels * BLOCK)), rate,
+                     channels), patch=patch, **options)
+    time_ms = probe.macro(TIME_I)
+    probe.deinit()
+    frames = law_frames(time_ms, rate)
+    on = frames - law_frames(1.0, rate)
+    data = burst(on, frames + BLOCK, channels, 8000.0, seed)
+    effect = build(cls, data, rate, channels, patch, **options)
+    effect.set_macro(MIX_I, law_midi(MIX_I, mix))
+    out = render(effect, frames)
+    effect.deinit()
+    if not any(out):
+        raise Red("the output was silent")
+    return sum(1 for i in range(frames * channels) if out[i] != data[i])
+
+
+def t2_darkening(cls, rate, channels, seed, loop_top, top_cut):
+    """T2: the 3.5-8 kHz over 200-1000 Hz energy ratio in dB, at 150-450
+    ms minus at 1000-1300 ms, at Mix 2, Feedback 0.85, a 20 ms burst."""
+    total = int(1.35 * rate)
+    data = burst(law_frames(20.0, rate), total, channels, 4000.0, seed)
+    effect = build(cls, data, rate, channels, mix=2.0, feedback=0.85,
+                   loop_top_hz=loop_top, top_cut_hz=top_cut)
+    x = mono(render(effect, total), channels)
+    effect.deinit()
+    bands = ((3500.0, 8000.0), (200.0, 1000.0))
+    early = x[int(0.15 * rate):int(0.45 * rate)]
+    late = x[int(1.0 * rate):int(1.3 * rate)]
+    hi_e, lo_e = band_energies(early, rate, bands)
+    hi_l, lo_l = band_energies(late, rate, bands)
+    return db_ratio(hi_e, lo_e) - db_ratio(hi_l, lo_l)
+
+
+def t2_added(cls, rate, channels, seed, loop_top=16000.0, top_cut=16000.0):
+    """T2's reading: the darkening a setting adds over Loop Top and Top
+    Cut at 16 kHz."""
+    return (t2_darkening(cls, rate, channels, seed, loop_top, top_cut)
+            - t2_darkening(cls, rate, channels, seed, 16000.0, 16000.0))
+
+
+def envelope_db(x, frame):
+    """Mean square in dB per non-overlapping frame of `frame` samples."""
+    out = []
+    for start in range(0, len(x) - frame + 1, frame):
+        power = sum(v * v for v in x[start:start + frame]) / frame
+        out.append(10.0 * math.log10(power) if power > 0.0 else -1e9)
+    return out
+
+
+def t3_tail_s(cls, rate, channels, seed, time_ms, feedback, seconds=12.0):
+    """T3: the time until the 10 ms envelope last sits within 40 dB of
+    its peak, at Mix 2, a 20 ms burst."""
+    total = int(seconds * rate)
+    data = burst(law_frames(20.0, rate), total, channels, 4000.0, seed)
+    effect = build(cls, data, rate, channels, mix=2.0, time_ms=time_ms,
+                   feedback=feedback)
+    x = mono(render(effect, total), channels)
+    effect.deinit()
+    env = envelope_db(x, int(round(0.01 * rate)))
+    peak = max(env)
+    if peak <= -1e8:
+        raise Red("the render held no energy")
+    last = max(i for i, v in enumerate(env) if v >= peak - 40.0)
+    if last >= len(env) - 50:
+        raise Red("the tail ran to the end of the render")
+    return (last + 1) * 0.01
+
+
+def t3_ratio(cls, rate, channels, seed, time_ms, feedback):
+    return (t3_tail_s(cls, rate, channels, seed, time_ms, feedback)
+            / t3_tail_s(cls, rate, channels, seed, time_ms, 0.0))
+
+
+def t4_reading(cls, rate, channels, seed, time_ms=111.0, feedback=0.375,
+               seconds=8.0):
+    """T4: the normalised autocorrelation, at a lag of one Time, of the
+    clamped and detrended 5 ms envelope, at Mix 2, a 10 ms burst."""
+    total = int(seconds * rate)
+    data = burst(law_frames(10.0, rate), total, channels, 4000.0, seed)
+    effect = build(cls, data, rate, channels, mix=2.0, time_ms=time_ms,
+                   feedback=feedback)
+    x = mono(render(effect, total), channels)
+    effect.deinit()
+    env = envelope_db(x, int(round(0.005 * rate)))
+    peak = max(env)
+    if peak <= -1e8:
+        raise Red("the render held no energy")
+    floor = peak - 40.0
+    first = int(round((time_ms + 60.0) / 5.0))
+    last = max(i for i, v in enumerate(env) if v >= floor)
+    lag = int(round(time_ms / 5.0))
+    window = [max(v, floor) for v in env[first:last + 1]]
+    if len(window) < 2 * lag:
+        raise Red("the window was shorter than two lags")
+    n = len(window)
+    mean_i = (n - 1) / 2.0
+    mean_v = sum(window) / n
+    sxx = sum((i - mean_i) ** 2 for i in range(n))
+    slope = sum((i - mean_i) * (v - mean_v)
+                for i, v in enumerate(window)) / sxx
+    resid = [v - (mean_v + slope * (i - mean_i))
+             for i, v in enumerate(window)]
+    energy = sum(v * v for v in resid)
+    if energy <= 0.0:
+        raise Red("the window was flat")
+    return sum(resid[i] * resid[i + lag] for i in range(n - lag)) / energy
+
+
+def t5_bend_db(cls, rate, channels, glide_ms, from_ms, to_ms):
+    """T5: the bent frequency's power over the held render's, from 50 ms
+    into a Time move to 20 ms before its end (at most 1.6 s), on a held
+    1 kHz tone at Mix 2. Returns dB."""
+    slew = law_slew(glide_ms)
+    move_at = int(round(rate / BLOCK))           # the pull nearest 1 s
+    start = move_at * BLOCK
+    travel_s = abs(to_ms - from_ms) / 1000.0 / slew
+    begin = start + int(0.05 * rate)
+    end = start + int(min(travel_s - 0.02, 1.6) * rate)
+    if end <= begin:
+        raise Red("the window was empty")
+    bent = 1000.0 * (1.0 - slew if to_ms > from_ms else 1.0 + slew)
+    data = tone(1000.0, end + BLOCK, rate, channels, 8000.0)
+    powers = []
+    for move in (True, False):
+        effect = build(cls, data, rate, channels, mix=2.0, time_ms=from_ms,
+                       glide_ms=glide_ms)
+        actions = None
+        if move:
+            actions = {move_at: lambda e: set_value(e, TIME_I, to_ms)}
+        x = mono(render(effect, end, actions), channels)
+        effect.deinit()
+        powers.append(goertzel_power(x[begin:end], bent, rate))
+    return db_ratio(powers[0], powers[1])
+
+
+class Wire(AirSpace):
+    """Every measurement's control: the class built as a wire."""
+
+    def _route(self):
+        self._route_around(self._adapter)
+
+
+# --------------------------------------------------------------------------
+# T1
+
+
+class T1DryIsUntouched(unittest.TestCase):
+
+    def test_every_patch_stereo_48k(self):
+        for patch in sorted(AirSpace.PATCHES):
+            for mix in (0.5, 1.0):
+                with self.subTest(patch=patch, mix=mix):
+                    self.assertEqual(
+                        t1_mismatches(AirSpace, 48000, 2, mix, 1, patch), 0)
+
+    def test_the_times_and_the_hardest_settings(self):
+        cells = [dict(time_ms=20.0), dict(time_ms=111.0),
+                 dict(time_ms=500.0),
+                 dict(top_cut_hz=1000.0, loop_top_hz=1000.0, drive=1.0)]
+        for rate in (48000, 22050):
+            for channels in (2, 1):
+                for options in cells:
+                    with self.subTest(rate=rate, channels=channels,
+                                      **options):
+                        self.assertEqual(t1_mismatches(
+                            AirSpace, rate, channels, 1.0, 2, **options), 0)
+
+    def test_red_on_the_top_cut_ahead_of_the_splitter(self):
+        self.assertGreater(
+            t1_mismatches(plants.SendFirst, 48000, 2, 1.0, 1), 0)
+
+
+# --------------------------------------------------------------------------
+# T2
+
+
+class T2EachRepeatDarker(unittest.TestCase):
+
+    CELLS = ((48000, 2), (22050, 1))
+
+    def test_loop_top_darkens_each_repeat(self):
+        for rate, channels in self.CELLS:
+            for loop_top in (2000.0, 4000.0):
+                with self.subTest(rate=rate, channels=channels,
+                                  loop_top=loop_top):
+                    added = t2_added(AirSpace, rate, channels, 1,
+                                     loop_top=loop_top)
+                    if loop_top == 2000.0:
+                        self.assertGreaterEqual(added, 6.0)
+                    else:
+                        self.assertGreater(added, 0.0)
+
+    def test_top_cut_darkens_once(self):
+        for rate, channels in self.CELLS:
+            for top_cut in (2000.0, 4000.0):
+                with self.subTest(rate=rate, channels=channels,
+                                  top_cut=top_cut):
+                    self.assertLessEqual(
+                        t2_added(AirSpace, rate, channels, 1,
+                                 top_cut=top_cut), 1.0)
+
+    def test_red_on_the_loop_filter_moved_onto_the_send(self):
+        self.assertLess(t2_added(plants.LoopOnSend, 48000, 2, 1,
+                                 loop_top=2000.0), 6.0)
+
+    def test_red_on_top_cut_wired_into_the_loop(self):
+        self.assertGreater(t2_added(plants.TopCutInLoop, 48000, 2, 1,
+                                    top_cut=2000.0), 1.0)
+
+    def test_red_on_a_wire(self):
+        with self.assertRaises(Red):
+            t2_added(Wire, 48000, 2, 1, loop_top=2000.0)
+
+
+# --------------------------------------------------------------------------
+# T3
+
+
+class T3FeedbackLengthensTheTail(unittest.TestCase):
+
+    #: (Time ms, Feedback, the card's bar).
+    BARS = ((500.0, 0.375, 1.3), (500.0, 0.6, 2.0), (500.0, 0.85, 3.0),
+            (111.0, 0.85, 1.6))
+
+    def test_the_bars(self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            for time_ms, feedback, bar in self.BARS:
+                with self.subTest(rate=rate, channels=channels,
+                                  time_ms=time_ms, feedback=feedback):
+                    self.assertGreaterEqual(
+                        t3_ratio(AirSpace, rate, channels, 1, time_ms,
+                                 feedback), bar)
+
+    def test_the_default_adds_only_a_little(self):
+        # Not one of the card's bars: its Limits sentence. The probe read
+        # 1 to 6 %.
+        ratio = t3_ratio(AirSpace, 48000, 2, 1, 111.0, 0.375)
+        self.assertGreaterEqual(ratio, 1.0)
+        self.assertLess(ratio, 1.1)
+
+    def test_red_on_no_feedback(self):
+        self.assertLess(t3_ratio(plants.NoFeedback, 48000, 2, 1, 500.0,
+                                 0.85), 3.0)
+
+    def test_red_on_a_wire(self):
+        self.assertLess(t3_ratio(Wire, 48000, 2, 1, 500.0, 0.85), 3.0)
+
+
+# --------------------------------------------------------------------------
+# T4
+
+
+class T4HeardAsAChamber(unittest.TestCase):
+
+    def test_the_cells(self):
+        cells = ((111.0, 0.375), (200.0, 0.375), (200.0, 0.6))
+        for rate, channels in ((48000, 2), (22050, 1)):
+            for time_ms, feedback in cells:
+                with self.subTest(rate=rate, channels=channels,
+                                  time_ms=time_ms, feedback=feedback):
+                    self.assertLessEqual(
+                        t4_reading(AirSpace, rate, channels, 1, time_ms,
+                                   feedback), 0.6)
+
+    def test_red_on_bare_repeats(self):
+        self.assertGreater(t4_reading(plants.BareRepeats, 48000, 2, 1,
+                                      200.0, 0.6), 0.6)
+
+    def test_red_on_a_wire(self):
+        with self.assertRaises(Red):
+            t4_reading(Wire, 48000, 2, 1, 200.0, 0.6)
+
+
+# --------------------------------------------------------------------------
+# T5
+
+
+class T5TimeBendsThePitch(unittest.TestCase):
+
+    def test_the_bend_both_ways_at_every_glide(self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            for glide in (1000.0, 4000.0, 10000.0):
+                for from_ms, to_ms in ((111.0, 222.0), (222.0, 111.0)):
+                    with self.subTest(rate=rate, channels=channels,
+                                      glide=glide, move=(from_ms, to_ms)):
+                        self.assertGreaterEqual(
+                            t5_bend_db(AirSpace, rate, channels, glide,
+                                       from_ms, to_ms), 40.0)
+
+    def test_red_on_a_jump(self):
+        self.assertLess(t5_bend_db(plants.JumpTime, 48000, 2, 4000.0,
+                                   111.0, 222.0), 40.0)
+
+    def test_red_on_a_wire(self):
+        self.assertLess(t5_bend_db(Wire, 48000, 2, 4000.0, 111.0, 222.0),
+                        40.0)
+
+
+# --------------------------------------------------------------------------
+# The surface
+
+
+def fresh(rate=48000, channels=2, patch=None, **options):
+    data = array("h", bytes(2 * channels * BLOCK))
+    return build(AirSpace, data, rate, channels, patch, **options)
+
+
+class TheSurface(unittest.TestCase):
+
+    def test_the_spans(self):
+        effect = fresh()
+        for index, (low, high, _log) in SPANS.items():
+            for midi, want in ((0, low), (127, high)):
+                with self.subTest(index=index, midi=midi):
+                    effect.set_macro(index, midi)
+                    self.assertAlmostEqual(effect.macro(index), want,
+                                           delta=abs(want) * 1e-9)
+        effect.deinit()
+
+    def test_the_labels_and_modes(self):
+        self.assertEqual(AirSpace.MACRO_LABELS, (
+            "Time", "Feedback", "Glide", "Drive", "Loop Top", "Loop Bass",
+            "Top Cut", "Low Cut", "Decay", "Damping", "Mix"))
+        self.assertEqual(set(AirSpace.MACRO_MODES.values()), {"UNIPOLAR"})
+
+    def test_time_lands_on_whole_frames(self):
+        for rate in (48000, 44100, 22050):
+            effect = fresh(rate)
+            for ms in (20.0, 37.3, 111.0, 222.0, 499.9):
+                with self.subTest(rate=rate, ms=ms):
+                    set_value(effect, TIME_I, ms)
+                    self.assertEqual(effect._handed["delay_frames"],
+                                     law_frames(effect.macro(TIME_I), rate))
+            effect.deinit()
+
+    def test_what_the_tape_and_the_filter_are_handed(self):
+        for rate in (48000, 22050):
+            effect = fresh(rate)
+            nyquist = rate * 0.5 * 0.98
+            for midi in (0, 40, 127):
+                with self.subTest(rate=rate, midi=midi):
+                    effect.set_macro(FEEDBACK_I, midi)
+                    effect.set_macro(DRIVE_I, midi)
+                    effect.set_macro(LOOP_TOP_I, midi)
+                    effect.set_macro(LOOP_BASS_I, midi)
+                    effect.set_macro(TOP_CUT_I, midi)
+                    handed = effect._handed
+                    self.assertAlmostEqual(
+                        handed["feedback"], law_value(FEEDBACK_I, midi))
+                    self.assertAlmostEqual(
+                        handed["loop_drive"], law_value(DRIVE_I, midi))
+                    self.assertAlmostEqual(
+                        handed["damping_hz"],
+                        min(law_value(LOOP_TOP_I, midi), nyquist))
+                    self.assertAlmostEqual(
+                        handed["cut_hz"], law_value(LOOP_BASS_I, midi))
+                    self.assertAlmostEqual(
+                        handed["top_cut_hz"],
+                        min(law_value(TOP_CUT_I, midi), nyquist))
+            effect.deinit()
+
+    def test_the_glide_law(self):
+        effect = fresh()
+        self.assertAlmostEqual(effect._handed["delay_slew"], 0.12)
+        for midi in (0, 64, 127):
+            with self.subTest(midi=midi):
+                effect.set_macro(GLIDE_I, midi)
+                self.assertAlmostEqual(effect._handed["delay_slew"],
+                                       law_slew(law_value(GLIDE_I, midi)))
+        effect.deinit()
+
+    def test_the_chamber_follows(self):
+        effect = fresh()
+        chamber = effect._chamber
+        pairs = ((LOW_CUT_I, 7), (DECAY_I, 1), (DAMPING_I, 5))
+        for ours, theirs in pairs:
+            self.assertAlmostEqual(chamber.macro(theirs),
+                                   CARD_DEFAULTS[ours], places=9)
+            for midi in (0, 127):
+                with self.subTest(macro=ours, midi=midi):
+                    effect.set_macro(ours, midi)
+                    self.assertAlmostEqual(
+                        chamber.macro(theirs), law_value(ours, midi),
+                        delta=law_value(ours, midi) * 1e-9)
+        # The rest of the chamber stays where the card fixes it.
+        self.assertEqual(chamber._character(), 2)
+        self.assertAlmostEqual(chamber.macro(2), 0.5 + 64 / 127.0)
+        self.assertEqual(chamber.macro(3), 0.0)
+        self.assertEqual(chamber.macro(12), 2.0)
+        effect.deinit()
+
+    def test_the_mix_law(self):
+        for channels in (2, 1):
+            effect = fresh(channels=channels)
+            voices = effect._mixer.voice
+            for mix in (0.35, 0.5, 1.0, 1.5, 2.0):
+                with self.subTest(channels=channels, mix=mix):
+                    set_value(effect, MIX_I, mix)
+                    dry, wet = law_levels(mix)
+                    if channels == 1 and dry == 1.0:
+                        dry = 1.0 - 2.0 ** -15
+                    self.assertAlmostEqual(voices[0].level, dry)
+                    self.assertAlmostEqual(voices[1].level, wet)
+            effect.deinit()
+
+    def test_mix_two_is_the_chamber_alone(self):
+        rate = 48000
+        frames = law_frames(111.0, rate)
+        data = burst(frames - 48, frames + BLOCK, 2, 8000.0, 3)
+        effect = build(AirSpace, data, rate, 2, mix=2.0)
+        out = render(effect, frames)
+        effect.deinit()
+        self.assertFalse(any(out))
+
+    def test_mix_zero_is_a_wire(self):
+        rate, channels = 48000, 2
+        frames = 8192
+        ramp = array("h", bytes(2 * frames * channels))
+        for i in range(frames * channels):
+            ramp[i] = ((i * 37) % 65536) - 32768
+        effect = build(AirSpace, ramp, rate, channels, mix=0.0)
+        self.assertEqual(render(effect, frames), ramp)
+        effect.deinit()
+
+    def test_the_tail_is_gone_when_mix_comes_back(self):
+        rate, channels = 48000, 2
+        data = burst(4800, rate * 3, channels, 8000.0, 4)
+        effect = build(AirSpace, data, rate, channels, mix=1.0,
+                       feedback=0.85, decay=10.0)
+        pulls = int(0.5 * rate / BLOCK)
+        actions = {pulls: lambda e: e.set_macro(MIX_I, 0),
+                   pulls + 8: lambda e: e.set_macro(MIX_I, 127)}
+        out = render(effect, pulls * BLOCK * 2, actions)
+        effect.deinit()
+        before = out[(pulls - 8) * BLOCK * channels:pulls * BLOCK * channels]
+        after = out[(pulls + 8) * BLOCK * channels:]
+        self.assertTrue(any(before))
+        self.assertFalse(any(after))
+
+    def test_latency_is_zero(self):
+        effect = fresh()
+        self.assertEqual(effect.latency_samples, 0)
+        self.assertEqual(AirSpace.LATENCY_SAMPLES, 0)
+        effect.deinit()
+
+    def test_the_patches(self):
+        self.assertEqual(tuple(AirSpace.PATCHES[k][0]
+                               for k in sorted(AirSpace.PATCHES)),
+                         PATCH_NAMES)
+
+    def test_patch_0_is_the_defaults_on_the_grid(self):
+        steps = AirSpace.PATCHES[0][1]
+        for index, value in enumerate(CARD_DEFAULTS):
+            with self.subTest(index=index):
+                self.assertEqual(steps[index],
+                                 int(round(law_midi(index, value))))
+
+    def test_a_fresh_instance_reads_patch_0_and_plays_the_defaults(self):
+        effect = fresh()
+        self.assertEqual([effect.get_macro(i) for i in range(11)],
+                         [float(m) for m in AirSpace.PATCHES[0][1]])
+        for index, value in enumerate(CARD_DEFAULTS):
+            self.assertEqual(effect.macro(index), value)
+        effect.deinit()
+
+    def test_fixed_size_no_sync_and_mono_in_mono_out(self):
+        self.assertNotIn("Size", AirSpace.MACRO_LABELS)
+        self.assertEqual(AirSpace.CAPABILITIES, ())
+        effect = fresh(channels=1)
+        self.assertEqual(effect.channel_count, 1)
+        self.assertEqual(effect.output.channel_count, 1)
+        effect.deinit()
+
+    def test_at_least_20_ms_before_the_chamber(self):
+        # The shortest Time, the most Feedback, the chamber alone: nothing
+        # reaches the output before 20 ms.
+        rate = 48000
+        frames = law_frames(20.0, rate)
+        data = burst(frames, frames + BLOCK, 2, 8000.0, 5)
+        effect = build(AirSpace, data, rate, 2, mix=2.0, time_ms=20.0,
+                       feedback=0.85)
+        self.assertEqual(effect.macro(TIME_I), 20.0)
+        out = render(effect, frames)
+        effect.deinit()
+        self.assertFalse(any(out))
+
+
+def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0):
+    """The longest run of frames at the rail, on a 50 Hz sine at `dbfs`
+    (the kit's ceiling material that rails first)."""
+    frames = int(seconds * rate)
+    peak = 32767.0 * 10.0 ** (dbfs / 20.0)
+    data = tone(50.0, frames, rate, channels, peak)
+    effect = build(cls, data, rate, channels, patch)
+    out = render(effect, frames)
+    effect.deinit()
+    if not any(out[-rate * channels:]):
+        raise Red("the output fell silent")
+    longest = run = 0
+    for i in range(frames):
+        if any(abs(out[i * channels + c]) >= 32767 for c in range(channels)):
+            run += 1
+            longest = max(longest, run)
+        else:
+            run = 0
+    return longest
+
+
+class TheInputCeiling(unittest.TestCase):
+
+    def test_minus_6_dbfs_reaches_no_rail(self):
+        self.assertEqual(AirSpace.INPUT_CEILING_DBFS, -6.0)
+        for rate, channels in ((48000, 2), (22050, 1)):
+            for patch in sorted(AirSpace.PATCHES):
+                with self.subTest(rate=rate, channels=channels, patch=patch):
+                    self.assertLessEqual(
+                        rail_run(AirSpace, rate, channels, -6.0, patch), 8)
+
+    def test_full_scale_does(self):
+        self.assertGreater(rail_run(AirSpace, 48000, 2, 0.0), 8)
+
+
+# --------------------------------------------------------------------------
+# reset() and patch changes
+
+
+class StaleTape(AirSpace):
+    """A reset that does not empty the tape, so its read head glides from
+    where it was."""
+
+    def _clear_tape(self):
+        self._reach = self._frames
+
+
+def after_reset(cls, rate, channels, data, from_ms=500.0):
+    """Render `data` after a stretch of noise at `from_ms` and a reset."""
+    frames = (rate // BLOCK) * BLOCK
+    noise = lcg_noise(frames, channels, 4000.0, 9)
+    feed = Feed(noise + data, rate, channels)
+    effect = cls(feed, time_ms=from_ms)
+    render(effect, frames)
+    effect.reset()
+    out = render(effect, len(data) // channels)
+    effect.deinit()
+    return out
+
+
+class TheReset(unittest.TestCase):
+
+    def burst(self, rate, channels):
+        return burst(law_frames(20.0, rate), rate, channels, 4000.0, 6)
+
+    def test_reset_renders_as_a_fresh_instance(self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            with self.subTest(rate=rate, channels=channels):
+                data = self.burst(rate, channels)
+                effect = build(AirSpace, data, rate, channels)
+                want = render(effect, rate)
+                effect.deinit()
+                self.assertTrue(any(want))
+                self.assertEqual(after_reset(AirSpace, rate, channels, data),
+                                 want)
+
+    def test_reset_restores_patch_0_and_the_chamber(self):
+        effect = fresh(time_ms=500.0, patch=4)
+        lines = fresh()._chamber._lines
+        effect.reset()
+        self.assertEqual(effect.patch_index, 0)
+        self.assertEqual([effect.get_macro(i) for i in range(11)],
+                         [float(m) for m in AirSpace.PATCHES[0][1]])
+        self.assertEqual(effect.macro(TIME_I), 111.0)
+        self.assertEqual(effect._chamber._lines, lines)
+        self.assertAlmostEqual(effect._chamber.macro(1), 1.8, places=12)
+        effect.deinit()
+
+    def test_red_on_a_reset_that_keeps_the_tape(self):
+        rate, channels = 48000, 2
+        data = self.burst(rate, channels)
+        effect = build(AirSpace, data, rate, channels)
+        want = render(effect, rate)
+        effect.deinit()
+        self.assertNotEqual(after_reset(StaleTape, rate, channels, data),
+                            want)
+
+    def test_a_patch_change_glides(self):
+        # Long Send (300 ms) to Plain Chamber (20 ms): the repeats bend
+        # up while the head travels.
+        rate, channels = 48000, 2
+        slew = law_slew(4000.0)
+        at = int(round(rate / BLOCK))
+        begin = at * BLOCK + int(0.05 * rate)
+        end = at * BLOCK + int(0.5 * rate)
+        data = tone(1000.0, end + BLOCK, rate, channels, 8000.0)
+        powers = []
+        for move in (True, False):
+            effect = build(AirSpace, data, rate, channels, patch=2)
+            effect.set_macro(MIX_I, 127)
+            actions = {at: lambda e: e.program_change(6)} if move else None
+            x = mono(render(effect, end, actions), channels)
+            effect.deinit()
+            powers.append(goertzel_power(x[begin:end], 1000.0 * (1 + slew),
+                                         rate))
+        self.assertGreaterEqual(db_ratio(powers[0], powers[1]), 40.0)
+
+
+# --------------------------------------------------------------------------
+# The docstring's claims, sentence by sentence (KIT.md, claims)
+
+
+CLAIMS = (
+    ("You send your signal to a tape echo whose repeats feed an echo "
+     "chamber, and your dry signal comes back exactly as it went in: the "
+     "filters, the drive and the tape act only on the send.",
+     ("T1DryIsUntouched.test_every_patch_stereo_48k",
+      "T1DryIsUntouched.test_the_times_and_the_hardest_settings",
+      "T1DryIsUntouched.test_red_on_the_top_cut_ahead_of_the_splitter")),
+    ("Time (20 to 500 ms) is the gap between repeats and Feedback (0 to "
+     "0.85) how much of each repeat goes round again.",
+     ("TheSurface.test_the_spans",
+      "TheSurface.test_time_lands_on_whole_frames",
+      "TheSurface.test_what_the_tape_and_the_filter_are_handed")),
+    ("Loop Top (1 to 16 kHz) and Loop Bass (20 Hz to 1 kHz) filter the "
+     "loop, so each repeat is darker than the last, and Drive (0 to 1) "
+     "saturates it.",
+     ("TheSurface.test_the_spans",
+      "TheSurface.test_what_the_tape_and_the_filter_are_handed",
+      "T2EachRepeatDarker.test_loop_top_darkens_each_repeat")),
+    ("Top Cut (1 to 16 kHz) darkens everything sent to the chamber, once.",
+     ("TheSurface.test_the_spans",
+      "T2EachRepeatDarker.test_top_cut_darkens_once")),
+    ("Low Cut (20 to 500 Hz), Decay (0.3 to 10 s) and Damping (500 Hz to "
+     "16 kHz) set the chamber.",
+     ("TheSurface.test_the_spans", "TheSurface.test_the_chamber_follows")),
+    ("Mix (0 to 2) is `audiodelays.Echo`'s: the dry at unity up to 1, the "
+     "chamber alone at 2.",
+     ("TheSurface.test_the_mix_law",
+      "TheSurface.test_mix_two_is_the_chamber_alone")),
+    ("More Feedback makes the chamber's tail longer: at Time 500 ms, "
+     "Feedback 0.85 at least triples it.",
+     "T3FeedbackLengthensTheTail.test_the_bars"),
+    ("At the defaults you hear the repeats as a longer chamber, not as a "
+     "rhythm of echoes.",
+     "T4HeardAsAChamber.test_the_cells"),
+    ("Move Time while it plays and the repeats bend in pitch, the way tape "
+     "does: down while it lengthens, up while it shortens.",
+     "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide"),
+    ("Glide (1 to 10 s) is how long a move across the whole Time range "
+     "takes, so it sets how far they bend: 12 % at the default of 4 s.",
+     ("TheSurface.test_the_glide_law",
+      "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide")),
+    ("Keep your input at or under -6 dBFS: the dry is at unity and the "
+     "chamber adds to it, so a hotter input can reach the rail.",
+     ("TheInputCeiling.test_minus_6_dbfs_reaches_no_rail",
+      "TheInputCeiling.test_full_scale_does")),
+    ("Latency is zero.", "TheSurface.test_latency_is_zero"),
+    ("`reset()` empties the tape and the chamber and restores patch 0, "
+     "whose Time of 111 ms lands at once instead of gliding.",
+     ("TheReset.test_reset_renders_as_a_fresh_instance",
+      "TheReset.test_reset_restores_patch_0_and_the_chamber",
+      "TheReset.test_red_on_a_reset_that_keeps_the_tape")),
+    ("The patches: Chamber Send (the defaults), Short Send, Long Send, "
+     "Dark Loop, Bright Chamber, Driven Tape, Plain Chamber.",
+     ("TheSurface.test_the_patches",
+      "TheSurface.test_patch_0_is_the_defaults_on_the_grid",
+      "TheSurface.test_a_fresh_instance_reads_patch_0_and_plays_the_"
+      "defaults")),
+    ("Time is the exception: it glides.",
+     "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide"),
+    ("A patch that changes Time glides there too, and the repeats bend "
+     "while it travels.",
+     "TheReset.test_a_patch_change_glides"),
+    ("At the defaults the repeats add only a little length to the tail; "
+     "the stretch comes with Feedback above about 0.6 or a long Time.",
+     ("T3FeedbackLengthensTheTail.test_the_default_adds_only_a_little",
+      "T3FeedbackLengthensTheTail.test_the_bars")),
+    ("There is always at least 20 ms between the dry and the chamber.",
+     ("TheSurface.test_at_least_20_ms_before_the_chamber",
+      "T1DryIsUntouched.test_the_times_and_the_hardest_settings")),
+    ("The chamber's size is fixed, there is no tempo sync, and a mono "
+     "source gets a mono rack.",
+     "TheSurface.test_fixed_size_no_sync_and_mono_in_mono_out"),
+    ("At Mix 0 the output is your input, byte for byte, and the tail that "
+     "was ringing when Mix went to 0 is gone when it comes back.",
+     ("TheSurface.test_mix_zero_is_a_wire",
+      "TheSurface.test_the_tail_is_gone_when_mix_comes_back")),
+)
+
+
+if __name__ == "__main__":
+    unittest.main()

From 3f890cc94c697f402cb46ad64610cc0d3e885ae0 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:40:38 -0500
Subject: [PATCH 14/76] AUDIODSP_PIN: move to audiodsp v0.6.6rc1 (30cbbf6)

---
 AUDIODSP_PIN | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/AUDIODSP_PIN b/AUDIODSP_PIN
index b9bf764..d337e91 100644
--- a/AUDIODSP_PIN
+++ b/AUDIODSP_PIN
@@ -321,5 +321,29 @@
 # plants that #211 made inert; and the lifecycle matrix's E8-dry event,
 # retired because a native source that runs dry has ended.
 #
+# 2026-10-12: eb2d20d -> v0.6.6rc1 (30cbbf6), a pre-release of the next
+# patch, for the effects program's Phase 6; TestPyPI only, so CI's
+# `git+...@v0.6.6rc1` install is the one that reaches it. The pyproject
+# floors stay at the last final release: the pin is not the floor. What
+# moved beneath the components, by `git log eb2d20d..v0.6.6rc1 -- src`:
+# audiodelays.Echo and MultiTapDelay start a line shortened under the write
+# head at its top, so a Time brought back after a shorter one plays nothing
+# from before, and the CPython Echo clears past a shorter line as the native
+# one does (audiodsp#241); Echo lets go of a looped source that comes back
+# empty instead of hanging the pull (#242); PitchShift and
+# GranularPitchShift start again from a new node's state on a reset (#240)
+# and return from a pull when the source has nothing to give (#243), and
+# PitchShift gains upstream's freeze (#222); Convolver's load() keeps the
+# audio in flight and crossfades the block being played, as synthesize()
+# already did (#237); a Mixer's host reset keeps every voice where it was
+# (#229); a set() on FeedbackDelay, Tank, Dynamics, Waveshaper, Ladder and
+# Bank is staged off the lock and lands whole (#233); an audiopump swap
+# that outlasts the ring fades out and back in (#234); Tank's filters and
+# modulation brought back from 0 start from what is playing (#227); a mono
+# SplitterTap's buffer is the tap's own on CPython too (#228); FeedbackDelay
+# takes its wow and pitch coast rate from what played, and the CPython Echo
+# holds its line still at mix 0 (#226); audiovorbis (#238, #239); and an
+# fmod-free angle reduction for the RP2040 (#225).
+#
 # <ref> <commit>   -- ref is what CI installs (git+https://...@<ref>)
-eb2d20daa7f3be2965f8f641b3fdf2d9a55aca9c eb2d20daa7f3be2965f8f641b3fdf2d9a55aca9c
+v0.6.6rc1 30cbbf619751ab6ff7c40d99336907af0a081fa6

From 82e2724955b6c104096b9cecb5c036e6cf4a867f Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:40:38 -0500
Subject: [PATCH 15/76] MultiTapDelay: restate the Mixer-tail plant
 (audiodsp#229 made it inert) and the CPython dry check (audiodsp#228)

---
 tests/test_cpython_effects_multitapdelay.py | 53 +++++++++++++--------
 1 file changed, 33 insertions(+), 20 deletions(-)

diff --git a/tests/test_cpython_effects_multitapdelay.py b/tests/test_cpython_effects_multitapdelay.py
index b0e739d..58010b6 100644
--- a/tests/test_cpython_effects_multitapdelay.py
+++ b/tests/test_cpython_effects_multitapdelay.py
@@ -1877,17 +1877,26 @@ def test_a_host_reset_keeps_the_first_block(self):
                                                 channels)
                 self.assertTrue(result["passed"], (rate, channels, result))
 
-    def test_mixer_tail_plant_is_red(self):
+    def test_mixer_tail_plant_is_inert(self):
         # Since re-audit fix round 1 every wiring is quiet, so no voice
         # holds the source's first block at construction and a host reset
         # that reaches the Mixer drops nothing there (c80ca59 put the 3 000
-        # click at 2 744). Mid-stream it still empties both lines: the
-        # click's heads are gone where the tail leaves them sounding.
+        # click at 2 744).
+        #
+        # Restated at audiodsp v0.6.6rc1 (30cbbf6). Up to eb2d20d a host
+        # reset that reached the Mixer mid-stream re-primed its voices from
+        # the Splitter's taps and dropped the blocks they held, so the
+        # click's heads were gone and this test held the plant red there. That rewind was
+        # the node's defect, fixed in audiodsp#229: a Mixer's host reset
+        # keeps every voice where it was, so the plant renders what the
+        # class does, heads and all, and is green. The class keeps its
+        # output on the tail; that is no longer needed for this, but it is
+        # not wrong.
         self.assertTrue(host_reset_route(MixerTail)["passed"])
         for channels in (2, 1):
             result = host_reset_lines_route(MixerTail, channels=channels)
-            self.assertFalse(result["passed"], result)
-            self.assertEqual(result["hits"], [[7000]] * channels)
+            self.assertTrue(result["passed"], result)
+            self.assertEqual(result["hits"], [result["law"]] * channels)
         result = reach_flag(MixerTail, "_plant_mixer_tail")
         self.assertEqual(result["checked"], 9 * 17 + 7)
 
@@ -2692,7 +2701,7 @@ def test_a_stall_window_cell_reaches_zero_at_the_feedback_set(self):
         self.assertNotEqual(stepped._feedback, stepped.macro(FEEDBACK_I))
         self.assertLess(abs(stepped._feedback - 0.5), 3e-5)
 
-    def _judge_routes(self, results, native):
+    def _judge_routes(self, results):
         """Items 1 and 2 on one interpreter's run."""
         for part in ("FIRSTDRY", "FIRSTHEADS"):
             self.assertEqual(red_cells(results, part, "clean"), [], part)
@@ -2706,19 +2715,23 @@ def _judge_routes(self, results, native):
             red_cells(results, "FIRSTHEADS", "oldwiring"),
             sorted((name, rate, channels) for name in RESYNC_ROUTES
                    for rate in ROUTE_RATES for channels in (2, 1)))
-        # And on a native interpreter, in mono, the dry's first block: all
-        # 256 samples zero. The CPython shim copies the primed block, so
-        # there the dry is kept (which is why this runs natively).
+        # And in mono, the dry's first block: all 256 samples zero.
+        #
+        # Restated at audiodsp v0.6.6rc1 (30cbbf6). Up to eb2d20d the
+        # CPython twin's mono SplitterTap handed out a fresh copy of the
+        # primed block, so on CPython the plant kept the dry and this test
+        # asserted no cell, holding the dry check to the native
+        # interpreters. That copy was the twin's defect, fixed in
+        # audiodsp#228: a mono tap's buffer is the tap's own on CPython as
+        # it is natively, so the plant loses the dry's first block on every
+        # interpreter, and every interpreter is held to it.
         dry = red_cells(results, "FIRSTDRY", "oldwiring")
-        if native:
-            self.assertEqual(dry, sorted(
-                (name, rate, 1) for name in RESYNC_ROUTES
-                for rate in ROUTE_RATES))
-            for name, rate, channels in dry:
-                self.assertEqual(results[("FIRSTDRY", "oldwiring", name,
-                                          rate, channels)], 256)
-        else:
-            self.assertEqual(dry, [])
+        self.assertEqual(dry, sorted(
+            (name, rate, 1) for name in RESYNC_ROUTES
+            for rate in ROUTE_RATES))
+        for name, rate, channels in dry:
+            self.assertEqual(results[("FIRSTDRY", "oldwiring", name,
+                                      rate, channels)], 256)
 
     def _judge_blocks(self, results):
         """Items 3 and 4 on one interpreter's run."""
@@ -2749,7 +2762,7 @@ def test_routes_before_the_first_pull_and_source_buffers_cpython(self):
         results = run_routes(sys.executable, (
             "clean,oldwiring=firstdry,firstheads",
             "clean,adapterreset,sourcebypass=blocks"))
-        self._judge_routes(results, native=False)
+        self._judge_routes(results)
         self._judge_blocks(results)
 
     def test_routes_before_the_first_pull_and_source_buffers_native(self):
@@ -2764,7 +2777,7 @@ def test_routes_before_the_first_pull_and_source_buffers_native(self):
             results = run_routes(binary, (
                 "clean,oldwiring=firstdry,firstheads",
                 "clean,adapterreset,sourcebypass=blocks"))
-            self._judge_routes(results, native=True)
+            self._judge_routes(results)
             self._judge_blocks(results)
 
     def test_the_route_plants_are_not_on_the_surface(self):

From 396de636470a27d17291d378d2c191dac1ace156 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:42:37 -0500
Subject: [PATCH 16/76] StereoWidener: reset() re-plays the Haas voices without
 get_buffer; a refused program_change keeps the exact Delay

---
 lib/audioeffects/rebuilt/stereowidener.py   | 37 +++++++++++++++------
 tests/test_cpython_effects_stereowidener.py | 36 ++++++++++++++++++++
 2 files changed, 62 insertions(+), 11 deletions(-)

diff --git a/lib/audioeffects/rebuilt/stereowidener.py b/lib/audioeffects/rebuilt/stereowidener.py
index 788324f..fa49419 100644
--- a/lib/audioeffects/rebuilt/stereowidener.py
+++ b/lib/audioeffects/rebuilt/stereowidener.py
@@ -345,8 +345,6 @@ def _apply_macro(self, index, position):
     def program_change(self, index, channel=0, note_id=-1,
                        sample_position=0):
         """Apply patch `index` whole, then refresh the graph once."""
-        if type(self).PATCHES.get(index) is not None:
-            self._delay_exact = None
         ready = self._ready
         self._ready = False
         try:
@@ -354,8 +352,29 @@ def program_change(self, index, channel=0, note_id=-1,
                 self, index, channel, note_id, sample_position)
         finally:
             self._ready = ready
-        if ready and type(self).PATCHES.get(index) is not None:
-            self._refresh()
+        if type(self).PATCHES.get(index) is not None:
+            # Only a call the base accepted drops the constructor's Delay.
+            self._delay_exact = None
+            if ready:
+                self._refresh()
+
+    def reset(self):
+        """Clear the line and return to patch 0. Where the output was
+        routed around the voices (and `audiocore.get_buffer` is absent),
+        they come back re-played, as `program_change(0)` brings them."""
+        self._check_live()
+        replay = self._wired and self._stranded
+        _component.Component.reset(self)
+        if replay and self._haas_live():
+            self._replay()
+
+    def _replay(self):
+        """Without `audiocore.get_buffer`, drop the block the voices still
+        hold and prime the source's next one."""
+        if getattr(audiocore, "get_buffer", None) is None:
+            voices = self._mixer.voice
+            voices[0].play(self._split.tap(0))
+            voices[1].play(self._line)
 
     def _refresh(self):
         if self._ms is None:
@@ -383,13 +402,9 @@ def _route(self):
             self._wire()
         else:
             self._levels()
-            if self._rejoin(keep=(self._ms,)) and getattr(
-                    audiocore, "get_buffer", None) is None:
-                # A voice may still hold the block it primed at wiring:
-                # play() again drops it and primes the source's next block.
-                voices = self._mixer.voice
-                voices[0].play(self._split.tap(0))
-                voices[1].play(self._line)
+            if self._rejoin(keep=(self._ms,)):
+                # A voice may still hold the block it primed at wiring.
+                self._replay()
         self._output = self._tail
 
     def _haas_live(self):
diff --git a/tests/test_cpython_effects_stereowidener.py b/tests/test_cpython_effects_stereowidener.py
index 66ad385..5663422 100644
--- a/tests/test_cpython_effects_stereowidener.py
+++ b/tests/test_cpython_effects_stereowidener.py
@@ -717,6 +717,42 @@ def test_without_get_buffer(self):
                          0)
         self.assertEqual(left_skip(values, out, settle, 2 * BLOCK), 0)
 
+    def test_without_get_buffer_reset(self):
+        # reset() brings Haas back the way program_change(0) does, after
+        # each way of leaving it before its first block.
+        frames = 4096
+        settle = 32
+        leaves = (("a Mid/Side patch", lambda e: e.program_change(4)),
+                  ("Width 0", lambda e: e.set_macro(0, 0)),
+                  ("Character", lambda e: e.set_macro(2, 127)))
+        for name, leave in leaves:
+            values, out = without_get_buffer(
+                StereoWidener, {0: leave, 6: lambda e: e.reset()})
+            self.assertEqual(
+                left_skip(values, out, 6 * BLOCK + settle, frames), BLOCK,
+                name)
+
+    def test_a_refused_program_change_keeps_every_macro(self):
+        values = array("h", bytes(4 * 512))
+        refused = (dict(index=1, sample_position=-5), dict(index=0.0),
+                   dict(index=1.0), dict(index=True), dict(index=-1))
+        for call in refused:
+            e = StereoWidener(source(values, 48000), delay_ms=20.0)
+            try:
+                before = [e.macro(i) for i in range(3)]
+                frames = e._frames
+                with self.assertRaises(ValueError):
+                    e.program_change(**call)
+                self.assertEqual([e.macro(i) for i in range(3)], before,
+                                 call)
+                self.assertEqual(e.macro(1), 20.0, call)
+                self.assertEqual(e._frames, frames, call)
+                e.set_macro(0, 63)
+                self.assertEqual(e.macro(1), 20.0, call)
+                self.assertEqual(e._frames, frames, call)
+            finally:
+                e.deinit()
+
     def test_the_tempo_is_never_read(self):
         reads = []
 

From 9fbe2e80a593bd9b4eecfed3487f5ae99236ef37 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Mon, 12 Oct 2026 23:53:19 -0500
Subject: [PATCH 17/76] Rack lifecycle runs on a chain without Vibrato and
 Fuzz, so the E1 P4 row no longer hides Rack's own reset faults

---
 tests/support/kit_common.py  |  6 +++---
 tests/support/kit_options.py | 16 ++++++++++++++++
 tests/support/lifecycle.py   |  7 ++-----
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 7eca674..57f3708 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -42,9 +42,9 @@
         "T6's faults need a host transport and a tempo change, which the"
         " plant render does not give; the trait test holds them red",
     ("Rack", "ceiling", "sine/48000/2/"):
-        "the probe chain ends in ConvolutionReverb, which rails this 0 dBFS"
-        " sine at its own defaults (its own ceiling cell sine/48000/2/d); a"
-        " rack is exactly its pedals",
+        "ConvolutionReverb's own ceiling at its defaults: it rails this 0"
+        " dBFS sine alone (its own ceiling cell sine/48000/2/d), a finding"
+        " for that class and not a rack defect",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/kit_options.py b/tests/support/kit_options.py
index 120abbc..38f8a87 100644
--- a/tests/support/kit_options.py
+++ b/tests/support/kit_options.py
@@ -15,7 +15,23 @@
         ("ConvolutionReverb", {}))},
 }
 
+#: What the lifecycle matrix builds a class with, where the kit's options
+#: would hide the class's own faults behind a child's: Rack's chain here has
+#: no Vibrato or Fuzz (each is red on E1 P4 alone), keeping a nested rack
+#: with a delay line mid-chain and ConvolutionReverb's latency.
+LIFECYCLE_OPTIONS = {
+    "Rack": {"chain": (
+        ("Rack", {"chain": (("DigitalDelay", {"mix": 0.3, "feedback": 0.4}),)}),
+        ("ConvolutionReverb", {}))},
+}
+
 
 def options_for(name):
     """A fresh dict of the options for class NAME `name`."""
     return dict(KIT_OPTIONS.get(name, {}))
+
+
+def lifecycle_options_for(name):
+    """A fresh dict of the lifecycle matrix's options for class NAME `name`
+    (the kit's own where it has none of its own)."""
+    return dict(LIFECYCLE_OPTIONS.get(name) or options_for(name))
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 3375c81..7a79a4a 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,10 +75,6 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
-    ("Rack", "E1-", "P4"):
-        "a rack is exactly its pedals, and two of the probe chain's are E1 P4"
-        " red alone at their defaults, Vibrato ('differs at +4917, bound"
-        " +2870' at 48 kHz stereo) and Fuzz ('+26883, bound +24836')",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
@@ -1348,7 +1344,8 @@ def _cli(argv):
         # The kit's options table: a class whose defaults are trivial (the
         # generic Rack's empty chain) runs on something real.
         import kit_options
-        run_class(cls, options=kit_options.options_for(cls.NAME), only=only,
+        run_class(cls, options=kit_options.lifecycle_options_for(cls.NAME),
+                  only=only,
                   quick=quick, name=name if name in PLANTS else None)
     print("DONE")
 

From 884d17646b8b9b9ac78c3e87cd857c8bcea8c1fb Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:00:16 -0500
Subject: [PATCH 18/76] StereoWidener: wire the voices the same way without
 get_buffer

Where audiocore.get_buffer is compiled out, the class could not hand out
the block a voice primes, so after wiring (or a re-play) a voice could
hold a block read from the line that a reset then emptied, or read at a
Delay the reset then left: the copy of that block never played, and the
right channel was silent for one block. The class now pulls the mixer
through a one-voice mixer of its own playing the Haas tail, so wiring
primes from silence and hands it out on every build, and no voice ever
holds a block between pulls. The re-play special cases are gone, and so
is the disclosed one-block skip when leaving Haas before its first block.

Renders with get_buffer are unchanged byte for byte. The new test
compares both channels with and without get_buffer from the first frame,
twelve paths at 48, 16 and 8 kHz.
---
 lib/audioeffects/rebuilt/stereowidener.py   |  84 +++++++-------
 tests/test_cpython_effects_stereowidener.py | 122 ++++++++++----------
 2 files changed, 102 insertions(+), 104 deletions(-)

diff --git a/lib/audioeffects/rebuilt/stereowidener.py b/lib/audioeffects/rebuilt/stereowidener.py
index fa49419..f4eada5 100644
--- a/lib/audioeffects/rebuilt/stereowidener.py
+++ b/lib/audioeffects/rebuilt/stereowidener.py
@@ -135,9 +135,6 @@ class StereoWidener(_component.Component):
     `reset()` empties the line and returns to patch 0.
     The class never reads the host's tempo.
 
-    Where `audiocore.get_buffer` is compiled out, leaving Haas before its
-    first block has played skips that one block of the source.
-
     **Limits shared by the family.**
     A control that jumps, Width or Character, makes the output step: move it
     in small steps from the host if you need it smooth.
@@ -243,8 +240,8 @@ def _build_graph(self):
             delay_frames=1, feedback=0.0, mix=2.0, damping_hz=0.0,
             cut_hz=0.0, delay_slew=SLEW), reset=self._clear)
         self._line.play(self._split.tap(1))
-        # Not reset by the walk: a voice resets its source, and neither
-        # voice holds a block between two pulls (`_wire`).
+        # Not reset by the walk: neither voice holds a block between two
+        # pulls (`_wire`), so there is nothing of its own to clear.
         self._mixer = self._own(audiomixer.Mixer(
             voice_count=2, buffer_size=BLOCK * 2 * 4, channel_count=2,
             bits_per_sample=16, samples_signed=True, sample_rate=rate),
@@ -259,6 +256,10 @@ def _build_graph(self):
             reset=False)
         self._silence = audiocore.RawSample(
             array("h", bytes(2 * 2 * 2)), sample_rate=rate, channel_count=2)
+        #: Where `audiocore.get_buffer` is compiled out, the one-voice
+        #: mixer `_pull` primes from `_tail`; built the first time it is
+        #: needed.
+        self._puller = None
         self._output = self._ms
 
     def _wire(self):
@@ -268,30 +269,45 @@ def _wire(self):
         Splitter on `_hush` that block is zeros, and one pull of the mixer
         hands it out, so wiring takes nothing from the borrowed source and
         leaves no voice holding a block: whatever the MidSide has handed
-        out, the output has played, at every Width and Character.
-
-        Without `audiocore.get_buffer` (compiled out of CircuitPython's
-        default board builds) the voices prime the source's next block,
-        which the next pull plays. If the output leaves Haas before that
-        pull, the bypass starts a block later and the voices hold the block
-        it skipped; `_route` re-plays them on the way back, so that block
-        is dropped rather than played stale. The skip is disclosed. A
-        re-played voice there starts at level 0 until its signal crosses
-        zero, upstream's level gate, as every class's first block does on
-        such a build."""
-        pull = getattr(audiocore, "get_buffer", None)
+        out, the output has played, at every Width and Character. So a
+        reset or a return to Haas that empties the line never empties a
+        block a voice is still waiting to play, and a voice never plays a
+        block read at a Delay the line has since left. The level gates are
+        opened first, as `_component.open_level_gates` opens them."""
         voices = self._mixer.voice
         self._levels()
-        _component.open_level_gates(self._mixer, voices, self._silence)
-        if pull is None:
-            self._in.play(self._ms)
+        for voice in voices:
+            voice.play(self._silence, loop=True)
+        self._pull()
         voices[0].play(self._split.tap(0))
         voices[1].play(self._line)
+        self._pull()
+        self._in.play(self._ms)
+        self._clear()
+        self._wired = True
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `_tail` and stops: its `play()` primes one block, which pulls
+        the mixer once. `_tail` forwards no reset, so the play rewinds
+        nothing behind it."""
+        pull = getattr(audiocore, "get_buffer", None)
         if pull is not None:
             pull(self._mixer)
-            self._in.play(self._ms)
-            self._clear()
-        self._wired = True
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # smallest that hold a stereo frame.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, buffer_size=16, channel_count=2,
+                bits_per_sample=16, samples_signed=True,
+                sample_rate=self._sample_rate), reset=False)
+        voice = self._puller.voice[0]
+        voice.play(self._tail)
+        voice.stop()
 
     def _clear(self):
         self._line.clear()
@@ -358,24 +374,6 @@ def program_change(self, index, channel=0, note_id=-1,
             if ready:
                 self._refresh()
 
-    def reset(self):
-        """Clear the line and return to patch 0. Where the output was
-        routed around the voices (and `audiocore.get_buffer` is absent),
-        they come back re-played, as `program_change(0)` brings them."""
-        self._check_live()
-        replay = self._wired and self._stranded
-        _component.Component.reset(self)
-        if replay and self._haas_live():
-            self._replay()
-
-    def _replay(self):
-        """Without `audiocore.get_buffer`, drop the block the voices still
-        hold and prime the source's next one."""
-        if getattr(audiocore, "get_buffer", None) is None:
-            voices = self._mixer.voice
-            voices[0].play(self._split.tap(0))
-            voices[1].play(self._line)
-
     def _refresh(self):
         if self._ms is None:
             return
@@ -402,9 +400,7 @@ def _route(self):
             self._wire()
         else:
             self._levels()
-            if self._rejoin(keep=(self._ms,)):
-                # A voice may still hold the block it primed at wiring.
-                self._replay()
+            self._rejoin(keep=(self._ms,))
         self._output = self._tail
 
     def _haas_live(self):
diff --git a/tests/test_cpython_effects_stereowidener.py b/tests/test_cpython_effects_stereowidener.py
index 5663422..bb0d56c 100644
--- a/tests/test_cpython_effects_stereowidener.py
+++ b/tests/test_cpython_effects_stereowidener.py
@@ -686,51 +686,16 @@ def test_reset_empties_the_line_and_returns_to_patch_0(self):
             self.assertEqual(out[2 * n + 1],
                              values[2 * (1024 + n - tau) + 1], n)
 
-    def test_without_get_buffer(self):
-        # A re-played voice there starts at level 0 until its signal
-        # crosses zero (upstream's level gate, which `open_level_gates`
-        # cannot open without get_buffer), so each read starts a few frames
-        # after the return.
-        frames = 4096
-        settle = 32
-        # Leaving Haas before its first block skips that block, once, and
-        # the block is never played stale.
-        values, out = without_get_buffer(
-            StereoWidener,
-            {0: lambda e: e.program_change(4),
-             4: lambda e: e.program_change(0)})
-        self.assertEqual(left_skip(values, out, 4 * BLOCK + settle, frames),
-                         BLOCK)
-        # Built at a Mid/Side patch, Haas is never wired until it is
-        # reached, and nothing is skipped.
-        values, out = without_get_buffer(
-            lambda src: StereoWidener(src, patch=4),
-            {4: lambda e: e.program_change(0)})
-        self.assertEqual(left_skip(values, out, 4 * BLOCK + settle, frames),
-                         0)
-        # Leaving and coming back once Haas has played skips nothing.
-        values, out = without_get_buffer(
-            StereoWidener,
-            {2: lambda e: e.program_change(4),
-             6: lambda e: e.program_change(0)})
-        self.assertEqual(left_skip(values, out, 6 * BLOCK + settle, frames),
-                         0)
-        self.assertEqual(left_skip(values, out, settle, 2 * BLOCK), 0)
-
-    def test_without_get_buffer_reset(self):
-        # reset() brings Haas back the way program_change(0) does, after
-        # each way of leaving it before its first block.
-        frames = 4096
-        settle = 32
-        leaves = (("a Mid/Side patch", lambda e: e.program_change(4)),
-                  ("Width 0", lambda e: e.set_macro(0, 0)),
-                  ("Character", lambda e: e.set_macro(2, 127)))
-        for name, leave in leaves:
-            values, out = without_get_buffer(
-                StereoWidener, {0: leave, 6: lambda e: e.reset()})
-            self.assertEqual(
-                left_skip(values, out, 6 * BLOCK + settle, frames), BLOCK,
-                name)
+    def test_without_get_buffer_plays_what_it_plays_with_it(self):
+        # Both channels, byte for byte, from the first frame.
+        for rate in (48000, 16000, 8000):
+            for what, build, moves in GET_BUFFER_CASES:
+                with self.subTest(rate=rate, what=what):
+                    _, plain = without_get_buffer(build, moves, rate=rate,
+                                                  hide=False)
+                    _, hidden = without_get_buffer(build, moves, rate=rate)
+                    self.assertEqual(differing_frames(plain, hidden),
+                                     [(0, [], [])] * 2)
 
     def test_a_refused_program_change_keeps_every_macro(self):
         values = array("h", bytes(4 * 512))
@@ -789,15 +754,17 @@ def test_no_latency_in_either_character(self):
                 e.deinit()
 
 
-def without_get_buffer(build, moves, frames=4096, seed=3):
+def without_get_buffer(build, moves, frames=4096, seed=3, rate=48000,
+                       hide=True):
     """Render with `audiocore.get_buffer` hidden from the class, as on a
-    CircuitPython board build, while it builds and while it moves."""
+    CircuitPython board build, while it builds and while it moves; with
+    `hide` false, the same render with it in place."""
     import types
     from audioeffects.rebuilt import stereowidener as module
     real = module.audiocore
     fake = types.ModuleType("audiocore")
     for name in dir(real):
-        if name != "get_buffer":
+        if name != "get_buffer" or not hide:
             setattr(fake, name, getattr(real, name))
 
     def hidden(action):
@@ -812,7 +779,7 @@ def run(e):
     values = lcg_noise(frames, 2, seed)
     module.audiocore = _component.audiocore = fake
     try:
-        e = build(source(values, 48000))
+        e = build(source(values, rate))
     finally:
         module.audiocore = _component.audiocore = real
     try:
@@ -822,14 +789,52 @@ def run(e):
     return values, out
 
 
-def left_skip(values, out, start, frames):
-    """The one shift, in frames, that makes the left from `start` on the
-    source's left, or None."""
-    for shift in (0, BLOCK):
-        if all(out[2 * n] == values[2 * (n + shift)]
-               for n in range(start, frames - shift)):
-            return shift
-    return None
+def differing_frames(a, b):
+    """For each channel, (how many frames differ, the first, the last)."""
+    found = []
+    for channel in (0, 1):
+        frames = [n for n in range(len(a) // 2)
+                  if a[2 * n + channel] != b[2 * n + channel]]
+        found.append((len(frames), frames[:1], frames[-1:]))
+    return found
+
+
+#: Whatever the class is asked, with `get_buffer` hidden or not: (what,
+#: build, moves). Each way out of Haas before its first block, each reset
+#: a voice could meet holding a block it primed, and a constructor Delay
+#: that patch 0 replaces.
+GET_BUFFER_CASES = (
+    ("reset before the first pull", StereoWidener,
+     {0: lambda e: e.reset()}),
+    ("reset twice before the first pull", StereoWidener,
+     {0: lambda e: (e.reset(), e.reset())}),
+    ("built at 1 ms, reset before the first pull",
+     lambda src: StereoWidener(src, delay_ms=1.0),
+     {0: lambda e: e.reset()}),
+    ("leave Haas before its first block, come back", StereoWidener,
+     {0: lambda e: e.program_change(4), 4: lambda e: e.program_change(0)}),
+    ("leave Haas before its first block, reset", StereoWidener,
+     {0: lambda e: e.program_change(4), 6: lambda e: e.reset()}),
+    ("leave Haas before its first block, reset twice", StereoWidener,
+     {0: lambda e: e.program_change(4),
+      6: lambda e: (e.reset(), e.reset())}),
+    ("leave Haas before its first block, program_change(0) and reset",
+     StereoWidener,
+     {0: lambda e: e.program_change(4),
+      6: lambda e: (e.program_change(0), e.reset())}),
+    ("leave Haas after playing, program_change(0) and reset", StereoWidener,
+     {2: lambda e: e.program_change(4),
+      6: lambda e: (e.program_change(0), e.reset())}),
+    ("Width 0 before the first block, reset", StereoWidener,
+     {0: lambda e: e.set_macro(0, 0), 6: lambda e: e.reset()}),
+    ("Character before the first block, reset", StereoWidener,
+     {0: lambda e: e.set_macro(2, 127), 6: lambda e: e.reset()}),
+    ("built at Mid/Side, then Haas",
+     lambda src: StereoWidener(src, patch=4),
+     {4: lambda e: e.program_change(0)}),
+    ("leave Haas after playing, come back", StereoWidener,
+     {2: lambda e: e.program_change(4), 6: lambda e: e.program_change(0)}),
+)
 
 
 class H1TheCopy(TestCase):
@@ -1094,9 +1099,6 @@ def test_fixed_copy_is_red(self):
      "test_a_centred_part_is_unchanged"),
     ("Peaks below half of full scale never clip at any Width.",
      "test_below_half_scale_never_clips"),
-    ("Where `audiocore.get_buffer` is compiled out, leaving Haas before its "
-     "first block has played skips that one block of the source.",
-     "test_without_get_buffer"),
     ("A one-channel source comes out exactly as it went in, whatever the "
      "controls say.",
      "test_a_mono_source_is_a_wire"),

From 8e597874f42a23339ceda9b4c0f152dbe52e0503 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:03:13 -0500
Subject: [PATCH 19/76] Effects kit: refused-call cells in args and a nogb
 check (get_buffer hidden), each red on a plant

---
 tests/support/KIT.md         |  84 +++++++++++---
 tests/support/kit.py         |  14 ++-
 tests/support/kit_args.py    | 153 ++++++++++++++++++++++++
 tests/support/kit_nogb.py    | 219 +++++++++++++++++++++++++++++++++++
 tests/support/kit_planted.py |  88 +++++++++++++-
 tests/test_kit.py            |  80 +++++++++++++
 6 files changed, 614 insertions(+), 24 deletions(-)
 create mode 100644 tests/support/kit_nogb.py

diff --git a/tests/support/KIT.md b/tests/support/KIT.md
index ba40d86..477e05b 100644
--- a/tests/support/KIT.md
+++ b/tests/support/KIT.md
@@ -1,14 +1,16 @@
 # The effects kit
 
-Six mechanical checks that run on one effect class with no model in the
+Seven mechanical checks that run on one effect class with no model in the
 loop: every verdict is arithmetic on rendered bytes, or on the source. They
 sit beside the [lifecycle matrix](LIFECYCLE.md) and catch the kinds of
 defect that kept turning up class after class: a tail that outlasts
 `tail_samples`, a planted fault a knob can reach, a docstring promise no
 test holds, a control that does not read back what it was set to, an input
-level that wraps, and a citation that no longer resolves.
+level that wraps, a citation that no longer resolves, a refused call that
+leaves a trace, and a class that only behaves where `audiocore.get_buffer`
+exists.
 
-To run all six on one class, from the repo root:
+To run all seven on one class, from the repo root:
 
     python tests/support/kit.py DigitalDelay
     python tests/support/kit.py DigitalDelay --only tail,ceiling --quick
@@ -27,9 +29,9 @@ why), `RED(...)` with what was measured, or `decl`. `h:` is a CRC-32 of the
 cell's render, so two interpreters' lines agree only when their bytes do.
 
 The four render checks (tail, plants, args, ceiling) are numpy-free and
-print the same lines on CPython, MicroPython and CircuitPython. The claims
-and paperwork checks read source, unittest and git, and run on CPython
-only; a native run prints `SKIP` for them.
+print the same lines on CPython, MicroPython and CircuitPython. The claims,
+paperwork and nogb checks read source, unittest and git, or patch modules,
+and run on CPython only; a native run prints `SKIP` for them.
 
 A class that does nothing at all must not read as a pass: the tail and
 args checks print `na(silent)` for a render that was zero throughout, and
@@ -117,6 +119,22 @@ hands it:
   was not on; and a NaN build renders exactly what the defaults or the
   option at 0 render.
 
+- `refused-<trigger>/<d|last|opt>`: a call the contract's methods refuse
+  leaves the instance exactly as it was. The triggers are
+  `program_change` with a negative, boolean or float `sample_position`, or
+  an index of 0.0, 1.0, True, -1, None or "0"; `set_macro` with an index
+  or value of the wrong type, a negative or float `sample_position` or
+  NaN; and the two no-ops the contract allows (an index past the last
+  patch, `channel=-1`). The call lands before pull 8 on an instance built
+  at the defaults (`d`), at the last patch (`last`) and with every numeric
+  constructor option moved off its default (`opt`, which is where a
+  constructor's exact value lives). A raise must be ValueError, TypeError
+  or IndexError. Whether it raised or was accepted as a no-op, every macro
+  reads back the same (on the 0-127 grid and as `macro()` plays it),
+  `patch_index` is unchanged, and the render equals one from an instance
+  that never saw the call. A call that is not a no-op and is accepted is
+  not judged (`ok(a)`).
+
 **ceiling** (`kit_ceiling.py`). At the level the class says it is clean
 at, on the worst material, the output does not wrap, sit on a rail, or go
 silent. The class states `INPUT_CEILING_DBFS` (dBFS, 0 or below); with
@@ -145,6 +163,29 @@ this repository or a parent), never changed; with no checkout, or without
 the pinned commit in it, an audiodsp citation prints `na(...)`. Line
 numbers are all it can know: a citation whose lines moved still resolves.
 
+**nogb** (`kit_nogb.py`). A class whose primed voice is flushed by
+`audiocore.get_buffer` misbehaves on the board builds that compile it out
+of CircuitPython: the block the voice still holds plays later, source
+frames from the start of the material at a point where they do not belong.
+The check hides `get_buffer` from the class's module, its bases' modules
+and `audioeffects` (it replaces the `audiocore` name they read with a
+stand-in that has everything but `get_buffer`, and puts it back; the
+matrix's own pulls keep the real one) and compares two things with the
+run that has it.
+
+- Lifecycle cells (E1, E5, E6, E10 at 48 kHz, stereo and mono, every
+  patch): P1 to P4 must be the same kind of verdict (ok, na, RED), so a
+  cell is red when the class is fine with `get_buffer` and not without. The
+  frames a red verdict names are not compared.
+- `bytes-<scenario>/48000/<channels>/<d|pK>`: the whole render, every
+  channel, byte for byte: a reset, two resets in a row, a reset before the
+  first pull, a patch change and a reset in one block, and resets a block
+  apart. A class whose first block is rightly gated differently without
+  `get_buffer` declares the cell in `DECLARED`.
+
+CPython only. A module that imports `get_buffer` inside a function is not
+reached.
+
 ## Options
 
 `kit_options.py` holds `KIT_OPTIONS`, the constructor options the kit
@@ -166,16 +207,21 @@ prints `decl` and counts as declared. Nothing else skips a cell.
 
 ## The plants
 
-`tests/test_kit.py` holds every check red on a planted fault and its
-control green on the same cell, with the plants in `kit_planted.py`
-(a Waveshaper and a level around the source; `KitPlain` is the control):
-`ShortTail` and `EventTail` (tail; `EchoTail` the control), `NoneSilent`
-and `NoneDC` (a None tail), `Inert`, `KnobReach` and `SoftOnly` (plants),
-a fixture test module with a missing sentence, a missing test, a failing
-and a skipped test and a loose claim (claims), `ReadbackOff`,
-`StopRaises`, `NanLevel`, `PatchStale` and `CtorNan` (args), `WrapKit`,
-`ClipKit` and `DeadStop` (ceiling), a missing CHANGELOG line and citations
-past the end of a file or to no file (paperwork), and `Silent`, which does
-nothing. Its native half holds the render checks to the same lines on all
-three interpreters, and shows that agreement can fail with `ImplKit`,
-whose level differs off CPython.
+`tests/test_kit.py` holds every check red on a planted fault and its control
+green on the same cell, with the plants in `kit_planted.py` (a Waveshaper
+and a level around the source; `KitPlain` is the control): `ShortTail` and
+`EventTail` (tail; `EchoTail` the control), `NoneSilent` and `NoneDC` (a
+None tail), `Inert`, `KnobReach` and `SoftOnly` (plants), a fixture test
+module with a missing sentence, a missing test, a failing and a skipped test
+and a loose claim (claims), `ReadbackOff`, `StopRaises`, `NanLevel`,
+`PatchStale` and `CtorNan` (args; `ClearsFirst` and `ClearsMacro` for the
+refused calls: one zeroes the cached level, the other drops the patch or
+moves a macro, before validating), `WrapKit`, `ClipKit` and `DeadStop`
+(ceiling), a missing CHANGELOG line and citations past the end of a file or
+to no file (paperwork), `FlushOnly` and `DoubleReset` (nogb: the first leans
+on `get_buffer` to flush a primed voice, the second drops a block on a
+second reset in a row without it; `FlushKit`, which primes a voice of its own
+and plays it again where it cannot flush, is the control), and `Silent`, which does nothing. Its native half
+holds the render checks to the same lines on all three interpreters, and
+shows that agreement can fail with `ImplKit`, whose level differs off
+CPython.
\ No newline at end of file
diff --git a/tests/support/kit.py b/tests/support/kit.py
index 529308a..e334df9 100644
--- a/tests/support/kit.py
+++ b/tests/support/kit.py
@@ -1,4 +1,4 @@
-"""The effects kit: six mechanical checks on one class, no model in the loop.
+"""The effects kit: seven mechanical checks on one class, no model in the loop.
 
     python tests/support/kit.py DigitalDelay [--only tail,plants,...]
         [--quick] [--plants-module NAME] [--claims-module NAME] [--no-run]
@@ -6,7 +6,8 @@
 Prints one line per cell, `name|check|key|V:verdict[|h:digest]`, a
 SUMMARY line per check, and DONE. On MicroPython and CircuitPython
 (`MICROPYPATH=lib:tests/support`) it runs the four render checks; the
-claims and paperwork checks read source and git, and run on CPython only.
+claims, paperwork and nogb checks read source and git or patch modules,
+and run on CPython only.
 `KIT.md` beside this file says what each check measures and its bars.
 """
 
@@ -19,8 +20,9 @@
 
 import kit_common as kc
 
-CHECKS = ("paperwork", "claims", "args", "plants", "ceiling", "tail")
-STATIC = ("paperwork", "claims")
+CHECKS = ("paperwork", "claims", "args", "plants", "ceiling", "tail",
+          "nogb")
+STATIC = ("paperwork", "claims", "nogb")
 
 
 def run_check(check, cls, emit=print, quick=False, plants_module=None,
@@ -43,6 +45,10 @@ def run_check(check, cls, emit=print, quick=False, plants_module=None,
         import kit_ceiling
         return kit_ceiling.run(cls, emit, quick=quick, name=name,
                                options=options)
+    if check == "nogb":
+        import kit_nogb
+        return kit_nogb.run(cls, emit, quick=quick, name=name,
+                            options=options)
     if check == "claims":
         import kit_claims
         return kit_claims.run(cls, emit, module=claims_module,
diff --git a/tests/support/kit_args.py b/tests/support/kit_args.py
index 1df533f..fdc9b3a 100644
--- a/tests/support/kit_args.py
+++ b/tests/support/kit_args.py
@@ -23,6 +23,20 @@
   RAIL_RUN); and a NaN build must render exactly what the defaults or the
   option at 0 render.
 
+- `refused-<trigger>`: a call the contract's methods refuse (a negative,
+  boolean or float `sample_position`, a `program_change` of 0.0, 1.0, True,
+  -1, None or "0", a macro index or value of the wrong type, `channel=-1`)
+  leaves the instance exactly as it was. Built at the defaults (`d`), at
+  its last patch (`last`) and with every numeric constructor option moved
+  off its default (`opt`), it takes the call before pull 8; a call that raises must raise ValueError,
+  TypeError or IndexError, and either way (a call that raises, or one that
+  is accepted or ignored as a no-op: `program_change` of an index past the
+  last patch, a macro set to its own readback) every macro reads back the
+  same on the 0-127 grid and as `macro()` plays it, `patch_index` is
+  unchanged (after a raise, or any `program_change`) and the render equals
+  one from an instance that never saw the call. A call not meant to be a no-op that is
+  accepted is not judged (`a`).
+
 A render that is silent throughout cannot show a difference; such a cell
 prints `na(silent)`.
 
@@ -184,6 +198,141 @@ def patch_cell(cls, patch):
     return "ok"
 
 
+# -- refused calls ---------------------------------------------------------
+
+#: The error classes a refusal may raise.
+REFUSED_ERRORS = (ValueError, TypeError, IndexError)
+
+
+def refusals(cls):
+    """[(label, call, noop)]: each call takes the instance. `noop` is True
+    for a call that must leave the instance as it was whether it raises or
+    not; for the others only a raise is judged."""
+    n = len(cls.MACRO_LABELS)
+    past = max(cls.PATCHES) + 1
+    out = [
+        ("pc-negsp", lambda e: e.program_change(0, sample_position=-5),
+         False),
+        ("pc-boolsp", lambda e: e.program_change(0, sample_position=True),
+         False),
+        ("pc-floatsp", lambda e: e.program_change(0, sample_position=1.5),
+         False),
+        ("pc-0.0", lambda e: e.program_change(0.0), False),
+        ("pc-1.0", lambda e: e.program_change(1.0), False),
+        ("pc-true", lambda e: e.program_change(True), False),
+        ("pc-neg", lambda e: e.program_change(-1), False),
+        ("pc-none", lambda e: e.program_change(None), False),
+        ("pc-str", lambda e: e.program_change("0"), False),
+        ("pc-past", lambda e: e.program_change(past), True),
+        ("pc-far", lambda e: e.program_change(1000000), True),
+        ("sm-index-n", lambda e: e.set_macro(n, 5), False),
+        ("sm-index-neg", lambda e: e.set_macro(-1, 5), False),
+        ("sm-index-float", lambda e: e.set_macro(0.0, 5), False),
+        ("sm-index-true", lambda e: e.set_macro(True, 5), False),
+        ("sm-value-str", lambda e: e.set_macro(0, "x"), False),
+        ("sm-value-none", lambda e: e.set_macro(0, None), False),
+    ]
+    for i in sorted(set((0, n - 1))):
+        out += [
+            ("sm-m%d-negchan" % i,
+             lambda e, i=i: e.set_macro(i, e.get_macro(i), channel=-1),
+             True),
+            ("sm-m%d-negsp" % i,
+             lambda e, i=i: e.set_macro(i, e.get_macro(i),
+                                        sample_position=-5), False),
+            ("sm-m%d-floatsp" % i,
+             lambda e, i=i: e.set_macro(i, e.get_macro(i),
+                                        sample_position=1.5), False),
+            ("sm-m%d-nan" % i, lambda e, i=i: e.set_macro(i, NAN), False),
+        ]
+    return out
+
+
+def _state(e):
+    """What the instance reads back: each macro on the 0-127 grid and in
+    its own units, and the patch."""
+    return (gets(e), [e.macro(i) for i in range(len(type(e).MACRO_LABELS))],
+            e.patch_index)
+
+
+def _nudged(cls):
+    """Candidate option sets with every numeric constructor option off its
+    default (a constructor's exact value is state a refused call can
+    drop)."""
+    out = []
+    for m in (0.73, 1.27):
+        out.append(dict((name, d * m if d else 0.37)
+                        for name, d in options_of(cls)
+                        if name not in _BASE))
+    return [o for o in out if o]
+
+
+def refused_cell(cls, label, variant):
+    patch = (max(cls.PATCHES) or None) if variant == "last" else None
+    options = None
+    if variant == "opt":
+        for options in _nudged(cls):
+            try:
+                _close(fresh(cls, 48000, 2, None, options))
+                break
+            except REFUSALS:
+                options = None
+        if options is None:
+            return "na(no option set builds)"
+    call = None
+    noop = False
+    for lab, fn, nop in refusals(cls):
+        if lab == label:
+            call, noop = fn, nop
+    if call is None:
+        return "RED(no such trigger %s)" % label
+    a = fresh(cls, 48000, 2, patch, options)
+    b = fresh(cls, 48000, 2, patch, options)
+    seen = {}
+
+    def take(e):
+        seen["before"] = _state(e)
+        try:
+            call(e)
+            seen["code"] = "a"
+        except REFUSED_ERRORS:
+            seen["code"] = "r"
+        except Exception as exc:                          # noqa: BLE001
+            seen["code"] = "x"
+            seen["exc"] = type(exc).__name__
+        seen["after"] = _state(e)
+
+    try:
+        ra = kc.render(a, FRAMES)
+        rb = kc.render(b, FRAMES, {K_MOVE: take})
+    finally:
+        _close(a)
+        _close(b)
+    code = seen["code"]
+    if code == "x":
+        return "RED(raised %s)" % seen["exc"]
+    if code == "a" and not noop:
+        return "ok(a)", kc.crc(rb)
+    # An accepted set_macro rightly drops the patch; a refusal never does.
+    if seen["after"][2] != seen["before"][2] and (
+            code == "r" or label.startswith("pc-")):
+        return "RED(%s moved patch_index to %r)" % (
+            "a refusal" if code == "r" else "the call", seen["after"][2])
+    for part, what in ((0, "read"), (1, "plays")):
+        for i, (x, y) in enumerate(zip(seen["before"][part],
+                                       seen["after"][part])):
+            if x != y:
+                return "RED(m%d %s %s, now %s)" % (i, what, kc.num(x),
+                                                   kc.num(y))
+    if ra != rb:
+        d = lifecycle._first_diff(ra, rb, 0, len(ra))
+        return "RED(renders differ from frame %d)" % (d // 4 - K_MOVE *
+                                                      kc.BLOCK), kc.crc(rb)
+    if _silent(ra) and _silent(rb):
+        return "na(silent)", kc.crc(rb)
+    return "ok(%s)" % code, kc.crc(rb)
+
+
 # -- constructor options ---------------------------------------------------
 
 
@@ -356,6 +505,10 @@ def cell(key, fn, *args):
         cell("bad-m%d" % i, bad_cell, cls, i)
     for patch in sorted(cls.PATCHES):
         cell("patch-p%d" % patch, patch_cell, cls, patch)
+    for label, _call, _noop in refusals(cls):
+        for variant in ("d", "last", "opt"):
+            cell("refused-%s/%s" % (label, variant), refused_cell, cls,
+                 label, variant)
     for option, _default in options_of(cls):
         if option in _BASE:
             continue
diff --git a/tests/support/kit_nogb.py b/tests/support/kit_nogb.py
new file mode 100644
index 0000000..f562c04
--- /dev/null
+++ b/tests/support/kit_nogb.py
@@ -0,0 +1,219 @@
+"""A board build with no `audiocore.get_buffer`.
+
+CircuitPython's default board builds compile `audiocore.get_buffer` out
+(CIRCUITPY_AUDIOCORE_DEBUG), and a class that primes a voice at
+construction and flushes the primed block by pulling it once is then left
+holding that block. The first pull, or the first pull after a Mix move back
+from a bypass, plays source frames from the start of the material at a
+later point: the stale-block shape.
+
+This check runs the lifecycle matrix's E1 (reset), E5 (Mix to 0 and back),
+E6 (patches) and E10 (events before the first pull) at 48000 Hz, stereo and
+mono, twice: once as it is, once with `get_buffer` hidden from the class's
+module, from `audioeffects` (`_component` and the rebuilt classes) and from
+the classes the class derives from. A cell is one lifecycle cell; it is red
+when any of P1 to P4 reads other than it did with `get_buffer` present
+(ok, na or RED: the frames a red verdict names are not compared).
+
+`bytes-<scenario>` cells hold the whole render, every channel, to equal
+the one with `get_buffer` present: a reset, two resets in a row, a reset
+before the first pull, a patch change and a reset in one block, at the
+defaults and at the last patch, stereo and mono.
+
+CPython only: it patches the `audiocore` name those modules read, with a
+stand-in that has everything but `get_buffer`, and puts it back afterwards.
+The matrix's own pulls (lifecycle, kit_common) keep the real one. A module
+that imports `get_buffer` inside a function is not reached.
+
+    python tests/support/kit_nogb.py StereoWidener
+"""
+
+import sys
+
+if __name__ == "__main__":
+    sys.path.insert(0, "lib")
+    sys.path.insert(0, "tests/support")
+
+import audiocore
+import kit_common as kc
+import lifecycle
+
+CHECK = "nogb"
+EVENTS = ("E1", "E5", "E6", "E10")
+PROPS = ("P1", "P2", "P3", "P4")
+#: Modules whose own pulls the matrix needs.
+KEEP = ("lifecycle", "kit_common")
+
+
+class _NoGetBuffer:
+    """`audiocore` without `get_buffer`."""
+
+    def __init__(self, real):
+        self.__dict__["_real"] = real
+
+    def __getattr__(self, name):
+        if name == "get_buffer":
+            raise AttributeError(name)
+        return getattr(self._real, name)
+
+
+def _modules(cls):
+    names = set(["audioeffects._component"])
+    for name in list(sys.modules):
+        if name == "audioeffects" or name.startswith("audioeffects."):
+            names.add(name)
+    for base in cls.__mro__:
+        names.add(base.__module__)
+    return [sys.modules[n] for n in sorted(names)
+            if n in sys.modules and n not in KEEP]
+
+
+class hidden:
+    """Hide `audiocore.get_buffer` from `cls`'s modules for a `with`."""
+
+    def __init__(self, cls):
+        self.cls = cls
+        self.saved = []
+
+    def __enter__(self):
+        real = audiocore
+        stand_in = _NoGetBuffer(real)
+        pull = real.get_buffer
+        for module in _modules(self.cls):
+            for key, value in list(vars(module).items()):
+                if value is real:
+                    self.saved.append((module, key, value))
+                    setattr(module, key, stand_in)
+                elif value is pull:
+                    self.saved.append((module, key, value))
+                    delattr(module, key)
+        return self
+
+    def __exit__(self, *exc):
+        for module, key, value in reversed(self.saved):
+            setattr(module, key, value)
+        self.saved = []
+        return False
+
+
+def _parse(lines):
+    out = {}
+    for line in lines:
+        parts = line.split("|")
+        if parts[0] == "SUMMARY" or len(parts) < 6:
+            continue
+        key = "%s/%s/%s/%s" % (parts[1], parts[2], parts[3], parts[4])
+        got = {}
+        for part in parts[5:]:
+            prop, _sep, verdict = part.partition(":")
+            got[prop] = verdict
+        out[key] = got
+    return out
+
+
+def _kind(verdict):
+    """ok, na, decl or RED: the numbers in a red verdict move with the
+    frames a run happens to lose, and are not compared."""
+    return (verdict or "none").split("(")[0]
+
+
+def _twice(*calls):
+    def go(e):
+        for call in calls:
+            call(e)
+    return go
+
+
+def _reset(e):
+    e.reset()
+
+
+def _last_patch(e):
+    e.program_change(max(type(e).PATCHES))
+
+
+#: name: {pull index: action}. Resets that follow each other, a reset
+#: before anything has been pulled, a patch change and a reset in one block.
+SCENARIOS = (
+    ("reset-once", {8: _reset}),
+    ("reset-twice", {8: _twice(_reset, _reset)}),
+    ("reset-first", {0: _reset}),
+    ("reset-first-twice", {0: _twice(_reset, _reset)}),
+    ("patch-reset", {8: _twice(_last_patch, _reset)}),
+    ("reset-patch", {8: _twice(_reset, _last_patch)}),
+    ("resets-apart", {8: _reset, 9: _reset}),
+)
+FRAMES = 16384
+
+
+def _render(cls, options, rate, ch, patch, actions):
+    import kit_args
+    feed = kc.feed(kit_args.probe(ch), rate, ch)
+    e = kc.build(cls, feed.port, rate, patch, options)
+    try:
+        return kc.render(e, FRAMES, actions)
+    finally:
+        e.deinit()
+
+
+def _bytes_cell(cls, options, rate, ch, patch, actions):
+    want = _render(cls, options, rate, ch, patch, actions)
+    with hidden(cls):
+        got = _render(cls, options, rate, ch, patch, actions)
+    if got == want:
+        return "ok"
+    d = lifecycle._first_diff(want, got, 0, len(want))
+    return "RED(bytes differ without get_buffer from frame %d, channel %d)" \
+        % (d // (2 * ch), (d // 2) % ch)
+
+
+def _run(cls, options, quick, name):
+    lines = []
+    lifecycle.run_class(cls, options=options, rates=(48000,),
+                        only=EVENTS, quick=quick, emit=lines.append,
+                        name=name)
+    return _parse(lines)
+
+
+def run(cls, emit=print, quick=False, name=None, options=None):
+    """Every nogb cell for `cls`; returns the red count."""
+    cells = kc.Cells(name or cls.NAME, CHECK, emit)
+    if not kc.CPYTHON:
+        return cells.summary()
+    present = _run(cls, options, quick, cells.name)
+    try:
+        with hidden(cls):
+            absent = _run(cls, options, quick, cells.name)
+    except Exception as exc:                              # noqa: BLE001
+        cells.cell("run", "RED(raised %s: %s)" % (type(exc).__name__, exc))
+        return cells.summary()
+    for patch in (None, max(cls.PATCHES) or None):
+        for ch in (2, 1):
+            for label, actions in SCENARIOS:
+                key = "bytes-%s/48000/%d/%s" % (
+                    label, ch, "d" if patch is None else "p%d" % patch)
+                try:
+                    cells.cell(key, _bytes_cell(cls, options or {}, 48000,
+                                                ch, patch, actions))
+                except Exception as exc:                  # noqa: BLE001
+                    cells.cell(key, "RED(raised %s: %s)" % (
+                        type(exc).__name__, exc))
+    for key in sorted(present):
+        want = present[key]
+        got = absent.get(key)
+        if got is None:
+            cells.cell(key, "RED(no cell without get_buffer)")
+            continue
+        diff = [p for p in PROPS if _kind(want.get(p)) != _kind(got.get(p))]
+        if diff:
+            cells.cell(key, "RED(%s)" % "; ".join(
+                "%s %s with get_buffer, %s without" % (
+                    p, want.get(p), got.get(p)) for p in diff))
+        else:
+            cells.cell(key, "ok")
+    return cells.summary()
+
+
+if __name__ == "__main__":
+    import kit
+    kit.main(sys.argv[1:], only=(CHECK,))
diff --git a/tests/support/kit_planted.py b/tests/support/kit_planted.py
index f902967..0fa4c8e 100644
--- a/tests/support/kit_planted.py
+++ b/tests/support/kit_planted.py
@@ -14,6 +14,9 @@
 except ImportError:                                   # pragma: no cover
     array = None
 
+import audiocore
+import audiomixer
+import lifecycle
 from audioeffects import _component
 
 #: `_component` reads VENDOR off the module a class is defined in.
@@ -307,8 +310,91 @@ def _level(self):
         return KitPlain._level(self)
 
 
+class ClearsFirst(KitPlain):
+    """Args: program_change zeroes the cached level before it validates,
+    so a refused call leaves the next render quiet."""
+    NAME = "ClearsFirst"
+
+    def program_change(self, index, *args, **kw):
+        self._shaper.set(post_gain=0.0)
+        KitPlain.program_change(self, index, *args, **kw)
+
+
+class ClearsMacro(KitPlain):
+    """Args: a refused set_macro has already dropped the patch, and a
+    refused program_change has already moved a macro."""
+    NAME = "ClearsMacro"
+
+    def set_macro(self, index, value, *args, **kw):
+        self._patch_index = None
+        KitPlain.set_macro(self, index, value, *args, **kw)
+
+    def program_change(self, index, *args, **kw):
+        self._macros[1] = 0.5
+        KitPlain.program_change(self, index, *args, **kw)
+
+
+# -- a board build with no audiocore.get_buffer -----------------------------
+
+
+class FlushKit(lifecycle.Routed):
+    """The control for nogb: Routed, with a voice of its own, primed at
+    construction and flushed by pulling its mixer once. Where
+    `audiocore.get_buffer` is absent it plays that voice again instead, so
+    nothing it renders depends on which it did."""
+    NAME = "FlushKit"
+
+    def _build(self, mix=1.0, gain=1.0, patch=None):
+        ch = self._channel_count
+        self._quiet = self._own(audiomixer.Mixer(
+            voice_count=1, **self._pcm(lifecycle.BLOCK * ch * 2)), reset=False)
+        self._zeros = lifecycle._raw(array("h", bytes(2 * 8 * ch)),
+                                     self._sample_rate, ch)
+        self._quiet.voice[0].play(self._zeros, loop=True)
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(self._quiet)
+        else:
+            self._quiet.voice[0].play(self._zeros, loop=True)
+        lifecycle.Routed._build(self, mix, gain, patch)
+
+
+class FlushOnly(lifecycle.Routed):
+    """Nogb: the voices are primed whenever the graph is armed (at
+    construction, after a reset, when Mix comes back) and flushed only by
+    pulling the mixer; with no `get_buffer` the primed block stays in the
+    voice and plays later, out of step."""
+    NAME = "FlushOnly"
+
+    def _arm(self):
+        lifecycle.Routed._arm(self)
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(self._mixer)
+
+
+class DoubleReset(FlushKit):
+    """Nogb: with no `get_buffer`, a second reset in a row plays the voices
+    again, which drops the block they held and takes the source's next one:
+    a block of the render is gone."""
+    NAME = "DoubleReset"
+    _fresh = False
+
+    def reset(self):
+        again = self._fresh
+        FlushKit.reset(self)
+        self._fresh = True
+        if again and getattr(audiocore, "get_buffer", None) is None:
+            lifecycle.Routed._arm(self)
+
+    def set_macro(self, *args, **kw):
+        self._fresh = False
+        FlushKit.set_macro(self, *args, **kw)
+
+
 PLANTS = {}
 for _cls in (KitPlain, Silent, WrapKit, WrapKitQuiet, ClipKit, DeadStop,
              ImplKit, EchoTail, ShortTail, EventTail, NoneSilent, NoneDC,
-             ReadbackOff, StopRaises, NanLevel, PatchStale, CtorNan):
+             ReadbackOff, StopRaises, NanLevel, PatchStale, CtorNan,
+             ClearsFirst, ClearsMacro, FlushKit, FlushOnly, DoubleReset):
     PLANTS[_cls.NAME] = _cls
diff --git a/tests/test_kit.py b/tests/test_kit.py
index 2946a50..6f86ad7 100644
--- a/tests/test_kit.py
+++ b/tests/test_kit.py
@@ -26,6 +26,7 @@
 import kit_ceiling                                        # noqa: E402
 import kit_claims                                         # noqa: E402
 import kit_common as kc                                   # noqa: E402
+import kit_nogb                                           # noqa: E402
 import kit_paperwork                                      # noqa: E402
 import kit_planted as kp                                  # noqa: E402
 import kit_plants                                         # noqa: E402
@@ -167,6 +168,32 @@ def test_each_plant_is_red_and_the_control_green(self):
                 self.assertTrue(self.call(fn, kp.KitPlain, args)
                                 .startswith("ok"), key)
 
+    def test_a_refused_call_that_moves_something_is_red(self):
+        # ClearsFirst zeroes the level before it validates (a render that
+        # differs); ClearsMacro moves a macro, or drops the patch, first.
+        for plant, label, variant in (
+                (kp.ClearsFirst, "pc-negsp", "last"),
+                (kp.ClearsFirst, "pc-true", "d"),
+                (kp.ClearsMacro, "pc-0.0", "d"),
+                (kp.ClearsMacro, "sm-index-n", "d"),
+                (kp.ClearsMacro, "sm-m0-negsp", "last")):
+            with self.subTest(plant=plant.NAME, label=label):
+                self.assertTrue(red(self.call(
+                    kit_args.refused_cell, plant, (label, variant))))
+                self.assertTrue(self.call(
+                    kit_args.refused_cell, kp.KitPlain,
+                    (label, variant)).startswith("ok"))
+
+    def test_every_refusal_is_green_on_the_control(self):
+        cells = cells_of(kit_args.run, kp.KitPlain, quick=True)
+        refused = [k for k in (key for (_n, _c, key) in cells)
+                   if k.startswith("refused-")]
+        self.assertEqual(len(refused),
+                         3 * len(kit_args.refusals(kp.KitPlain)))
+        for key in refused:
+            self.assertTrue(verdict(cells, "KitPlain", "args", key)
+                            .startswith("ok"), key)
+
     def test_a_clamp_is_read_as_one(self):
         self.assertEqual(kit_args.bad_cell(kp.KitPlain, 1),
                          "ok(nan:c inf:c -inf:c -1:c 128:c)")
@@ -182,6 +209,59 @@ def test_the_options_are_read_from_the_source(self):
                          [("mix", 1.0), ("gain", 1.0)])
 
 
+def nogb_cells(cls):
+    return cells_of(kit_nogb.run, cls, quick=True)
+
+
+class TestNoGetBuffer(unittest.TestCase):
+
+    def test_the_control_is_green(self):
+        for cls in (kp.KitPlain, kp.FlushKit):
+            with self.subTest(cls=cls.NAME):
+                cells = nogb_cells(cls)
+                self.assertTrue(cells)
+                for key in (k for (_n, _c, k) in cells):
+                    self.assertEqual(verdict(cells, cls.NAME, "nogb", key),
+                                     "ok", key)
+
+    def test_a_flush_that_needs_get_buffer_is_red(self):
+        cells = nogb_cells(kp.FlushOnly)
+        bad = [k for (_n, _c, k) in cells
+               if red(verdict(cells, "FlushOnly", "nogb", k))]
+        self.assertTrue(any(k.startswith("E5-mix0") for k in bad), bad)
+        self.assertTrue(any(k.startswith("bytes-reset-once") for k in bad),
+                        bad)
+
+    def test_a_second_reset_in_a_row_is_red(self):
+        cells = nogb_cells(kp.DoubleReset)
+        bad = sorted(k for (_n, _c, k) in cells
+                     if red(verdict(cells, "DoubleReset", "nogb", k)))
+        self.assertTrue(bad)
+        for k in bad:
+            self.assertTrue(k.startswith(("bytes-reset-first-twice",
+                                          "bytes-resets-apart")), k)
+        self.assertEqual(verdict(cells, "DoubleReset", "nogb",
+                                 "bytes-reset-once/48000/2/d"), "ok")
+
+    def test_get_buffer_is_put_back(self):
+        import audiocore
+        import audioeffects._component as component
+        real = audiocore.get_buffer
+        with kit_nogb.hidden(kp.FlushOnly):
+            self.assertIsNone(getattr(component.audiocore, "get_buffer",
+                                      None))
+            self.assertIsNone(getattr(kp.audiocore, "get_buffer", None))
+            self.assertIs(audiocore.get_buffer, real)
+            self.assertIs(lifecycle.audiocore, audiocore)
+        self.assertIs(component.audiocore, audiocore)
+        self.assertIs(kp.audiocore, audiocore)
+
+    def test_red_numbers_are_not_compared(self):
+        self.assertEqual(kit_nogb._kind("RED(differs at +1)"),
+                         kit_nogb._kind("RED(differs at +9)"))
+        self.assertNotEqual(kit_nogb._kind("ok"), kit_nogb._kind("RED(x)"))
+
+
 class TestCeiling(unittest.TestCase):
 
     def v(self, cls, which="sine", patch=None, knob=None):

From baa0c904b24508ad5539cd6d7fd31364f7f95bc9 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:08:29 -0500
Subject: [PATCH 20/76] Octaver: the Phase 6 rebuild, its trait tests, plants
 and claims

The OC-2's octave-down on a clock leg (two Q 0.5 low-passes, a dead-band
comparator, SubOctave) and a signal leg (a matched two-stage AllPass and
Multiply), Octave 2 dividing Tone 1's output, three voices on a Mixer.
Seven macros, six patches; constructor values land on the 0-127 grid.
Declares the divider's free count (lifecycle P4), the family P5 rows,
CircuitPython's own Mixer on a host reset, and clicks under Sensitivity
in the ceiling check.
---
 CHANGELOG.md                          |    7 +
 lib/audioeffects/rebuilt/octaver.py   |  414 ++++++++++
 tests/support/kit_common.py           |    4 +
 tests/support/lifecycle.py            |   31 +
 tests/test_cpython_effects_octaver.py | 1074 +++++++++++++++++++++++++
 5 files changed, 1530 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/octaver.py
 create mode 100644 tests/test_cpython_effects_octaver.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..273af3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`Octaver` (rebuilt, Phase 6):** the analog octave-down, after the
+  Boss OC-2. The octave is your own note with every other cycle turned
+  over, clocked from a low-passed copy and multiplied into an all-passed
+  one, so it keeps your attack and decay and tracks from E2 to A4 at the
+  default. Seven controls: Direct, Octave 1, Octave 2, Tracking, Tone 1,
+  Tone 2 and Sensitivity, and six patches. It drops the shifter-based
+  class's octave up and its `down=`, `up=`, `down2=` and `up2=` options.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/octaver.py b/lib/audioeffects/rebuilt/octaver.py
new file mode 100644
index 0000000..1aabdab
--- /dev/null
+++ b/lib/audioeffects/rebuilt/octaver.py
@@ -0,0 +1,414 @@
+"""`Octaver` - the analog octave-down.
+
+The player's text is the class docstring; the `CLAIMS` table in the class's
+test file ties its claim sentences to tests. How the graph works is told
+where it is built, in `Octaver._build`.
+"""
+
+VENDOR = "PyDevices"
+
+from array import array
+
+import audiocore
+
+from .. import _component
+
+try:
+    import audiobiquad
+    import audiomath
+    import audiomixer
+    import audioroute
+    import audioshaper
+except ImportError:                     # pragma: no cover - a stock board
+    audiobiquad = audiomath = audiomixer = audioroute = audioshaper = None
+
+
+DIRECT_I, OCTAVE1_I, OCTAVE2_I, TRACKING_I, TONE1_I, TONE2_I, SENS_I = \
+    range(7)
+
+#: The constructor defaults, which NaN falls back to (patch 0).
+DEFAULTS = (1.0, 0.7, 0.0, 90.0, 324.0, 70.3, -80.0)
+
+#: The comparator's table: 4097 points over the shaper's -1..1, exact zero
+#: across |i - 2048| <= 63 and the rails beyond. Interpolating between two
+#: points of a one-point step is a gain stage, which leaks an octave up and
+#: DC below Sensitivity; a dead band many points wide reads exact zero.
+CURVE_POINTS = 4097
+DEAD_HALF = 63
+#: The comparator reaches the rail where its input times `pre_gain` is
+#: 64/2048, so `pre_gain = EDGE / 10^(Sensitivity/20)` puts the rail at the
+#: clock's level of Sensitivity. 1/32 is exact in every float format.
+EDGE = 0.03125
+
+#: The clock filters' Q: two sections of 0.5 are four coincident real
+#: poles, whose phase a two-stage first-order all-pass matches exactly.
+CLOCK_Q = 0.5
+TONE_Q = 0.7071
+
+#: The divider of the clock leg: a +-1 square from the comparator's +-rail.
+CLOCK_THRESHOLD = 0.5
+CLOCK_HOLD_MS = 1.0
+
+#: Frames a mixer pull hands out, and so what every node and tap takes per
+#: pull: the palette's own block, so the Splitters' rings empty each pull.
+BLOCK = 256
+
+_CURVE = None
+
+
+def comparator_curve():
+    """The comparator's table, built once and shared by every instance."""
+    global _CURVE
+    if _CURVE is None:
+        rail = (CURVE_POINTS - 1) // 2 - DEAD_HALF
+        _CURVE = array("h", [-32767] * rail + [0] * (2 * DEAD_HALF + 1)
+                       + [32767] * rail)
+    return _CURVE
+
+
+def pre_gain(sensitivity_db):
+    """The comparator's input gain for a Sensitivity in dBFS."""
+    return EDGE / (10.0 ** (sensitivity_db / 20.0))
+
+
+def _allpass_ring(coefficient):
+    """Frames two first-order all-pass sections ring for, as an upper
+    bound: the cascade is a repeated real pole at -coefficient, which
+    `_component.biquad_ring` bounds as a biquad with that double pole."""
+    a = -coefficient
+
+    class _Pole:
+        coefficients = (1.0, 0.0, 0.0, -2.0 * a, a * a)
+    return _component.biquad_ring(_Pole)
+
+
+class Octaver(_component.Component):
+    """An octave down that is your own note: like the Boss OC-2, it turns
+    every other cycle of what you play upside down, so the octave keeps
+    your attack, your decay and your tone.
+
+    **The controls.** Direct, Octave 1 and Octave 2 are the three levels,
+    each from 0 to 1.
+    Tracking, from 40 to 400 Hz, moves the range of notes the divider
+    follows.
+    Tone 1 (100 to 2000 Hz) and Tone 2 (40 to 800 Hz) are two-pole
+    low-passes at the hertz they show, on the first and second octave.
+    Sensitivity, from -90 to -40 dBFS, is how quiet a note can get before
+    the octaves stop.
+    Constructor values land on the nearest of each knob's 128 steps.
+
+    **What you hear.** The octave is exactly half your note and sounds
+    within 2 ms of it.
+    Octave 2 is Octave 1 divided again: two octaves down, not a fourth
+    below the note.
+    On low notes, to A2, the octave follows your note's decay within 1 dB:
+    it has no envelope of its own.
+    Below Sensitivity the octaves are silent, with no ghost and no hum.
+    With the Tones open the octave carries a fifth above it 4.4 dB
+    quieter, as the pedal's multiplication does, wherever Tracking is set.
+    Turning Tone 1 down thins that fifth more on high notes than on low
+    ones.
+
+    **Its range.** At patch 0, on a mono source, every note from low E
+    (E2) to A4 divides cleanly, even with a strong second harmonic.
+    The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.
+    Below the range a low note's second harmonic clocks the divider and it
+    skips; above it the clock is low-passed under Sensitivity and the
+    octave goes silent.
+    Between -90 and -84.5 dBFS Sensitivity changes nothing: that whole
+    stretch is one step of the clock.
+
+    **Limits.** It plays one note at a time: on a power chord (A2 and E3)
+    about two fifths of the octave is intermodulation.
+    A stereo source is clocked on its mid: with the right channel 45
+    degrees ahead of the left, the fifth sits 3.2 dB under the octave
+    instead of 4.4, on both channels.
+    So near the top of the range a stereo note whose channels cancel each
+    other's fundamental can drop out: one stereo A4 in eight did, at
+    patch 0.
+    The output can peak at 2.8 times the input (a square wave, with Octave
+    2 at full), so keep the input under -9 dBFS.
+    A control that jumps makes the output step: move it in small steps
+    from the host if you need it smooth.
+
+    **Wire, latency, tail.** With both octaves at 0 and Direct at 1 the
+    output is the input, byte for byte.
+    There is no latency.
+    `tail_samples` covers the all-pass and the two Tone filters ringing
+    down.
+    `reset()` clears the filters and the dividers and returns to patch 0.
+    The class never reads the host's tempo.
+    """
+
+    NAME = 'Octaver'
+    DISPLAY_NAME = 'Octaver'
+    CATEGORIES = ('Pitch Shift',)
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioroute", "audiobiquad", "audioshaper", "audiomath")
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    TAIL_SAMPLES = None
+
+    #: The worst peak gain over the kit's material, every patch and every
+    #: stop, is 2.75 (a square, Octave 2 at full): -9 dBFS keeps it inside
+    #: full scale.
+    INPUT_CEILING_DBFS = -9.0
+
+    MACRO_LABELS = ("Direct", "Octave 1", "Octave 2", "Tracking", "Tone 1",
+                    "Tone 2", "Sensitivity")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR",
+                   3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR",
+                   6: "UNIPOLAR"}
+    _MACRO_RANGES = (
+        (0.0, 1.0),                     # 0  Direct
+        (0.0, 1.0),                     # 1  Octave 1
+        (0.0, 1.0),                     # 2  Octave 2
+        (40.0, 400.0, "log"),           # 3  Tracking, Hz
+        (100.0, 2000.0, "log"),         # 4  Tone 1, Hz
+        (40.0, 800.0, "log"),           # 5  Tone 2, Hz
+        (-90.0, -40.0),                 # 6  Sensitivity, dBFS
+    )
+
+    #: `_component.macro_of` of the card's settings: 0.7 is 89, 0.8 is 102,
+    #: 0.6 is 76; Tracking 90/50/200 Hz is 45/12/89; Tone 1 324/250/700 Hz
+    #: is 50/39/82; Tone 2 70.3 Hz is 24; Sensitivity -80 dBFS is 25.
+    PATCHES = {
+        0: ("Octave down under the dry", (127, 89, 0, 45, 50, 24, 25)),
+        1: ("Both octaves", (102, 89, 89, 45, 50, 24, 25)),
+        2: ("Octaves alone, no dry", (0, 127, 76, 45, 50, 24, 25)),
+        3: ("Bass guitar", (127, 102, 0, 12, 39, 24, 25)),
+        4: ("High on the neck", (127, 89, 0, 89, 82, 24, 25)),
+        5: ("Two octaves down alone", (0, 0, 127, 45, 50, 24, 25)),
+    }
+
+    def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
+               tone1_hz=324.0, tone2_hz=70.3, sensitivity_db=-80.0,
+               patch=None):
+        grid = self._grid((direct, octave1, octave2, tracking_hz, tone1_hz,
+                           tone2_hz, sensitivity_db))
+        rate = self._sample_rate
+        channels = self._channel_count
+        self._ready = False
+        self._armed = False
+
+        self._silence = self._own(audiocore.RawSample(
+            array("h", bytes(2 * 2 * channels)),
+            sample_rate=rate, channel_count=channels), reset=False)
+
+        # One Splitter, three legs: the dry voice, the signal the octave is
+        # made of, and the clock that says when to turn it over. The clock
+        # and the signal are kept apart because `SubOctave` clocks on what
+        # it divides, so a tracking filter in front of it would darken the
+        # octave too (12 dB from E2 to G3, measured on the card's probes).
+        split = self._own(audioroute.Splitter(self._source, taps=3),
+                          reset=False)
+        self._dry = split.tap(0)
+        self._allpass = None
+        self._clock = []
+        signal = self._signal_leg(split.tap(1))
+        square = self._clock_leg(split.tap(2))
+        self._product = self._octave(signal, square)
+        self._tone1 = self._own(audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=324.0, Q=TONE_Q, mix=1.0,
+            sample_rate=rate, channel_count=channels))
+        self._tone1.play(self._product)
+
+        # Octave 2 divides Octave 1's filtered output, on that signal's own
+        # crossings, as the pedal's second stage does.
+        split2 = self._own(audioroute.Splitter(self._tone1, taps=2),
+                           reset=False)
+        self._octave1 = split2.tap(0)
+        self._divider2 = self._second(split2.tap(1))
+        self._tone2 = self._own(audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=70.3, Q=TONE_Q, mix=1.0,
+            sample_rate=rate, channel_count=channels))
+        self._tone2.play(self._divider2)
+
+        # Not reset: the voices keep the source frames they have taken, and
+        # a Mixer reset is no reset of anything this class holds.
+        self._mixer = self._own(audiomixer.Mixer(
+            voice_count=3, **self._pcm(BLOCK * channels * 2)), reset=False)
+        self._output = self._mixer
+
+        self._init_macros(tuple(
+            _component.macro_value(self._MACRO_RANGES[i], grid[i] / 127.0)
+            for i in range(7)))
+        # Land each knob exactly on its step, as patch 0 does.
+        for i in range(7):
+            position = _component.position_of_midi("UNIPOLAR", grid[i])
+            if self._macros[i] != position:
+                self._macros[i] = position
+                self._apply_macro(i, position)
+
+        _component.open_level_gates(self._mixer, self._mixer.voice,
+                                    self._silence)
+        self._ready = True
+        self._route()
+        if patch is not None:
+            self.program_change(patch)
+
+    def _grid(self, asked):
+        """Each constructor value as its knob's nearest MIDI step: NaN is
+        the default, anything past a stop is that stop."""
+        grid = []
+        for i in range(7):
+            value = float(asked[i])
+            if value != value:
+                value = DEFAULTS[i]
+            span = self._MACRO_RANGES[i]
+            value = min(span[1], max(span[0], value))
+            grid.append(int(round(
+                127.0 * _component.macro_position(span, value))))
+        return grid
+
+    # -- the legs; each a method, so a test can plant a fault in one ------
+
+    def _signal_leg(self, tap):
+        """Two first-order all-pass sections at Tracking. The clock's two
+        Q 0.5 sections are four coincident real poles, whose phase is
+        exactly this cascade's, so the square turns over on the signal's own
+        zero crossings and the octave keeps the multiplication's balance."""
+        self._allpass = self._own(audiobiquad.AllPass(
+            stages=2, frequency=90.0, feedback=0.0, mix=1.0,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._allpass.play(tap)
+        return self._allpass
+
+    def _mid(self, tap):
+        """A stereo clock runs on the mid, so both channels turn over on
+        the same crossings; a mono one runs on the tap."""
+        if self._channel_count != 2:
+            return tap
+        mid = self._own(audioroute.MidSide(
+            width=0.0, sample_rate=self._sample_rate, channel_count=2))
+        mid.play(tap)
+        return mid
+
+    def _clock_leg(self, tap):
+        """Low-pass at Tracking, a comparator with a dead band, and a
+        divider that hands out a +-1 square at half the note (zero while the
+        comparator reads zero)."""
+        clock = self._mid(tap)
+        for _ in range(2):
+            section = self._own(audiobiquad.Biquad(
+                mode=audiobiquad.LOW_PASS, frequency=90.0, Q=CLOCK_Q,
+                mix=1.0, sample_rate=self._sample_rate,
+                channel_count=self._channel_count))
+            section.play(clock)
+            clock = section
+            self._clock.append(section)
+        self._comparator = self._own(audioshaper.Waveshaper(
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count, curve=self._curve(),
+            oversample=1, mix=1.0, pre_gain=self._pre_gain(DEFAULTS[SENS_I]),
+            post_gain=1.0))
+        self._comparator.play(clock)
+        self._divider = self._own(audiomath.SubOctave(
+            self._comparator, order=1, mix=1.0, threshold=CLOCK_THRESHOLD,
+            hold_ms=CLOCK_HOLD_MS, sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        return self._divider
+
+    def _curve(self):
+        return comparator_curve()
+
+    def _pre_gain(self, sensitivity_db):
+        return pre_gain(sensitivity_db)
+
+    def _octave(self, signal, square):
+        """The signal times the square: every other cycle turned over."""
+        return self._own(audiomath.Multiply(
+            signal, square, mix=1.0, sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+
+    def _second(self, tap):
+        """Octave 1's output divided again."""
+        return self._own(audiomath.SubOctave(
+            tap, order=1, mix=1.0, sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+
+    def _set_tracking(self, hz):
+        if self._allpass is not None:
+            self._allpass.frequency = hz
+        for section in self._clock:
+            section.frequency = hz
+
+    def _tone1_hz(self):
+        return self._hz(self._value(TONE1_I))
+
+    # -- the controls ----------------------------------------------------
+
+    def _value(self, index):
+        return _component.macro_value(self._MACRO_RANGES[index],
+                                      self._macros[index])
+
+    def _apply_macro(self, index, position):
+        del position
+        if index == TRACKING_I:
+            self._set_tracking(self._hz(self._value(TRACKING_I)))
+        elif index == TONE1_I:
+            self._tone1.frequency = self._tone1_hz()
+        elif index == TONE2_I:
+            self._tone2.frequency = self._hz(self._value(TONE2_I))
+        elif index == SENS_I:
+            self._comparator.set(
+                pre_gain=self._pre_gain(self._value(SENS_I)))
+        else:
+            self._route()
+
+    def _is_wire(self):
+        return (self._macros[DIRECT_I] >= 1.0
+                and self._macros[OCTAVE1_I] <= 0.0
+                and self._macros[OCTAVE2_I] <= 0.0)
+
+    def _levels(self):
+        voices = self._mixer.voice
+        voices[0].level = self._value(DIRECT_I)
+        voices[1].level = self._value(OCTAVE1_I)
+        voices[2].level = self._value(OCTAVE2_I)
+
+    def _route(self):
+        """Direct at 1 with both octaves at 0 hands out the source itself;
+        anything else plays the mixer, re-armed if the graph was left."""
+        if self._is_wire():
+            self._route_around(self._source)
+            self._armed = False
+            return
+        if not self._ready:
+            self._levels()
+            return
+        if self._rejoin() or not self._armed:
+            # The nodes are clear; the voices still hold the blocks they
+            # had queued. Armed as `_build` arms them: levels, gates,
+            # voices, then the port.
+            self._levels()
+            _component.open_level_gates(self._mixer, self._mixer.voice,
+                                        self._silence)
+            voices = self._mixer.voice
+            voices[0].play(self._dry, loop=True)
+            voices[1].play(self._octave1, loop=True)
+            voices[2].play(self._tone2, loop=True)
+            self._armed = True
+        self._output = self._mixer
+        self._levels()
+
+    @property
+    def tail_samples(self):
+        """The all-pass and both Tone filters ringing down, end to end."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        if self._is_wire():
+            return 0
+        ring = 0
+        if self._allpass is not None:
+            ring = _allpass_ring(self._allpass.coefficient)
+        tones = _component.cascade_ring((self._tone1, self._tone2))
+        if ring is None or tones is None:
+            return None
+        return ring + tones
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..4a3d9e3 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,10 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("Octaver", "ceiling", "clicks/"):
+        "with Direct at 0 only the octaves sound, and one-sample clicks"
+        " through the clock's low-pass stay under Sensitivity, where the"
+        " octaves are silent by design (trait T3 b)",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..1142b9f 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,6 +75,37 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
+    ("Octaver", "E1-", "P4"):
+        "a flip-flop divider keeps its count: a reset starts it in"
+        " pass-through polarity part-way through the material, so the"
+        " octave stays inverted against an instance that was never reset"
+        " (it matches a fresh one; the OC-2's flip-flops do the same)",
+    ("Octaver", "E2-", "P4"):
+        "CircuitPython only: its own audiomixer.Mixer resets the voices on"
+        " a host reset, so Tone 2's voice loses the frames it held and"
+        " Octave 2 runs late against the others (audiodsp#229's upstream"
+        " half, ruled to be declared in Phase 6); CPython and MicroPython"
+        " are ok",
+    ("Octaver", "E4-", "P4"):
+        "a flip-flop divider keeps its count: a move that adds or drops a"
+        " crossing (Tracking, Tone 1, Sensitivity) or the clear on the way"
+        " back from the wire leaves the octave inverted for good",
+    ("Octaver", "E6-", "P4"):
+        "a flip-flop divider keeps its count: a patch change that moves"
+        " Tracking or Tone 1 adds or drops a crossing, and the octave stays"
+        " inverted",
+    ("Octaver", "E11-", "P4"):
+        "a flip-flop divider keeps its count: moves that add or drop a"
+        " crossing leave the octave inverted",
+    ("Octaver", "E4-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step",
+    ("Octaver", "E6-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (a patch change moves the levels)",
+    ("Octaver", "E11-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
new file mode 100644
index 0000000..5cd7ca1
--- /dev/null
+++ b/tests/test_cpython_effects_octaver.py
@@ -0,0 +1,1074 @@
+"""`Octaver`'s trait and planted-fault tests.
+
+Six traits, T1 to T6, each with its measurement run over the span listed
+with it and the same measurement shown red on a planted fault of the same
+kind. `KIT_PLANTS` hands the plants to the kit, which shows each one
+differs from the clean class and that no knob stop or patch reproduces it.
+`CLAIMS` ties every claim sentence of the docstring to the tests that hold
+it.
+
+Every law a measurement checks against is written out here, never taken
+from the class: the octave's pitch, the RBJ low-pass, the clock's
+attenuation, the material.
+
+The module is numpy-free and imports on MicroPython and CircuitPython,
+where `unittest` is absent: the kit reads `KIT_PLANTS` there. Every level is
+read with a Hann-windowed Goertzel written out below.
+"""
+
+import math
+import sys
+from array import array
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                     # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    import os
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.join(_HERE, "..", "lib"))
+except (ImportError, AttributeError, NameError):   # no os.path natively
+    pass
+
+import audiomath                                            # noqa: E402
+import audioroute                                           # noqa: E402
+import kit_common as kc                                     # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+VENDOR = "PyDevices"
+
+RATES = (48000, 22050)
+BLOCK = 256
+DIRECT, OCT1, OCT2, TRACKING, TONE1, TONE2, SENS = range(7)
+
+Octaver = rebuilt.module_class("Octaver")
+
+NOTES = {"E1": 41.2, "A1": 55.0, "E2": 82.41, "A2": 110.0, "D3": 146.8,
+         "G3": 196.0, "B3": 246.9, "E3": 164.8, "A3": 220.0, "E4": 329.6,
+         "A4": 440.0, "E5": 659.3}
+
+#: Each patch's tracking window (card T2 and T5).
+WINDOWS = {0: ("E2", "A2", "D3", "G3", "B3", "E4", "A4"),
+           3: ("E1", "A1", "E2", "A2", "D3", "G3"),
+           4: ("D3", "G3", "B3", "E4", "A4", "E5")}
+
+
+# --------------------------------------------------------------------------
+# The laws, written out
+
+
+def midi_of_log(value, low, high):
+    """The float MIDI position of `value` on a log span."""
+    return 127.0 * math.log(value / low) / math.log(high / low)
+
+
+def midi_of_lin(value, low, high):
+    return 127.0 * (value - low) / (high - low)
+
+
+def rbj_lowpass_db(f, fc, q, rate):
+    """|H(f)| of the RBJ cookbook two-pole low-pass, in dB."""
+    w0 = 2.0 * math.pi * fc / rate
+    alpha = math.sin(w0) / (2.0 * q)
+    cw = math.cos(w0)
+    b0 = (1.0 - cw) / 2.0
+    b1 = 1.0 - cw
+    b2 = b0
+    a0 = 1.0 + alpha
+    a1 = -2.0 * cw
+    a2 = 1.0 - alpha
+    w = 2.0 * math.pi * f / rate
+    zr, zi = math.cos(w), -math.sin(w)          # z^-1
+    z2r, z2i = zr * zr - zi * zi, 2.0 * zr * zi  # z^-2
+    nr = b0 + b1 * zr + b2 * z2r
+    ni = b1 * zi + b2 * z2i
+    dr = a0 + a1 * zr + a2 * z2r
+    di = a1 * zi + a2 * z2i
+    return 10.0 * math.log10((nr * nr + ni * ni) / (dr * dr + di * di))
+
+
+def clock_attenuation(f, fc):
+    """Two Q 0.5 low-pass sections: four coincident real poles."""
+    return (1.0 / (1.0 + (f / fc) ** 2)) ** 2
+
+
+# --------------------------------------------------------------------------
+# Material and measurement
+
+
+class Rng:
+    """A 31-bit LCG: the same uniforms on every interpreter."""
+
+    def __init__(self, seed):
+        self.state = (seed * 2654435761 + 12345) & 0x7FFFFFFF
+
+    def uniform(self, low, high):
+        self.state = (1103515245 * self.state + 12345) & 0x7FFFFFFF
+        return low + (high - low) * (self.state / 2147483648.0)
+
+
+def _partials(f, n, rate, amps, phases):
+    """Sum of sines k*f, by the two-term recurrence, below Nyquist."""
+    y = [0.0] * n
+    for k in range(1, len(amps) + 1):
+        if k * f >= rate / 2.0:
+            break
+        w = 2.0 * math.pi * k * f / rate
+        c = 2.0 * math.cos(w)
+        a = amps[k - 1]
+        s2 = a * math.sin(phases[k - 1] - w)
+        s1 = a * math.sin(phases[k - 1])
+        for i in range(n):
+            y[i] += s1
+            s1, s2 = c * s1 - s2, s1
+    return y
+
+
+def rich(f, n, seed, rate, shift=0.0):
+    """Material R: twelve harmonics, U(0.3, 1)/k^U(0.5, 1), the second
+    scaled by a further U(1, 2.5), phases U(0, 2 pi) moved `shift` * k,
+    normalised to 12000 peak."""
+    rng = Rng(seed)
+    amps = [rng.uniform(0.3, 1.0) for _ in range(12)]
+    exponent = rng.uniform(0.5, 1.0)
+    amps = [amps[k] / (k + 1) ** exponent for k in range(12)]
+    amps[1] *= rng.uniform(1.0, 2.5)
+    phases = [rng.uniform(0.0, 2.0 * math.pi) + shift * (k + 1)
+              for k in range(12)]
+    y = _partials(f, n, rate, amps, phases)
+    peak = max(max(y), -min(y))
+    return [12000.0 * v / peak for v in y]
+
+
+def sine(f, n, rate, amp=16384.0, phase=0.0, start=0):
+    y = [0.0] * n
+    for i in range(start, n):
+        y[i] = amp * math.sin(2.0 * math.pi * f * (i - start) / rate + phase)
+    return y
+
+
+def pcm(left, right=None):
+    """Interleaved int16 from one or two float lists."""
+    if right is None:
+        return array("h", [max(-32768, min(32767, int(round(v))))
+                           for v in left])
+    out = array("h", bytes(4 * len(left)))
+    for i in range(len(left)):
+        out[2 * i] = max(-32768, min(32767, int(round(left[i]))))
+        out[2 * i + 1] = max(-32768, min(32767, int(round(right[i]))))
+    return out
+
+
+def channel(values, channels, which=0):
+    return [values[i] for i in range(which, len(values), channels)]
+
+
+def render(cls, values, rate, channels, frames=None, options=None,
+           patch=None, macros=None):
+    """`cls` around `values`, then silence: `frames` frames as int16."""
+    if frames is None:
+        frames = len(values) // channels
+    feed = kc.feed(values, rate, channels)
+    e = cls(feed.port, sample_rate=rate, **(options or {}))
+    try:
+        if patch is not None:
+            e.program_change(patch)
+        for index, value in (macros or ()):
+            e.set_macro(index, value)
+        return kc.samples(kc.render(e, frames))
+    finally:
+        e.deinit()
+
+
+#: Octave 1 alone, Octave 2 alone: the mixer voice at 1.0 is a wire.
+ONLY1 = ((DIRECT, 0), (OCT1, 127), (OCT2, 0))
+ONLY2 = ((DIRECT, 0), (OCT1, 0), (OCT2, 127))
+OPEN = ((TONE1, 127), (TONE2, 127))
+
+_HANN = {}
+
+
+def _hann(n):
+    if n not in _HANN:
+        if len(_HANN) > 16:
+            _HANN.clear()
+        step = 2.0 * math.pi / (n - 1)
+        window = [0.5 - 0.5 * math.cos(step * i) for i in range(n)]
+        _HANN[n] = (window, sum(window))
+    return _HANN[n]
+
+
+def level_db(y, f, rate):
+    """Hann-windowed Goertzel amplitude of `y` at `f`, in dB re 1."""
+    n = len(y)
+    window, total = _hann(n)
+    c = 2.0 * math.cos(2.0 * math.pi * f / rate)
+    s1 = s2 = 0.0
+    for i in range(n):
+        s1, s2 = y[i] * window[i] + c * s1 - s2, s1
+    power = s1 * s1 + s2 * s2 - c * s1 * s2
+    amp = math.sqrt(max(power, 0.0)) * 2.0 / total
+    return 20.0 * math.log10(amp + 1e-12)
+
+
+def tail_part(y):
+    """The render with its first quarter discarded."""
+    return y[len(y) // 4:]
+
+
+def rising_pitch(y, rate):
+    """Frequency from rising zero crossings."""
+    count = 0
+    first = last = None
+    for i in range(1, len(y)):
+        if y[i - 1] <= 0 < y[i]:
+            if first is None:
+                first = i
+            last = i
+            count += 1
+    return (count - 1) * rate / (last - first)
+
+
+def cents(ratio):
+    return 1200.0 * math.log(ratio) / math.log(2.0)
+
+
+# --------------------------------------------------------------------------
+# The measurements
+
+
+def t1_pitch(cls, rate, channels, f):
+    n = int(1.5 * rate)
+    s = sine(f, n, rate)
+    values = pcm(s, s if channels == 2 else None)
+    y = render(cls, values, rate, channels, macros=ONLY1)
+    return cents(rising_pitch(channel(y, channels)[rate // 2:], rate)
+                 / (f / 2.0))
+
+
+def t1_onset_ms(cls, rate, channels, f, start=480):
+    n = rate // 2
+    s = sine(f, n, rate, start=start)
+    values = pcm(s, s if channels == 2 else None)
+    y = channel(render(cls, values, rate, channels, macros=ONLY1), channels)
+    for i in range(n):
+        if abs(y[i]) >= 8:
+            return 1000.0 * (i - start) / rate
+    return None
+
+
+def balance(y, f, rate):
+    """level(f/2) - level(3f/2)."""
+    return level_db(y, f / 2.0, rate) - level_db(y, 1.5 * f, rate)
+
+
+def t2_mono(cls, rate, patch):
+    """{note: balance} over the patch's window, Tones open."""
+    out = {}
+    for name in WINDOWS[patch]:
+        f = NOTES[name]
+        if 1.5 * f > 0.45 * rate:
+            continue
+        n = int(1.5 * rate)
+        y = render(cls, pcm(sine(f, n, rate)), rate, 1, patch=patch,
+                   macros=ONLY1 + OPEN)
+        out[name] = balance(tail_part(y), f, rate)
+    return out
+
+
+def t2_stereo(cls, rate, degrees):
+    """{note: (left, right)} at patch 0, R leading L by `degrees`."""
+    out = {}
+    for name in WINDOWS[0]:
+        f = NOTES[name]
+        n = int(1.5 * rate)
+        values = pcm(sine(f, n, rate),
+                     sine(f, n, rate, phase=math.radians(degrees)))
+        y = render(cls, values, rate, 2, macros=ONLY1 + OPEN)
+        out[name] = (balance(tail_part(channel(y, 2, 0)), f, rate),
+                     balance(tail_part(channel(y, 2, 1)), f, rate))
+    return out
+
+
+def windows_db(y, f, rate, width, count):
+    return [level_db(y[i * width:(i + 1) * width], f, rate)
+            for i in range(count)]
+
+
+def t3_envelope(cls, rate, name, seed):
+    """(spread, median) of Octave 1's f/2 against the input's f, per 8/f
+    window, while the note is above -36 dBFS, after the first two."""
+    f = NOTES[name]
+    n = 2 * rate
+    r = rich(f, n, seed, rate)
+    x = [32767.0 * 10.0 ** ((-6.0 - 40.0 * i / n) / 20.0) * r[i] / 12000.0
+         for i in range(n)]
+    values = pcm(x)
+    y = render(cls, values, rate, 1, macros=ONLY1 + ((SENS, 0),))
+    width = int(round(8.0 * rate / f))
+    count = int(1.5 * rate) // width
+    xin = [float(v) for v in values]
+    diffs = [a - b for a, b in zip(windows_db(y, f / 2.0, rate, width, count),
+                                   windows_db(xin, f, rate, width, count))]
+    diffs = sorted(diffs[2:])
+    return diffs[-1] - diffs[0], diffs[len(diffs) // 2]
+
+
+def t3_sensitivity(cls, rate, name, sens=-50.0):
+    """The worst Octave 1 power (DC included) against the input's, in dB,
+    over the 8/f windows that start with the clock 3 dB under
+    Sensitivity."""
+    f = NOTES[name]
+    probe = cls(kc.feed(array("h", bytes(4)), rate, 1).port,
+                sample_rate=rate)
+    fc = probe.macro(TRACKING)
+    probe.deinit()
+    n = 3 * rate
+    a0 = 10.0 ** ((sens + 20.0) / 20.0) * 32768.0 / clock_attenuation(f, fc)
+    amp = [a0 * 10.0 ** (-60.0 * i / n / 20.0) for i in range(n)]
+    x = [amp[i] * math.sin(2.0 * math.pi * f * i / rate) for i in range(n)]
+    values = pcm(x)
+    y = render(cls, values, rate, 1,
+               macros=ONLY1 + ((SENS, midi_of_lin(sens, -90.0, -40.0)),))
+    width = int(round(8.0 * rate / f))
+    worst = -999.0
+    for k in range(n // width):
+        lo = k * width
+        clock = amp[lo] * clock_attenuation(f, fc) / 32768.0
+        if 20.0 * math.log10(clock) > sens - 3.0:
+            continue
+        out = sum(v * v for v in y[lo:lo + width]) / width
+        inp = sum(float(v) * v for v in values[lo:lo + width]) / width
+        rel = 10.0 * math.log10(out + 1e-30) - 10.0 * math.log10(inp)
+        worst = max(worst, rel)
+    return worst
+
+
+def t4_split(cls, rate, channels, name, tones_open):
+    f = NOTES[name]
+    n = rate
+    s = sine(f, n, rate)
+    values = pcm(s, s if channels == 2 else None)
+    y = render(cls, values, rate, channels,
+               macros=ONLY2 + (OPEN if tones_open else ()))
+    y = tail_part(channel(y, channels))
+    return level_db(y, f / 4.0, rate) - level_db(y, 0.75 * f, rate)
+
+
+def t5_margin(y, f, rate):
+    """Octave 1's f/2 over the strongest of f/4, 3f/4, f and 2f."""
+    main = level_db(y, f / 2.0, rate)
+    stray = max(level_db(y, q, rate) for q in (f / 4.0, 0.75 * f, f,
+                                                2.0 * f))
+    return main - stray
+
+
+def t5_clean(cls, rate, channels, patch, name, seeds=8):
+    """How many of `seeds` R notes divide cleanly (>= 20 dB), and the
+    smallest margin."""
+    f = NOTES[name]
+    n = rate // 2
+    clean = 0
+    low = 999.0
+    for seed in range(seeds):
+        left = rich(f, n, seed, rate)
+        right = rich(f, n, seed, rate, shift=0.3) if channels == 2 else None
+        y = render(cls, pcm(left, right), rate, channels, patch=patch,
+                   macros=ONLY1)
+        margin = t5_margin(tail_part(channel(y, channels)), f, rate)
+        clean += margin >= 20.0
+        low = min(low, margin)
+    return clean, low
+
+
+def t6_change(cls, rate, f, tone_hz, index=TONE1, low=100.0, high=2000.0,
+              split=2.0):
+    """The change in the octave's balance between Tone at `tone_hz` and at
+    its top stop, with the prediction from the hertz the knob shows. For
+    Tone 1 the balance is f/2 against 3f/2 of Octave 1; for Tone 2,
+    f/4 against 3f/4 of Octave 2 (`split` 4)."""
+    n = rate
+    values = pcm(sine(f, n, rate))
+    only = ONLY1 if index == TONE1 else ONLY2
+    lo, hi = f / split, 3.0 * f / split
+    readings = []
+    shown = []
+    for midi in (midi_of_log(tone_hz, low, high), 127):
+        feed = kc.feed(values, rate, 1)
+        e = cls(feed.port, sample_rate=rate)
+        for i, v in only + OPEN + ((index, midi),):
+            e.set_macro(i, v)
+        shown.append(e.macro(index))
+        y = tail_part(kc.samples(kc.render(e, n)))
+        e.deinit()
+        readings.append(level_db(y, lo, rate) - level_db(y, hi, rate))
+    measured = readings[0] - readings[1]
+    predicted = ((rbj_lowpass_db(lo, shown[0], 0.7071, rate)
+                  - rbj_lowpass_db(hi, shown[0], 0.7071, rate))
+                 - (rbj_lowpass_db(lo, shown[1], 0.7071, rate)
+                    - rbj_lowpass_db(hi, shown[1], 0.7071, rate)))
+    return measured, predicted
+
+
+# --------------------------------------------------------------------------
+# The planted faults
+
+
+class PitchShiftOctave(Octaver):
+    """T1: a splice shifter an octave down in place of the multiply."""
+
+    def _octave(self, signal, square):
+        import audiodelays
+        shifter = self._own(audiodelays.PitchShift(
+            semitones=-12.0, mix=1.0, sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        shifter.play(signal)
+        return shifter
+
+
+class HeldAllPass(Octaver):
+    """T2: the all-pass held at 90 Hz while Tracking moves."""
+
+    def _set_tracking(self, hz):
+        Octaver._set_tracking(self, hz)
+        if self._allpass is not None:
+            self._allpass.frequency = 90.0
+
+
+class NoAllPass(Octaver):
+    """T2: the signal multiplied as it comes, the switch off its
+    crossings."""
+
+    def _signal_leg(self, tap):
+        return tap
+
+
+class NoMidSide(Octaver):
+    """T2 stereo: each channel clocked on itself, one divider's polarity
+    across both."""
+
+    def _mid(self, tap):
+        return tap
+
+
+class SquareToTone(Octaver):
+    """T2: the comparator's square fed straight to Tone 1, no multiply."""
+
+    def _octave(self, signal, square):
+        return square
+
+
+class Compressed(Octaver):
+    """T3 (a): a compressor after the multiply, an envelope of its own."""
+
+    def _octave(self, signal, square):
+        import audiodynamics
+        product = Octaver._octave(self, signal, square)
+        comp = self._own(audiodynamics.Dynamics(
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count, threshold_db=-30.0,
+            ratio=4.0, attack_ms=1.0, release_ms=100.0))
+        comp.play(product)
+        return comp
+
+
+class WireOctave(Octaver):
+    """T3 (a): the signal itself in place of the octave."""
+
+    def _octave(self, signal, square):
+        return signal
+
+
+class OneBinCurve(Octaver):
+    """T3 (b): the comparator as a one-point step, which the shaper's
+    interpolation turns into a gain stage."""
+
+    def _curve(self):
+        half = 2048
+        return array("h", [-32767] * half + [0] + [32767] * half)
+
+    def _pre_gain(self, sensitivity_db):
+        return (2.0 / 4096.0) / 10.0 ** (sensitivity_db / 20.0)
+
+
+class FourthBelow(Octaver):
+    """T4: Octave 2 as `SubOctave(order=2)` on the all-passed dry."""
+
+    def _signal_leg(self, tap):
+        node = Octaver._signal_leg(self, tap)
+        fan = self._own(audioroute.Splitter(node, taps=2), reset=False)
+        self._fan = fan
+        return fan.tap(0)
+
+    def _second(self, tap):
+        return self._own(audiomath.SubOctave(
+            self._fan.tap(1), order=2, mix=1.0,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+
+
+class ClockWire(Octaver):
+    """T5: both clock filters taken out of the clock leg."""
+
+    def _clock_leg(self, tap):
+        square = Octaver._clock_leg(self, tap)
+        self._comparator.play(self._mid_node)
+        return square
+
+    def _mid(self, tap):
+        self._mid_node = Octaver._mid(self, tap)
+        return self._mid_node
+
+
+class DoubleTone(Octaver):
+    """T6: Tone 1 at twice the hertz its knob shows."""
+
+    def _tone1_hz(self):
+        return self._hz(2.0 * Octaver._tone1_hz(self))
+
+
+KIT_PLANTS = {
+    "T1": PitchShiftOctave,
+    "T2-held": (HeldAllPass, 3),
+    "T2-none": NoAllPass,
+    "T2-mid": NoMidSide,
+    "T2-square": SquareToTone,
+    "T3-comp": Compressed,
+    "T3-wire": WireOctave,
+    "T3-bin": OneBinCurve,
+    "T4": (FourthBelow, 1),
+    "T5": ClockWire,
+    "T6": DoubleTone,
+}
+
+
+# --------------------------------------------------------------------------
+# The trait tests (CPython: unittest)
+
+#: T5's one stereo draw that drops out at the top of patch 0's window
+#: (seed 7, at both rates): its mid's fundamental sits under Sensitivity
+#: once the clock filter has taken 55 dB off it.
+T5_STEREO_DROPOUT = (0, "A4", 7)
+
+
+def _within(value, target, tolerance):
+    return abs(value - target) <= tolerance
+
+
+class T1Divider(TestCase):
+    """The octave is exactly f/2 and sounds within 2 ms of the note."""
+
+    NOTES_HZ = (82.41, 110.0, 111.0, 196.0)
+
+    def test_the_pitch_is_half_the_note(self):
+        for rate in RATES:
+            for channels in (1, 2):
+                for f in self.NOTES_HZ:
+                    off = t1_pitch(Octaver, rate, channels, f)
+                    self.assertLessEqual(abs(off), 1.0,
+                                         (rate, channels, f, off))
+
+    def test_the_onset_is_within_2_ms(self):
+        for rate in RATES:
+            for channels in (1, 2):
+                for f in (82.41, 110.0, 196.0):
+                    onset = t1_onset_ms(Octaver, rate, channels, f)
+                    self.assertIsNotNone(onset)
+                    self.assertLessEqual(onset, 2.0, (rate, channels, f))
+
+    def test_a_pitch_shifter_is_red(self):
+        rate = 48000
+        offs = [t1_pitch(PitchShiftOctave, rate, 1, f)
+                for f in self.NOTES_HZ]
+        onsets = [t1_onset_ms(PitchShiftOctave, rate, 1, f)
+                  for f in (82.41, 110.0, 196.0)]
+        self.assertTrue(any(abs(c) > 1.0 for c in offs), offs)
+        self.assertTrue(all(o > 2.0 for o in onsets), onsets)
+
+
+class T2Multiplication(TestCase):
+    """Tones open: f/2 over 3f/2 is 4.44 +- 0.3 dB over each patch's
+    window, at its Tracking; 3.2 +- 0.3 dB on both channels of a stereo
+    source with R 45 degrees ahead."""
+
+    def test_mono_every_window(self):
+        for rate in RATES:
+            for patch in (0, 3, 4):
+                for name, value in t2_mono(Octaver, rate, patch).items():
+                    self.assertTrue(_within(value, 4.44, 0.3),
+                                    (rate, patch, name, value))
+
+    def test_stereo_45_degrees(self):
+        for rate in RATES:
+            for name, pair in t2_stereo(Octaver, rate, 45).items():
+                for value in pair:
+                    self.assertTrue(_within(value, 3.2, 0.3),
+                                    (rate, name, pair))
+
+    def test_in_phase_stereo_reads_as_mono(self):
+        rate = 48000
+        mono = t2_mono(Octaver, rate, 0)
+        for name, pair in t2_stereo(Octaver, rate, 0).items():
+            self.assertAlmostEqual(pair[0], mono[name], delta=0.01)
+            self.assertAlmostEqual(pair[1], mono[name], delta=0.01)
+
+    def _red(self, cls, patch):
+        values = t2_mono(cls, 48000, patch)
+        return [v for v in values.values() if not _within(v, 4.44, 0.3)]
+
+    def test_an_all_pass_held_at_90_hz_is_red(self):
+        self.assertTrue(self._red(HeldAllPass, 3))
+        self.assertTrue(self._red(HeldAllPass, 4))
+
+    def test_no_all_pass_is_red(self):
+        self.assertTrue(self._red(NoAllPass, 0))
+
+    def test_the_square_straight_to_tone_1_is_red(self):
+        self.assertTrue(self._red(SquareToTone, 0))
+
+    def test_no_mid_side_is_red(self):
+        values = t2_stereo(NoMidSide, 48000, 45)
+        self.assertTrue(any(not _within(pair[1], 3.2, 0.3)
+                            for pair in values.values()), values)
+
+
+class T3Dynamics(TestCase):
+    """(a) On R decaying 40 dB at E2 and A2, Octave 1's f/2 tracks the
+    note's f within 1 dB, median at least -20 dB. (b) Once the clock is
+    3 dB under Sensitivity, Octave 1 is 60 dB under the input."""
+
+    ENVELOPE_NOTES = ("E2", "A2")
+
+    def test_the_octave_follows_the_decay(self):
+        for rate in RATES:
+            for name in self.ENVELOPE_NOTES:
+                for seed in range(8):
+                    spread, median = t3_envelope(Octaver, rate, name, seed)
+                    self.assertLessEqual(spread, 1.0, (rate, name, seed))
+                    self.assertGreaterEqual(median, -20.0,
+                                            (rate, name, seed))
+
+    def test_silent_below_sensitivity(self):
+        for rate in RATES:
+            for name in ("E2", "D3"):
+                self.assertLessEqual(t3_sensitivity(Octaver, rate, name),
+                                     -60.0, (rate, name))
+
+    def test_a_compressor_is_red(self):
+        spread, _ = t3_envelope(Compressed, 48000, "E2", 0)
+        self.assertGreater(spread, 1.0)
+
+    def test_a_wire_for_the_octave_is_red(self):
+        _, median = t3_envelope(WireOctave, 48000, "E2", 0)
+        self.assertLess(median, -20.0)
+
+    def test_a_one_point_comparator_is_red(self):
+        self.assertGreater(t3_sensitivity(OneBinCurve, 48000, "E2"), -60.0)
+
+
+class T4SecondOctave(TestCase):
+    """Octave 2's f/4 over 3f/4: +6 dB with the Tones open, +9 at patch 0."""
+
+    NAMES = ("E2", "A2", "D3", "G3", "B3")
+
+    def test_two_octaves_down(self):
+        for rate in RATES:
+            for channels in (1, 2):
+                for name in self.NAMES:
+                    self.assertGreaterEqual(
+                        t4_split(Octaver, rate, channels, name, True), 6.0)
+                    self.assertGreaterEqual(
+                        t4_split(Octaver, rate, channels, name, False), 9.0)
+
+    def test_a_fourth_below_is_red(self):
+        self.assertLess(t4_split(FourthBelow, 48000, 1, "E2", True), 6.0)
+
+
+class T5Range(TestCase):
+    """8/8 draws of R divide cleanly (f/2 20 dB over its neighbours) at
+    every note of each patch's window."""
+
+    def _window(self, rate, channels):
+        for patch in (0, 3, 4):
+            for name in WINDOWS[patch]:
+                clean, low = t5_clean(Octaver, rate, channels, patch, name)
+                if (channels == 2 and (patch, name)
+                        == T5_STEREO_DROPOUT[:2]):
+                    self.assertEqual(clean, 7, (patch, name, rate, low))
+                    continue
+                self.assertEqual(clean, 8, (rate, channels, patch, name,
+                                            low))
+
+    def test_the_windows_mono(self):
+        for rate in RATES:
+            self._window(rate, 1)
+
+    def test_the_windows_stereo(self):
+        for rate in RATES:
+            self._window(rate, 2)
+
+    def test_a_stereo_note_can_drop_out_at_the_top(self):
+        patch, name, seed = T5_STEREO_DROPOUT
+        f = NOTES[name]
+        for rate in RATES:
+            n = rate // 2
+            left = rich(f, n, seed, rate)
+            right = rich(f, n, seed, rate, shift=0.3)
+            stereo = render(Octaver, pcm(left, right), rate, 2, patch=patch,
+                            macros=ONLY1)
+            mono = render(Octaver, pcm(left), rate, 1, patch=patch,
+                          macros=ONLY1)
+            self.assertLess(
+                t5_margin(tail_part(channel(stereo, 2)), f, rate), 20.0)
+            self.assertGreaterEqual(t5_margin(tail_part(mono), f, rate),
+                                    20.0)
+
+    def test_outside_the_window(self):
+        rate = 48000
+        clean, _ = t5_clean(Octaver, rate, 1, 0, "E1")
+        self.assertLess(clean, 8)
+        f = NOTES["E5"]
+        for seed in range(8):
+            y = render(Octaver, pcm(rich(f, rate // 2, seed, rate)), rate,
+                       1, patch=0, macros=ONLY1)
+            # The attack's step clocks it for a moment; then silence.
+            self.assertFalse(any(tail_part(y)), seed)
+
+    def test_wires_for_the_clock_filters_are_red(self):
+        for rate in RATES:
+            counts = [t5_clean(ClockWire, rate, 1, 0, name)[0]
+                      for name in WINDOWS[0]]
+            self.assertLess(min(counts), 8, counts)
+
+
+class T6Tone(TestCase):
+    """The change in Octave 1's f/2 over 3f/2 between Tone 1 at 324 Hz and
+    at 2000 Hz is the RBJ two-pole's, within 0.25 dB."""
+
+    NOTES_HZ = (164.8, 220.0, 329.6)
+
+    def test_tone_1_is_a_two_pole_low_pass(self):
+        for rate in RATES:
+            changes = []
+            for f in self.NOTES_HZ:
+                measured, predicted = t6_change(Octaver, rate, f, 324.0)
+                self.assertAlmostEqual(measured, predicted, delta=0.25)
+                changes.append(measured)
+            self.assertLess(changes[0], changes[1])
+            self.assertLess(changes[1], changes[2])
+
+    def test_tone_2_is_a_two_pole_low_pass(self):
+        for rate in RATES:
+            for f in (110.0, 146.8, 196.0):
+                measured, predicted = t6_change(
+                    Octaver, rate, f, 70.3, index=TONE2, low=40.0,
+                    high=800.0, split=4.0)
+                self.assertAlmostEqual(measured, predicted, delta=0.25)
+
+    def test_tone_1_at_twice_its_hertz_is_red(self):
+        misses = [abs(m - p) for m, p in
+                  (t6_change(DoubleTone, 48000, f, 324.0)
+                   for f in self.NOTES_HZ)]
+        self.assertGreater(max(misses), 0.25, misses)
+
+
+class TheSurface(TestCase):
+    """The controls, the wire, latency, tail, reset and tempo."""
+
+    def _fresh(self, rate=48000, channels=1, **options):
+        feed = kc.feed(array("h", bytes(4 * channels)), rate, channels)
+        return Octaver(feed.port, sample_rate=rate, **options)
+
+    def test_the_spans(self):
+        e = self._fresh()
+        self.assertEqual(e.MACRO_LABELS, ("Direct", "Octave 1", "Octave 2",
+                                          "Tracking", "Tone 1", "Tone 2",
+                                          "Sensitivity"))
+        ends = ((0.0, 1.0), (0.0, 1.0), (0.0, 1.0), (40.0, 400.0),
+                (100.0, 2000.0), (40.0, 800.0), (-90.0, -40.0))
+        for i, (low, high) in enumerate(ends):
+            e.set_macro(i, 0)
+            self.assertAlmostEqual(e.macro(i), low, places=9)
+            e.set_macro(i, 127)
+            self.assertAlmostEqual(e.macro(i), high, places=9)
+        e.deinit()
+
+    def test_constructor_values_land_on_the_grid(self):
+        e = self._fresh(tracking_hz=100.0, tone1_hz=500.0, octave1=0.33,
+                        sensitivity_db=-61.0)
+        for i, value in ((TRACKING, midi_of_log(100.0, 40.0, 400.0)),
+                         (TONE1, midi_of_log(500.0, 100.0, 2000.0)),
+                         (OCT1, 0.33 * 127.0),
+                         (SENS, midi_of_lin(-61.0, -90.0, -40.0))):
+            self.assertEqual(e.get_macro(i), float(int(round(value))))
+        e.deinit()
+
+    def test_a_fresh_instance_reads_patch_0(self):
+        e = self._fresh()
+        self.assertEqual(tuple(e.get_macro(i) for i in range(7)),
+                         tuple(float(v) for v in Octaver.PATCHES[0][1]))
+        e.deinit()
+
+    def test_sensitivity_dead_stretch(self):
+        """A note decaying 100 dB passes the clock through every level."""
+        for rate in RATES:
+            n = rate
+            x = [16384.0 * 10.0 ** (-100.0 * i / n / 20.0)
+                 * math.sin(2.0 * math.pi * 82.41 * i / rate)
+                 for i in range(n)]
+            values = pcm(x)
+            ref = render(Octaver, values, rate, 1,
+                         macros=ONLY1 + ((SENS, 0),))
+            for midi in (7, 14):
+                self.assertEqual(render(Octaver, values, rate, 1,
+                                        macros=ONLY1 + ((SENS, midi),)),
+                                 ref)
+            self.assertNotEqual(render(Octaver, values, rate, 1,
+                                       macros=ONLY1 + ((SENS, 15),)), ref)
+            self.assertAlmostEqual(-90.0 + 50.0 * 14 / 127.0, -84.49,
+                                   places=2)
+
+    def _material(self, rate, channels):
+        n = BLOCK * (rate // 2 // BLOCK)
+        left = rich(110.0, n, 3, rate)
+        right = rich(110.0, n, 4, rate) if channels == 2 else None
+        return pcm(left, right)
+
+    def test_the_wire_is_the_input(self):
+        for rate in RATES:
+            for channels in (1, 2):
+                values = self._material(rate, channels)
+                n = len(values) // channels
+                y = render(Octaver, values, rate, channels,
+                           options={"octave1": 0.0})
+                self.assertEqual(y, kc.samples(bytes(values)))
+                # An octave up and back: the wire again, byte for byte.
+                feed = kc.feed(values, rate, channels)
+                e = Octaver(feed.port, sample_rate=rate, octave1=0.0)
+                first = kc.render(e, BLOCK * 8)
+                e.set_macro(OCT1, 89)
+                middle = kc.render(e, BLOCK * 8)
+                e.set_macro(OCT1, 0)
+                last = kc.render(e, n - BLOCK * 16)
+                e.deinit()
+                fsize = 2 * channels
+                raw = bytes(values)
+                self.assertEqual(first, raw[:BLOCK * 8 * fsize])
+                self.assertNotEqual(middle,
+                                    raw[BLOCK * 8 * fsize:BLOCK * 16 * fsize])
+                self.assertEqual(last, raw[BLOCK * 16 * fsize:])
+
+    def test_no_latency(self):
+        for rate in (48000, 44100, 22050):
+            values = array("h", bytes(2 * 4096))
+            values[1000] = 12000
+            e = self._fresh(rate=rate)
+            self.assertEqual(e.latency_samples, 0)
+            e.deinit()
+            y = render(Octaver, values, rate, 1)
+            first = [i for i in range(len(y)) if y[i]][0]
+            self.assertEqual(first, 1000)
+            self.assertEqual(y[1000], 12000)
+
+    def test_the_tail_is_bounded(self):
+        slow = ((OCT2, 127), (TRACKING, 0), (TONE1, 0), (TONE2, 0))
+        for rate in RATES:
+            for macros in ((), slow):
+                for name in ("E2", "A2"):
+                    feed = kc.feed(pcm(rich(NOTES[name], rate // 2, 1,
+                                            rate)), rate, 1)
+                    e = Octaver(feed.port, sample_rate=rate)
+                    for i, v in macros:
+                        e.set_macro(i, v)
+                    tail = e.tail_samples
+                    y = kc.samples(kc.render(e, rate // 2 + tail + 4096))
+                    e.deinit()
+                    last = max(i for i in range(len(y)) if y[i])
+                    self.assertGreater(last, rate // 2 - BLOCK)
+                    self.assertLessEqual(last, rate // 2 + tail + BLOCK,
+                                         (rate, macros, name, tail))
+
+    def test_reset_renders_as_fresh(self):
+        rate = 48000
+        values = self._material(rate, 1)
+        n = len(values)
+        gap = array("h", bytes(2 * BLOCK * 128))
+        # The macros come back to patch 0.
+        e = TheSurface._fresh(self)
+        e.program_change(1)
+        e.set_macro(TRACKING, 100)
+        e.reset()
+        self.assertEqual(e.patch_index, 0)
+        self.assertEqual(tuple(e.get_macro(i) for i in range(7)),
+                         tuple(float(v) for v in Octaver.PATCHES[0][1]))
+        e.deinit()
+        # The dividers and filters come back clear: after a note, a pause
+        # and a reset, the next note renders as on a fresh instance. (A
+        # reset that moves a level takes it at the next zero crossing, as
+        # every level move on the mixer does.)
+        feed = kc.feed(values + gap + values, rate, 1)
+        e = Octaver(feed.port, sample_rate=rate)
+        kc.render(e, n + len(gap))
+        e.reset()
+        after = kc.samples(kc.render(e, n))
+        e.deinit()
+        self.assertEqual(after, render(Octaver, values, rate, 1))
+
+    def test_never_reads_the_tempo(self):
+        calls = []
+
+        def transport():
+            calls.append(1)
+            return (True, 0.0, 99.0, 4, 4)
+        feed = kc.feed(self._material(48000, 1), 48000, 1)
+        e = Octaver.create(feed.port, 48000, transport=transport)
+        self.assertEqual(e.capabilities, ())
+        kc.render(e, 4096)
+        e.transport_changed()
+        for i in range(7):
+            e.set_macro(i, 100)
+        e.program_change(2)
+        kc.render(e, 4096)
+        e.deinit()
+        self.assertEqual(calls, [])
+
+    def test_one_note_at_a_time(self):
+        rate = 48000
+
+        def intermodulation(freqs):
+            n = 2 * rate
+            x = [sum(5000.0 * math.sin(2.0 * math.pi * f * i / rate + j)
+                     for j, f in enumerate(freqs)) for i in range(n)]
+            y = render(Octaver, pcm(x), rate, 1, macros=ONLY1)[rate // 2:]
+            total = sum(float(v) * v for v in y) / len(y)
+            lines = set()
+            for f in freqs:
+                for k in range(1, 40, 2):
+                    if k * f / 2.0 < rate / 2.0:
+                        lines.add(k * f / 2.0)
+            wanted = 0.0
+            for q in lines:
+                amp = 10.0 ** (level_db(y, q, rate) / 20.0)
+                wanted += amp * amp / 2.0
+            return 1.0 - wanted / total
+        self.assertLess(intermodulation((110.0,)), 0.01)
+        chord = intermodulation((110.0, 164.81))
+        self.assertTrue(0.35 <= chord <= 0.47, chord)
+
+    def test_the_peak_gain(self):
+        """The kit's square and sine at its own amplitude, at the settings
+        the ceiling found worst and at every patch."""
+        import kit_ceiling
+        rate = 48000
+        amp = 3277
+        worst = 0.0
+        configs = [(None, k) for k in ((OCT1, 127), (OCT2, 127),
+                                       (TONE1, 0))]
+        configs += [(p, None) for p in sorted(Octaver.PATCHES)]
+        for which in ("square", "sine"):
+            values = kit_ceiling.material(which, rate, 1, amp)
+            for patch, knob in configs:
+                y = render(Octaver, values, rate, 1, patch=patch,
+                           macros=(knob,) if knob else ())
+                worst = max(worst, max(abs(v) for v in y) / float(amp))
+        self.assertTrue(2.6 <= worst <= 2.8, worst)
+        self.assertLessEqual(worst * 10.0 ** (
+            Octaver.INPUT_CEILING_DBFS / 20.0), 1.0)
+
+
+CLAIMS = (
+    ("An octave down that is your own note: like the Boss OC-2, it turns "
+     "every other cycle of what you play upside down, so the octave keeps "
+     "your attack, your decay and your tone.",
+     ("T1Divider.test_the_pitch_is_half_the_note",
+      "T1Divider.test_the_onset_is_within_2_ms",
+      "T2Multiplication.test_mono_every_window",
+      "T3Dynamics.test_the_octave_follows_the_decay")),
+    ("Direct, Octave 1 and Octave 2 are the three levels, each from 0 to 1.",
+     "TheSurface.test_the_spans"),
+    ("Tracking, from 40 to 400 Hz, moves the range of notes the divider "
+     "follows.",
+     ("TheSurface.test_the_spans", "T5Range.test_the_windows_mono")),
+    ("Tone 1 (100 to 2000 Hz) and Tone 2 (40 to 800 Hz) are two-pole "
+     "low-passes at the hertz they show, on the first and second octave.",
+     ("TheSurface.test_the_spans",
+      "T6Tone.test_tone_1_is_a_two_pole_low_pass",
+      "T6Tone.test_tone_2_is_a_two_pole_low_pass")),
+    ("Sensitivity, from -90 to -40 dBFS, is how quiet a note can get before "
+     "the octaves stop.",
+     ("TheSurface.test_the_spans",
+      "T3Dynamics.test_silent_below_sensitivity")),
+    ("Constructor values land on the nearest of each knob's 128 steps.",
+     ("TheSurface.test_constructor_values_land_on_the_grid",
+      "TheSurface.test_a_fresh_instance_reads_patch_0")),
+    ("The octave is exactly half your note and sounds within 2 ms of it.",
+     ("T1Divider.test_the_pitch_is_half_the_note",
+      "T1Divider.test_the_onset_is_within_2_ms")),
+    ("Octave 2 is Octave 1 divided again: two octaves down, not a fourth "
+     "below the note.",
+     "T4SecondOctave.test_two_octaves_down"),
+    ("On low notes, to A2, the octave follows your note's decay within "
+     "1 dB: it has no envelope of its own.",
+     "T3Dynamics.test_the_octave_follows_the_decay"),
+    ("Below Sensitivity the octaves are silent, with no ghost and no hum.",
+     "T3Dynamics.test_silent_below_sensitivity"),
+    ("With the Tones open the octave carries a fifth above it 4.4 dB "
+     "quieter, as the pedal's multiplication does, wherever Tracking is "
+     "set.",
+     "T2Multiplication.test_mono_every_window"),
+    ("Turning Tone 1 down thins that fifth more on high notes than on low "
+     "ones.",
+     "T6Tone.test_tone_1_is_a_two_pole_low_pass"),
+    ("At patch 0, on a mono source, every note from low E (E2) to A4 "
+     "divides cleanly, even with a strong second harmonic.",
+     "T5Range.test_the_windows_mono"),
+    ("The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.",
+     ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo")),
+    ("Below the range a low note's second harmonic clocks the divider and "
+     "it skips; above it the clock is low-passed under Sensitivity and the "
+     "octave goes silent.",
+     "T5Range.test_outside_the_window"),
+    ("Between -90 and -84.5 dBFS Sensitivity changes nothing: that whole "
+     "stretch is one step of the clock.",
+     "TheSurface.test_sensitivity_dead_stretch"),
+    ("It plays one note at a time: on a power chord (A2 and E3) about two "
+     "fifths of the octave is intermodulation.",
+     "TheSurface.test_one_note_at_a_time"),
+    ("A stereo source is clocked on its mid: with the right channel 45 "
+     "degrees ahead of the left, the fifth sits 3.2 dB under the octave "
+     "instead of 4.4, on both channels.",
+     ("T2Multiplication.test_stereo_45_degrees",
+      "T2Multiplication.test_in_phase_stereo_reads_as_mono")),
+    ("So near the top of the range a stereo note whose channels cancel "
+     "each other's fundamental can drop out: one stereo A4 in eight did, "
+     "at patch 0.",
+     ("T5Range.test_a_stereo_note_can_drop_out_at_the_top",
+      "T5Range.test_the_windows_stereo")),
+    ("The output can peak at 2.8 times the input (a square wave, with "
+     "Octave 2 at full), so keep the input under -9 dBFS.",
+     "TheSurface.test_the_peak_gain"),
+    ("A control that jumps makes the output step: move it in small steps "
+     "from the host if you need it smooth.",
+     "DECLARED:Octaver,E4-,P5"),
+    ("With both octaves at 0 and Direct at 1 the output is the input, byte "
+     "for byte.",
+     "TheSurface.test_the_wire_is_the_input"),
+    ("There is no latency.", "TheSurface.test_no_latency"),
+    ("`tail_samples` covers the all-pass and the two Tone filters ringing "
+     "down.",
+     "TheSurface.test_the_tail_is_bounded"),
+    ("`reset()` clears the filters and the dividers and returns to patch "
+     "0.",
+     "TheSurface.test_reset_renders_as_fresh"),
+    ("The class never reads the host's tempo.",
+     "TheSurface.test_never_reads_the_tempo"),
+)
+
+
+if __name__ == "__main__" and unittest is not None:
+    unittest.main()

From 029b317fbb6a0d98427bd33faf901771b7cbbacf Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:19:16 -0500
Subject: [PATCH 21/76] AirSpace: declare the 22.05 kHz lifecycle cells and tie
 the family sentence

At 22.05 kHz a macro move that reaches the tape's loop or the chamber
leaves the tank off the uninterrupted control for good (P4, as Reverb's),
and Mix, Top Cut and patch moves step the output (P5, the family's
disclosed limit). The docstring's sentence on jumping controls now names
those declared rows.
---
 tests/support/lifecycle.py             | 6 +++++-
 tests/test_cpython_effects_airspace.py | 3 +++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 34d1428..272dba7 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -247,11 +247,15 @@
     # instance does (the class's TheReset tests); it is the control that
     # never was reset.
     ("AirSpace", "E1-", "P4"): "reset() empties the chamber and restarts its modulation, so it never re-converges with the uninterrupted control (Reverb's E1 P4)",
-    ("AirSpace", "E4-m10=", "P4"): "Mix to 0 and back empties the chamber and restarts its modulation (as E1)",
+    ("AirSpace", "E4-", "P4"): "a move that reaches the tape's loop or the chamber's, or Mix to 0 and back, leaves the tank off the control's for good (Reverb's E4 P4)",
     ("AirSpace", "E5-", "P4"): "Mix to 0 and back empties the chamber and restarts its modulation (as E1)",
     ("AirSpace", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the chamber (as E1)",
     ("AirSpace", "E6-", "P4"): "a patch move reaches the chamber's loop and leaves its tank off the control's for good (Reverb's E6 P4)",
     ("AirSpace", "E11-", "P4"): "moves that reach the chamber's loop or empty it leave its tank off the control's for good (Reverb's E11 P4)",
+    ("AirSpace", "E4-m6=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Top Cut)",
+    ("AirSpace", "E5-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
+    ("AirSpace", "E6-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (a patch change)",
+    ("AirSpace", "E9-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
 }
 
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index fc0603b..7e06cb9 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -929,6 +929,9 @@ def test_a_patch_change_glides(self):
       "TheSurface.test_patch_0_is_the_defaults_on_the_grid",
       "TheSurface.test_a_fresh_instance_reads_patch_0_and_plays_the_"
       "defaults")),
+    ("A control that jumps makes the output step: move it in small steps "
+     "from the host if you need it smooth.",
+     ("DECLARED:AirSpace,E5-,P5", "DECLARED:AirSpace,E4-m6=,P5")),
     ("Time is the exception: it glides.",
      "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide"),
     ("A patch that changes Time glides there too, and the repeats bend "

From 54d204057d63104200d5763ef5146622934ede95 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:27:21 -0500
Subject: [PATCH 22/76] AirSpace: re-play the voices on a return from Mix 0
 where get_buffer is compiled out

On a board's own audiocore the constructor's wiring primes the source's
first block into the voices, and a Mix 0 before the first pull would play
that block stale on the return. The return now re-plays the voices there;
mid-stream it renders byte for byte what the quiet wiring renders. Tested
with get_buffer hidden from the class and _component, with the replay
taken out as the red control.
---
 lib/audioeffects/rebuilt/airspace.py   | 18 +++++-
 tests/test_cpython_effects_airspace.py | 81 ++++++++++++++++++++++++++
 2 files changed, 97 insertions(+), 2 deletions(-)

diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
index f9940fb..b76bf1f 100644
--- a/lib/audioeffects/rebuilt/airspace.py
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -439,10 +439,24 @@ def _route(self):
         self._levels()
         if not self._wired:
             self._wire()
-        else:
-            self._rejoin()
+        elif self._rejoin() and getattr(audiocore, "get_buffer", None) is None:
+            self._replay()
         self._output = self._tail
 
+    def _replay(self):
+        """Play the voices again on a return from Mix 0 where
+        `audiocore.get_buffer` is compiled out (a board's own audiocore).
+
+        There the constructor's wiring primes the source's first block into
+        the voices, and a Mix 0 before the first pull leaves that block
+        held while the bypass plays on; without this, the return would play
+        it stale. Mid-stream no voice holds a block, and a re-play primes
+        the source's next block, which the next pull plays on time. Where
+        `get_buffer` exists the wiring is quiet and nothing is held."""
+        voices = self._mixer.voice
+        voices[0].play(self._split.tap(0))
+        voices[1].play(self._wet_source())
+
     def _wire(self):
         """Play the voices, the first time Mix is above 0.
 
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index 7e06cb9..2030560 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -868,6 +868,87 @@ def test_a_patch_change_glides(self):
         self.assertGreaterEqual(db_ratio(powers[0], powers[1]), 40.0)
 
 
+class _NoGetBuffer:
+    """`audiocore` as a board's own build has it: no `get_buffer`."""
+
+    def __init__(self, module):
+        self._module = module
+
+    def __getattr__(self, name):
+        if name == "get_buffer":
+            raise AttributeError(name)
+        return getattr(self._module, name)
+
+
+class HiddenGetBuffer:
+    """Hide `audiocore.get_buffer` from the class and `_component` (the
+    renders here keep their own reference to it)."""
+
+    def __enter__(self):
+        from audioeffects import _component
+        self._modules = (sys.modules[AirSpace.__module__], _component)
+        for module in self._modules:
+            module.audiocore = _NoGetBuffer(audiocore)
+        return self
+
+    def __exit__(self, *exc):
+        for module in self._modules:
+            module.audiocore = audiocore
+        return False
+
+
+def moves_render(data, rate, channels, pulls, actions, hidden):
+    if hidden:
+        with HiddenGetBuffer():
+            effect = build(AirSpace, data, rate, channels)
+            out = render(effect, pulls * BLOCK, actions)
+    else:
+        effect = build(AirSpace, data, rate, channels)
+        out = render(effect, pulls * BLOCK, actions)
+    effect.deinit()
+    return out
+
+
+class WithoutGetBuffer(unittest.TestCase):
+    """A board's own audiocore has no `get_buffer`, so the voices prime
+    the source's first block at construction instead of a block of zeros
+    (the class's `_wire` and `_replay`)."""
+
+    def test_mix_zero_and_back_mid_stream_renders_the_same(self):
+        rate, channels = 48000, 2
+        data = lcg_noise(rate, channels, 4000.0, 11)
+        actions = {10: lambda e: e.set_macro(MIX_I, 0),
+                   14: lambda e: e.set_macro(MIX_I, 22)}
+        want = moves_render(data, rate, channels, 120, actions, False)
+        got = moves_render(data, rate, channels, 120, actions, True)
+        # The first block differs by design: without `get_buffer` the level
+        # gates cannot be opened ahead (`open_level_gates`), so the voices
+        # wait for the first zero crossing, as upstream's do.
+        skip = BLOCK * channels
+        self.assertEqual(got[skip:], want[skip:])
+
+    def test_no_stale_block_after_mix_zero_before_the_first_pull(self):
+        rate, channels = 48000, 2
+        data = burst(BLOCK, rate, channels, 8000.0, 12)
+        actions = {0: lambda e: e.set_macro(MIX_I, 0),
+                   4: lambda e: e.set_macro(MIX_I, 22)}
+        out = moves_render(data, rate, channels, 60, actions, True)
+        self.assertFalse(any(out[4 * BLOCK * channels:]))
+
+    def test_red_without_the_replay(self):
+        rate, channels = 48000, 2
+        data = burst(BLOCK, rate, channels, 8000.0, 12)
+        actions = {0: lambda e: e.set_macro(MIX_I, 0),
+                   4: lambda e: e.set_macro(MIX_I, 22)}
+        replay = AirSpace._replay
+        AirSpace._replay = lambda self: None
+        try:
+            out = moves_render(data, rate, channels, 60, actions, True)
+        finally:
+            AirSpace._replay = replay
+        self.assertTrue(any(out[4 * BLOCK * channels:]))
+
+
 # --------------------------------------------------------------------------
 # The docstring's claims, sentence by sentence (KIT.md, claims)
 

From 04dc20348e7b11243fe6439331d74d9c205c2474 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:38:53 -0500
Subject: [PATCH 23/76] DeEsser: restate the STATE plant that audiodsp#229 made
 inert; record the pin move in the changelog

---
 CHANGELOG.md                          |  2 ++
 tests/test_cpython_effects_deesser.py | 28 ++++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..82476b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -291,6 +291,8 @@ there, and are recorded in its changelog.
 
 ### Fixed
 
+- A Time brought back after a shorter one no longer plays a stray sample from before the move in MultiTapDelay and the delays built on `audiodelays.Echo`; PitchShifter, Harmonizer and Octaver start again from scratch on a reset and no longer hang on a source with nothing to give; and a host reset that reaches a Mixer inside an effect keeps the audio its voices hold. All of it is audiodsp's, at the pre-release `AUDIODSP_PIN` now names (v0.6.6rc1).
+
 - The delays, Reverb and ConvolutionReverb now ring out when their source ends, then rest at exact zero, instead of freezing the tail until the source came back; a one-shot source plays once instead of feeding them for ever. A source that comes up short part-way through a block leaves a whole block with the rest silent, and a host `reset_buffer` on ConvolutionReverb keeps the frames it holds. All of it is audiodsp's, at the commit `AUDIODSP_PIN` now names (audiocomponents#127).
 
 - **Ten effects no longer replay old audio when a control brings a bypassed
diff --git a/tests/test_cpython_effects_deesser.py b/tests/test_cpython_effects_deesser.py
index 960e156..ff92e86 100644
--- a/tests/test_cpython_effects_deesser.py
+++ b/tests/test_cpython_effects_deesser.py
@@ -1274,17 +1274,35 @@ def test_click_goes_red_when_latency_is_misreported(self):
 
     def test_state_goes_red_when_a_ring_is_left_full(self):
         """The reset fault of the same kind the dossier's V7-7 measured:
-        skip the ring flush and the class replays what the rings hold."""
+        skip the silence and the ring flush and the class replays the
+        audio it held before the reset."""
         rate = 48000
         values = probe("noise_det", rate, frames=STATE_FRAMES)
         effect, holder = build(rate=rate, values=values)
         quiet = source(silence(len(values) // 2), rate)
-        # The fault: the reset walk without the ring flush, which is what
-        # the class did before `_reset_chain` existed. 32-block pulls fill
-        # the rings; the 4 s file was leftover length.
+        # The fault: the class's reset walk without the silent sample and
+        # the ring flush, so the voices re-prime from the live source and
+        # replay it after the reset (the 3 024 LSB `_reset_chain`'s
+        # docstring measured). 32-block pulls fill the rings; the 4 s file
+        # was leftover length.
+        #
+        # Restated at audiodsp v0.6.6rc1 (30cbbf6). Up to eb2d20d this plant
+        # was the walk the class took before `_reset_chain` existed: a host
+        # reset of the Dynamics and both Mixers, and a Mixer's reset fetched
+        # a chunk into every voice from the taps, which replayed what the
+        # rings held. That refetch was the node's defect, fixed in
+        # audiodsp#229: a Mixer's host reset keeps every voice where it
+        # was, so that walk replays nothing (residual 0) and could no
+        # longer show this check failing. The class never resets a Mixer
+        # (it re-primes the voices, for CircuitPython's sake), so nothing
+        # in it changes.
         render(effect.output, 32 * 256, rate)
-        for node in (effect._duck, effect._pre, effect._out):
+        for node in (effect._lows[0], effect._lows[1], effect._highs[0],
+                     effect._highs[1], effect._duck):
             audiocore.reset_buffer(node)
+        for mixer, index, sample in effect._voices:
+            mixer.voice[index].play(sample)
+        audiocore.reset_buffer(effect._tail)
         effect._adapter.play(quiet)
         after = render(effect.output, 32 * 256, rate)
         residual = int(abs(after.data).max())

From f34b98e96f4af28f5546cafa2f9dbd7afd79981d Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:38:54 -0500
Subject: [PATCH 24/76] Rack reset returns every pedal to exactly how the rack
 built it

A rack's reset used to run each pedal's own reset, which loads patch 0,
then put the rack's settings back over the top. A pedal built at Mix 0
re-armed its voices inside that patch 0 and pulled a block of the source,
so the rack's output skipped 256 frames and the held block played stale
when Mix came back up (Compressor, Saturation, Bitcrusher, DynamicEQ,
Exciter, Overdrive). The put-back also lost the exact constructor values a
delay keeps beside its knobs, so DigitalDelay(glide_ms=10) glided for
815 ms on its next Time move.

Component gains a small private hook: _record() takes an instance's
positions, patch index and the values its class names in _KEPT, and
_restore() puts them back with _seeding set. Component.reset() reloads a
record a parent hands in through _reset_to in place of patch 0, so a
child's own reset clears and restores in one step and never passes
through patch 0. With no record handed in, every class's reset is what it
was: 550 renders of every class at every patch, reset mid-stream, are
byte-identical before and after.

The five delays that keep exact values (DigitalDelay, TapeDelay,
AnalogDelay, SlapbackDelay, PingPongDelay) name them in _KEPT. A refused
patch= now releases every pedal the rack built.
---
 lib/audioeffects/_component.py            |  51 +++-
 lib/audioeffects/rebuilt/analogdelay.py   |   2 +
 lib/audioeffects/rebuilt/digitaldelay.py  |   2 +
 lib/audioeffects/rebuilt/pingpongdelay.py |   2 +
 lib/audioeffects/rebuilt/rack.py          |  86 ++++--
 lib/audioeffects/rebuilt/slapbackdelay.py |   2 +
 lib/audioeffects/rebuilt/tapedelay.py     |   2 +
 tests/test_cpython_effects_rack.py        | 341 +++++++++++++++++++---
 8 files changed, 420 insertions(+), 68 deletions(-)

diff --git a/lib/audioeffects/_component.py b/lib/audioeffects/_component.py
index 909be61..4f61784 100644
--- a/lib/audioeffects/_component.py
+++ b/lib/audioeffects/_component.py
@@ -740,6 +740,11 @@ def __init__(self, source, *options, **keywords):
         #: `Saturation` and `Overdrive` each grew a private flag for the
         #: same hazard; this is the one every class can read.
         self._constructing = True
+        #: True while a class seeds its knobs from its constructor's
+        #: arguments (the class sets it in `_build`) or `_restore` puts them
+        #: back: a class that keeps an exact constructor value beside a knob
+        #: (`_KEPT`) keeps it through a knob applied while this is set.
+        self._seeding = False
 
         try:
             self._build(*options, **keywords)
@@ -1048,6 +1053,40 @@ def _apply_positions(self, positions, patch_index):
             self._apply_macro(macro, positions[macro])
         self._patch_index = patch_index
 
+    #: Attributes beyond the macros and the patch index that a class's
+    #: constructor leaves and a put-back must restore with them: an exact
+    #: constructor value kept beside its knob (`_glide_exact`). A class that
+    #: keeps one names it here; `_record` and `_restore` carry it.
+    _KEPT = ()
+
+    #: What `reset()` reloads in place of patch 0: `None`, or a `_record()`
+    #: a parent hands in for the length of one reset, so a child it built
+    #: comes back as built in one step, never passing through patch 0.
+    _reset_to = None
+
+    def _record(self):
+        """This instance's settings as they stand, for `_restore`: the
+        positions, the patch index and the `_KEPT` values."""
+        return (list(self._macros), self._patch_index,
+                tuple(getattr(self, name) for name in type(self)._KEPT))
+
+    def _restore(self, record):
+        """Put back what `_record` returned, through `_apply_positions`.
+
+        The kept values go back first and the positions are applied with
+        `_seeding` set, the flag a class's constructor holds while it seeds
+        the knobs: a class that drops an exact value when its knob moves
+        keeps it while seeding, so the values and the knobs land together.
+        """
+        positions, patch_index, kept = record
+        for name, value in zip(type(self)._KEPT, kept):
+            setattr(self, name, value)
+        self._seeding = True
+        try:
+            self._apply_positions(list(positions), patch_index)
+        finally:
+            self._seeding = False
+
     def pitch_bend(self, value, channel=0, sample_position=0):
         self._check_live()
         _pitch_bend(value)
@@ -1109,7 +1148,17 @@ def reset(self):
         # Everything is clear now, so nothing is stranded: patch 0 coming
         # back off a bypass is the reset's own re-arm, not a second clear.
         self._stranded = False
-        self.program_change(0)
+        if self._reset_to is None:
+            self.program_change(0)
+        else:
+            # A parent's reset: straight back to the settings it built this
+            # with. Loading patch 0 on the way could re-arm a graph those
+            # settings route around, and pull the source to do it. Those
+            # settings may route around the graph, but it has not played
+            # since it was cleared, so it is no more stranded than a graph
+            # `_build` routes around.
+            self._restore(self._reset_to)
+            self._stranded = False
 
     def deinit(self):
         """Release every node this class built, tail first. Idempotent, and
diff --git a/lib/audioeffects/rebuilt/analogdelay.py b/lib/audioeffects/rebuilt/analogdelay.py
index 0581cba..7214d73 100644
--- a/lib/audioeffects/rebuilt/analogdelay.py
+++ b/lib/audioeffects/rebuilt/analogdelay.py
@@ -216,6 +216,8 @@ class AnalogDelay(_component.Component):
     VERSION = '0.1.0'
 
     TIER = _component.AUDIODSP
+    #: The exact constructor values a rack's reset puts back with the knobs.
+    _KEPT = ('_time_exact',)
     REQUIRES = ("audioecho",)
 
     CAPABILITIES = ("tempo_sync",)
diff --git a/lib/audioeffects/rebuilt/digitaldelay.py b/lib/audioeffects/rebuilt/digitaldelay.py
index f44b2f1..e1a4fff 100644
--- a/lib/audioeffects/rebuilt/digitaldelay.py
+++ b/lib/audioeffects/rebuilt/digitaldelay.py
@@ -311,6 +311,8 @@ class DigitalDelay(_component.Component):
     VERSION = '0.1.0'
 
     TIER = _component.AUDIODSP
+    #: The exact constructor values a rack's reset puts back with the knobs.
+    _KEPT = ('_glide_exact',)
     REQUIRES = ("audioecho",)
 
     CAPABILITIES = ("tempo_sync",)
diff --git a/lib/audioeffects/rebuilt/pingpongdelay.py b/lib/audioeffects/rebuilt/pingpongdelay.py
index 7f9d42b..6c501f3 100644
--- a/lib/audioeffects/rebuilt/pingpongdelay.py
+++ b/lib/audioeffects/rebuilt/pingpongdelay.py
@@ -167,6 +167,8 @@ class PingPongDelay(_component.Component):
     VERSION = '0.1.0'
 
     TIER = _component.AUDIODSP
+    #: The exact constructor values a rack's reset puts back with the knobs.
+    _KEPT = ('_time_exact',)
     REQUIRES = ("audioecho",)
 
     CAPABILITIES = ("tempo_sync",)
diff --git a/lib/audioeffects/rebuilt/rack.py b/lib/audioeffects/rebuilt/rack.py
index 1a34a26..a3fb892 100644
--- a/lib/audioeffects/rebuilt/rack.py
+++ b/lib/audioeffects/rebuilt/rack.py
@@ -63,8 +63,8 @@ class in place of a name. `("Rack", {"chain": ...})` nests a rack.
     needs whatever modules its pedals need.
 
     `deinit()` releases every pedal, nested racks included, and never your
-    source. If an entry fails to build, the pedals built before it are
-    released before the error reaches you.
+    source. If an entry fails to build, or `patch` is refused, the pedals
+    already built are released before the error reaches you.
     """
 
     NAME = 'Rack'
@@ -88,28 +88,30 @@ def _build(self, chain=(), patch=None):
                 child = self._child(name, tail, options)
                 built.append(child)
                 tail = child.output
+            self._effects = tuple(built)
+            # What patch 0 and reset() restore: each child's settings as the
+            # rack built it (`_record`).
+            self._built = tuple(_record(child) for child in built)
+            capabilities = []
+            for child in built:
+                for capability in child.capabilities:
+                    if capability not in capabilities:
+                        capabilities.append(capability)
+            self._capabilities = tuple(capabilities)
+            # No port of its own: the rack's output IS the last child's
+            # output (its port), and an empty rack's IS the source. Set
+            # directly, around the `_output` property, which would wrap it
+            # in a new port.
+            self._port = tail
+            # Last, and inside the release: a `patch` the rack refuses
+            # raises here, with every child built.
+            self._init_macros((), patch)
         except BaseException:
             # The constructor never returns, so nobody else can release
             # what was built: do it here, tail first, and re-raise.
             for child in reversed(built):
                 child.deinit()
             raise
-        self._effects = tuple(built)
-        # What patch 0 restores: each child's positions, whole, and its
-        # patch index, as the rack built it.
-        self._built = tuple((list(child._macros), child._patch_index)
-                            for child in built)
-        capabilities = []
-        for child in built:
-            for capability in child.capabilities:
-                if capability not in capabilities:
-                    capabilities.append(capability)
-        self._capabilities = tuple(capabilities)
-        # No port of its own: the rack's output IS the last child's output
-        # (its port), and an empty rack's IS the source. Set directly,
-        # around the `_output` property, which would wrap it in a new port.
-        self._port = tail
-        self._init_macros((), patch)
 
     def _child(self, name, source, options):
         """One chain entry built around `source`, with the rack's transport
@@ -160,11 +162,11 @@ def capabilities(self):
     # -- the surface ----------------------------------------------------
 
     def _apply_positions(self, positions, patch_index):
-        """Patch 0: every child back to the positions and patch index the
-        rack built it with. A nested rack restores inside itself."""
+        """Patch 0: every child back to the settings the rack built it
+        with. A nested rack restores inside itself."""
         _component.Component._apply_positions(self, positions, patch_index)
-        for child, (macros, index) in zip(self._effects, self._built):
-            child._apply_positions(list(macros), index)
+        for child, record in zip(self._effects, self._built):
+            _restore(child, record)
 
     def transport_changed(self):
         self._check_live()
@@ -172,12 +174,26 @@ def transport_changed(self):
             child.transport_changed()
 
     def reset(self):
-        """Each child's own reset, tail first, then patch 0. The borrowed
-        source is never named."""
+        """Each child's own reset, tail first, reloading the settings the
+        rack built it with in place of its patch 0, so no child passes
+        through a patch the rack never gave it: one built at Mix 0 would
+        re-arm there and pull a block of the source. A nested rack's reset
+        does the same inside itself. The borrowed source is never named."""
         self._check_live()
-        for child in reversed(self._effects):
-            child.reset()
-        _component.Component.reset(self)
+        for position in range(len(self._effects) - 1, -1, -1):
+            child = self._effects[position]
+            record = self._built[position]
+            if isinstance(child, _component.Component):
+                child._reset_to = record
+                try:
+                    child.reset()
+                finally:
+                    child._reset_to = None
+            else:
+                child.reset()
+                _restore(child, record)
+        self._stranded = False
+        self._patch_index = 0
 
     def deinit(self):
         """Every child's own deinit, tail first. The port is never released
@@ -190,6 +206,22 @@ def deinit(self):
         self._deinited = True
 
 
+def _record(child):
+    """What puts `child` back as it stands: its `_record()`, or, for a
+    child on the older `_core` base, its positions and patch index."""
+    if isinstance(child, _component.Component):
+        return child._record()
+    return (list(child._macros), child._patch_index)
+
+
+def _restore(child, record):
+    """Put `child` back to `record`, without clearing anything."""
+    if isinstance(child, _component.Component):
+        child._restore(record)
+    else:
+        child._apply_positions(list(record[0]), record[1])
+
+
 def _entry(entry):
     """(name or class, options dict) for one chain entry."""
     if isinstance(entry, (str, type)):
diff --git a/lib/audioeffects/rebuilt/slapbackdelay.py b/lib/audioeffects/rebuilt/slapbackdelay.py
index 015a208..c479ef8 100644
--- a/lib/audioeffects/rebuilt/slapbackdelay.py
+++ b/lib/audioeffects/rebuilt/slapbackdelay.py
@@ -173,6 +173,8 @@ class SlapbackDelay(_component.Component):
     VERSION = '0.1.0'
 
     TIER = _component.AUDIODSP
+    #: The exact constructor values a rack's reset puts back with the knobs.
+    _KEPT = ('_time_exact',)
     REQUIRES = ("audioecho",)
 
     CAPABILITIES = ()
diff --git a/lib/audioeffects/rebuilt/tapedelay.py b/lib/audioeffects/rebuilt/tapedelay.py
index 41463a7..6e2aa62 100644
--- a/lib/audioeffects/rebuilt/tapedelay.py
+++ b/lib/audioeffects/rebuilt/tapedelay.py
@@ -343,6 +343,8 @@ class TapeDelay(_component.Component):
     VERSION = '0.1.0'
 
     TIER = _component.AUDIODSP
+    #: The exact constructor values a rack's reset puts back with the knobs.
+    _KEPT = ('_glide_exact', '_time_exact')
     REQUIRES = ("audioecho",)
 
     CAPABILITIES = ("tempo_sync",)
diff --git a/tests/test_cpython_effects_rack.py b/tests/test_cpython_effects_rack.py
index 0a76c3a..585f2c0 100644
--- a/tests/test_cpython_effects_rack.py
+++ b/tests/test_cpython_effects_rack.py
@@ -417,24 +417,32 @@ def reset(self):
 
 
 class PublicRestoreRack(Rack):
-    """T4: patch 0 restores through the public `set_macro`."""
+    """T4: patch 0, and the put-back after each child's own reset, restore
+    through the public `set_macro`."""
 
     def _apply_positions(self, positions, patch_index):
         _component.Component._apply_positions(self, positions, patch_index)
-        for child, (macros, index) in zip(self._effects, self._built):
+        for child, record in zip(self._effects, self._built):
+            macros = record[0]
             for macro in range(len(macros)):
                 child.set_macro(macro, _component.midi_of_position(
                     child._mode(macro), macros[macro]))
 
+    def reset(self):
+        self._check_live()
+        for child in reversed(self._effects):
+            child.reset()
+        _component.Component.reset(self)
+
 
 class SkipNestedRack(Rack):
     """T4: patch 0 leaves nested racks' children alone."""
 
     def _apply_positions(self, positions, patch_index):
         _component.Component._apply_positions(self, positions, patch_index)
-        for child, (macros, index) in zip(self._effects, self._built):
+        for child, record in zip(self._effects, self._built):
             if not isinstance(child, Rack):
-                child._apply_positions(list(macros), index)
+                child._apply_positions(list(record[0]), record[1])
 
 
 class NoRestoreRack(Rack):
@@ -520,6 +528,39 @@ def capabilities(self):
         return type(self).CAPABILITIES
 
 
+class PutBackRack(Rack):
+    """T4: each child's own reset, which loads its patch 0, then the
+    positions and patch index the rack built it with put back over the top
+    (the class's first shape)."""
+
+    def reset(self):
+        self._check_live()
+        for child in reversed(self._effects):
+            child.reset()
+        for child, record in zip(self._effects, self._built):
+            child._apply_positions(list(record[0]), record[1])
+        self._patch_index = 0
+
+
+class PositionsOnlyRack(Rack):
+    """T4: the restore puts back positions and patch index alone, not the
+    exact constructor values a child keeps beside them."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, chain, patch)
+        self._built = tuple((record[0], record[1], ())
+                            for record in self._built)
+
+
+class LeakyPatchRack(Rack):
+    """T5: a refused `patch=` raises with the built pedals unreleased (the
+    class's first shape: the patch is applied outside the release)."""
+
+    def _build(self, chain=(), patch=None):
+        Rack._build(self, chain)
+        self._init_macros((), patch)
+
+
 def _recording_lowpass():
     base = audioeffects.LowPass
 
@@ -632,7 +673,7 @@ def t3(cls, rate, channels):
     made, _ = hand(Source(material(1, channels, 4096), rate, channels),
                    rate, K)
     ours = leaves(rack)
-    as_built = [(list(leaf._macros), leaf.patch_index) for leaf in made]
+    as_built = [leaf._record() for leaf in made]
     try:
         if len(ours) != 4 or rack.latency_samples == 0:
             return ["built %d leaves, latency %d" % (
@@ -656,13 +697,13 @@ def read(when):
                 ours[leaf].set_macro(macro, value)
                 made[leaf].set_macro(macro, value)
                 read("leaf %d macro %d at %r" % (leaf, macro, value))
-        # The same reset by hand: each leaf's own, tail first, then each
-        # back to the positions it was built with.
+        # The same reset by hand: each leaf's own, tail first, reloading
+        # the settings it was built with in place of its patch 0.
         rack.reset()
-        for leaf in reversed(made):
-            leaf.reset()
-        for leaf, (macros, index) in zip(made, as_built):
-            leaf._apply_positions(list(macros), index)
+        for position in range(len(made) - 1, -1, -1):
+            made[position]._reset_to = as_built[position]
+            made[position].reset()
+            made[position]._reset_to = None
         read("reset")
         if len(set(s[0] for s in seen)) < 3 or \
                 len(set(s[1] for s in seen)) < 2:
@@ -892,6 +933,164 @@ def t6(cls, rate, channels=2):
     return wrong
 
 
+#: Pedals that, built at Mix 0, re-arm their voices when their own reset
+#: loads patch 0 (Mix on), which pulls a block of the source.
+MIX0 = ("Compressor", "Saturation", "Bitcrusher", "DynamicEQ", "Exciter",
+        "Overdrive")
+
+#: Pedals that keep an exact constructor value beside its knob, each built
+#: off the grid, with the knobs moved before the reset and Time after it.
+EXACT = (("DigitalDelay", {"time_ms": 300.0, "glide_ms": 10.0, "mix": 1.0,
+                           "feedback": 0.0}),
+         ("TapeDelay", {"time_ms": 97.3, "glide_ms": 10.0, "mix": 1.0,
+                        "feedback": 0.0}),
+         ("AnalogDelay", {"time_ms": 97.3, "mix": 1.0, "feedback": 0.0}),
+         ("SlapbackDelay", {"time_ms": 97.3}),
+         ("PingPongDelay", {"time_ms": 97.3, "mix": 1.0, "feedback": 0.0}))
+
+
+#: The exact constructor values those pedals keep.
+KEPT = ("_time_exact", "_glide_exact")
+
+
+def _feed(values, rate, channels):
+    """A native-safe source: the lifecycle matrix's Feed, whose port can be
+    pointed at fresh material without the rack seeing a rewind."""
+    import lifecycle
+    return lifecycle.Feed(values, rate, channels, "256", loop=False)
+
+
+def _against_fresh(cls, rate, channels, chain, values, run, before=None):
+    """[] if a `cls` rack fed `values` from just before a mid-stream reset
+    renders what a freshly built `Rack` does under `run(rack)`; else what
+    differed.
+    `before(rack)` moves knobs ahead of the reset."""
+    feed = _feed(values, rate, channels)
+    fresh = Rack.create(feed.port, rate, chain=chain)
+    try:
+        want = run(fresh)
+    finally:
+        fresh.deinit()
+    other = array("h", values)
+    for i in range(len(other)):
+        other[i] = -other[i] // 2
+    feed = _feed(other, rate, channels)
+    rack = cls.create(feed.port, rate, chain=chain)
+    try:
+        if before is not None:
+            before(rack)
+        pull(rack.output, 3000, channels)
+        # The new material goes in ahead of the reset, so a block the reset
+        # pulls is missing from what plays after it.
+        feed.point(_feed(values, rate, channels).mat)
+        rack.reset()
+        got = run(rack)
+    finally:
+        rack.deinit()
+    if got == want:
+        return []
+    a, b = samples(got), samples(want)
+    first = 0
+    while a[first] == b[first]:
+        first += 1
+    return ["after reset %08x, fresh %08x, first difference at frame %d"
+            % (fnv(got), fnv(want), first // channels)]
+
+
+def t4_mix0(cls, rate, channels, names=MIX0):
+    """A pedal built at Mix 0 comes back from the rack's reset as built: on
+    time, and through a later Mix move back up."""
+    wrong = []
+    values = noise_det(16384, 5, channels)
+    for name in names:
+        mix = list(getattr(audioeffects, name).MACRO_LABELS).index("Mix")
+
+        def run(rack):
+            head = pull(rack.output, 4096, channels)
+            rack.effects[0].set_macro(mix, 100)
+            return head + pull(rack.output, 8192, channels)
+
+        for line in _against_fresh(cls, rate, channels,
+                                   ((name, {"mix": 0.0}),), values, run):
+            wrong.append("%s at Mix 0: %s" % (name, line))
+    return wrong
+
+
+def t4_exact(cls, rate, channels, cases=EXACT):
+    """A pedal's exact constructor values come back from the rack's reset:
+    a host's read-back of Time and a Time move after it play what the
+    freshly built rack's do."""
+    wrong = []
+    frames = 36000
+    values = clicks(frames, channels, range(512, frames, 4800))
+    for name, options in cases:
+        labels = list(getattr(audioeffects, name).MACRO_LABELS)
+
+        def before(rack):
+            pedal = rack.effects[0]
+            pedal.set_macro(0, 90)
+            if "Glide" in labels:
+                pedal.set_macro(labels.index("Glide"), 30)
+
+        def run(rack):
+            pedal = rack.effects[0]
+            # A host that reads Time back and writes it keeps the exact one.
+            pedal.set_macro(0, pedal.get_macro(0))
+            head = pull(rack.output, 12000, channels)
+            pedal.set_macro(0, 60)
+            return head + pull(rack.output, frames - 12000, channels)
+
+        for line in _against_fresh(cls, rate, channels,
+                                   ((name, dict(options)),), values, run,
+                                   before):
+            wrong.append("%s %r: %s" % (name, options, line))
+        # The values themselves, which a render at these settings may not
+        # reach (an exact Time a whole frame away from its knob's).
+        fresh = Rack.create(_feed(values, rate, channels).port, rate,
+                            chain=((name, dict(options)),))
+        rack = cls.create(_feed(values, rate, channels).port, rate,
+                          chain=((name, dict(options)),))
+        try:
+            before(rack)
+            rack.reset()
+            for kept in KEPT:
+                want = getattr(fresh.effects[0], kept, None)
+                got = getattr(rack.effects[0], kept, None)
+                if got != want:
+                    wrong.append("%s: %s reads %r after reset, %r as built"
+                                 % (name, kept, got, want))
+        finally:
+            rack.deinit()
+            fresh.deinit()
+    return wrong
+
+
+def t5_patch(cls):
+    """A `patch=` the rack refuses releases every pedal it had built."""
+    wrong = []
+    data = material(1, 2, 4096)
+    for patch in (-1, "x", True):
+        recording = _recording_lowpass()
+        try:
+            cls(_feed(data, 48000, 2).port,
+                chain=(recording, ("Rack", {"chain": (recording,)})),
+                patch=patch)
+            wrong.append("patch=%r built" % (patch,))
+            continue
+        except ValueError:
+            pass
+        if len(recording.built) != 2:
+            wrong.append("patch=%r: %d pedals built" % (
+                patch, len(recording.built)))
+            continue
+        for built in recording.built:
+            live = [n for n in built if not is_released(n)]
+            if not built or live:
+                wrong.append("patch=%r: a LowPass keeps %d of %d nodes live"
+                             % (patch, len(live), len(built)))
+    return wrong
+
+
 # --------------------------------------------------------------------------
 # The tests
 
@@ -1050,6 +1249,28 @@ def test_an_off_grid_child_comes_back_as_built(self):
             self.assertEqual(t4(Rack, rate, 2, (1, 2), chains=("R",)),
                              [], rate)
 
+    def test_a_mix0_pedal_comes_back_as_built(self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            self.assertEqual(t4_mix0(Rack, rate, channels), [],
+                             (rate, channels))
+
+    def test_exact_constructor_values_come_back(self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            self.assertEqual(t4_exact(Rack, rate, channels), [],
+                             (rate, channels))
+
+    def test_reset_as_built_faults_are_red(self):
+        self.assertNotEqual(t4_mix0(PutBackRack, 48000, 2), [])
+        for plant in (PutBackRack, PositionsOnlyRack):
+            self.assertNotEqual(t4_exact(plant, 48000, 2), [],
+                                plant.__name__)
+
+    def test_reset_as_built_micropython(self):
+        _native(self, "micropython", "T4")
+
+    def test_reset_as_built_circuitpython(self):
+        _native(self, "circuitpython", "T4")
+
     def test_a_host_reset_clears_the_last_pedal_only(self):
         # A delay into a filter: the host's reset_buffer on the output
         # clears the filter and leaves the delay's repeats playing.
@@ -1089,32 +1310,15 @@ def test_t5_faults_are_red(self):
                       LeakyBuildRack):
             self.assertNotEqual(t5(plant), [], plant.__name__)
 
-    def _native(self, family):
-        import subprocess
-        import tempfile
-        binaries, root = _native_binaries()
-        binary = binaries[family]
-        if binary is None:
-            self.skipTest("no %s binary: set LIFECYCLE_%s"
-                          % (family, family.upper()))
-        with tempfile.TemporaryDirectory() as scratch:
-            env = dict(os.environ, MICROPYPATH="lib:tests/support",
-                       GCOV_PREFIX=scratch)
-            done = subprocess.run(
-                [binary, "-X", "heapsize=256M",
-                 "tests/test_cpython_effects_rack.py"],
-                capture_output=True, text=True, cwd=root, env=env)
-        lines = [line for line in done.stdout.splitlines()
-                 if not line.startswith("T5|nodes|")]
-        self.assertEqual(lines, ["T5|Rack|ok"] + [
-            "T5|%s|red" % plant.__name__ for plant in NATIVE_PLANTS]
-            + ["DONE"], done.stdout[-2000:] + done.stderr[-2000:])
+    def test_a_refused_patch_releases_every_pedal(self):
+        self.assertEqual(t5_patch(Rack), [])
+        self.assertNotEqual(t5_patch(LeakyPatchRack), [])
 
     def test_deinit_releases_every_pedal_micropython(self):
-        self._native("micropython")
+        _native(self, "micropython", "T5")
 
     def test_deinit_releases_every_pedal_circuitpython(self):
-        self._native("circuitpython")
+        _native(self, "circuitpython", "T5")
 
 class TestTempo(TestCase):
     """T6. A tempo-synced pedal in the rack follows the song's tempo,
@@ -1180,6 +1384,41 @@ def test_the_class_is_stock_tier(self):
 NATIVE_PLANTS = (LastOnlyDeinitRack, OutputNodeDeinitRack, LeakyBuildRack)
 
 
+def _native_lines(part):
+    """What `_native_main(part)` prints when every check holds."""
+    if part == "T5":
+        return (["T5|Rack|ok"]
+                + ["T5|%s|red" % plant.__name__ for plant in NATIVE_PLANTS]
+                + ["T5|patch|Rack|ok", "T5|patch|LeakyPatchRack|red",
+                   "DONE"])
+    return ["T4|mix0|Rack|ok", "T4|mix0|PutBackRack|red",
+            "T4|exact|Rack|ok", "T4|exact|PutBackRack|red",
+            "T4|exact|PositionsOnlyRack|red", "DONE"]
+
+
+def _native(case, family, part):
+    """Run `_native_main(part)` on a native interpreter and hold its lines
+    to `_native_lines(part)`."""
+    import subprocess
+    import tempfile
+    binaries, root = _native_binaries()
+    binary = binaries[family]
+    if binary is None:
+        case.skipTest("no %s binary: set LIFECYCLE_%s"
+                      % (family, family.upper()))
+    with tempfile.TemporaryDirectory() as scratch:
+        env = dict(os.environ, MICROPYPATH="lib:tests/support",
+                   GCOV_PREFIX=scratch)
+        done = subprocess.run(
+            [binary, "-X", "heapsize=256M",
+             "tests/test_cpython_effects_rack.py", part],
+            capture_output=True, text=True, cwd=root, env=env)
+    lines = [line for line in done.stdout.splitlines()
+             if not line.startswith("T5|nodes|")]
+    case.assertEqual(lines, _native_lines(part),
+                     done.stdout[-2000:] + done.stderr[-2000:])
+
+
 #: Every claim sentence of the class docstring, word for word, and the
 #: tests that hold it.
 CLAIMS = (
@@ -1210,7 +1449,9 @@ def test_the_class_is_stock_tier(self):
      "the pedals in chain order.", "test_effects_is_the_chain_in_order"),
     ("`reset()` clears every pedal and puts each back to the settings the "
      "rack built it with, undoing knob moves made since.",
-     "test_reset_puts_every_pedal_back"),
+     ("test_reset_puts_every_pedal_back",
+      "test_a_mix0_pedal_comes_back_as_built",
+      "test_exact_constructor_values_come_back")),
     ("`program_change(0)` does the putting back alone, without clearing "
      "anything.", "test_reset_puts_every_pedal_back"),
     ("A host's `audiocore.reset_buffer(rack.output)` clears the last pedal "
@@ -1231,19 +1472,38 @@ def test_the_class_is_stock_tier(self):
     ("`deinit()` releases every pedal, nested racks included, and never "
      "your source.", ("test_deinit_releases_every_pedal",
                       "test_an_empty_rack_is_a_patch_cable")),
-    ("If an entry fails to build, the pedals built before it are released "
-     "before the error reaches you.", "test_deinit_releases_every_pedal"),
+    ("If an entry fails to build, or `patch` is refused, the pedals already "
+     "built are released before the error reaches you.",
+     ("test_deinit_releases_every_pedal",
+      "test_a_refused_patch_releases_every_pedal")),
 )
 
 
-def _native_main():
-    """T5 on this interpreter by itself: the clean class, then each plant,
-    which must be red."""
+def _native_main(part="T5"):
+    """T5 (or T4's reset-as-built checks) on this interpreter by itself:
+    the clean class, then each plant, which must be red."""
+    if part == "T4":
+        for label, check, plants in (
+                ("mix0", t4_mix0, (PutBackRack,)),
+                ("exact", t4_exact, (PutBackRack, PositionsOnlyRack))):
+            wrong = check(Rack, 48000, 2)
+            print("T4|%s|Rack|%s" % (label, "ok" if not wrong
+                                     else "RED(%s)" % wrong))
+            for plant in plants:
+                print("T4|%s|%s|%s" % (label, plant.__name__,
+                                       "red" if check(plant, 48000, 2)
+                                       else "GREEN"))
+        print("DONE")
+        return
     wrong = t5(Rack)
     print("T5|Rack|%s" % ("ok" if not wrong else "RED(%s)" % wrong))
     print("T5|nodes|%r|no deinit|%s" % (COUNTED, sorted(NO_DEINIT)))
     for plant in NATIVE_PLANTS:
         print("T5|%s|%s" % (plant.__name__, "red" if t5(plant) else "GREEN"))
+    wrong = t5_patch(Rack)
+    print("T5|patch|Rack|%s" % ("ok" if not wrong else "RED(%s)" % wrong))
+    print("T5|patch|LeakyPatchRack|%s" % (
+        "red" if t5_patch(LeakyPatchRack) else "GREEN"))
     print("DONE")
 
 
@@ -1253,6 +1513,7 @@ def _native_main():
         # the module a planted class is defined in.
         sys.path.insert(0, "tests")
         import test_cpython_effects_rack
-        test_cpython_effects_rack._native_main()
+        test_cpython_effects_rack._native_main(
+            sys.argv[1] if len(sys.argv) > 1 else "T5")
     else:
         unittest.main()

From 8d6d77123a59f60f4c70c06f32c12246653bb558 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:53:51 -0500
Subject: [PATCH 25/76] Harmonizer: three pitch shifters at fixed intervals
 under the dry, its six traits and planted faults

---
 CHANGELOG.md                             |    8 +
 lib/audioeffects/rebuilt/harmonizer.py   |  509 ++++++++
 tests/support/kit_common.py              |    7 +
 tests/support/lifecycle.py               |   37 +
 tests/test_cpython_effects_harmonizer.py | 1352 ++++++++++++++++++++++
 5 files changed, 1913 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/harmonizer.py
 create mode 100644 tests/test_cpython_effects_harmonizer.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..8a1a231 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`Harmonizer` (rebuilt, Phase 6):** three pitch shifters at fixed
+  intervals under the dry, after three Eventide H910s played from one
+  keyboard. Each voice is its own `audiodelays.PitchShift` on its own
+  splitter tap and lands on the nearest step the shifter can play; a
+  voice at its Level's bottom step is off and its shifter is not pulled.
+  Ten controls (Pitch, Voice 1 to 3, Level 1 to 3, Detune, Spread, Mix),
+  seven patches including a lean two-voice one, and a `window_ms` option.
+  It drops the old class's `intervals=` and `level=` options.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/harmonizer.py b/lib/audioeffects/rebuilt/harmonizer.py
new file mode 100644
index 0000000..3c19ccb
--- /dev/null
+++ b/lib/audioeffects/rebuilt/harmonizer.py
@@ -0,0 +1,509 @@
+"""`Harmonizer` - a harmony of pitch-shifted voices.
+
+The player's text is the class docstring; the `CLAIMS` table in the class's
+test file ties its claim sentences to tests. How the graph works is told
+where it is built, in `Harmonizer._build`.
+"""
+
+VENDOR = "PyDevices"
+
+import math
+
+import audiocore
+
+from .. import _component
+
+try:
+    import audiodelays
+    import audiomixer
+    import audioroute
+except ImportError:                     # pragma: no cover - a stock board
+    audiodelays = audiomixer = audioroute = None
+
+
+PITCH_I = 0
+VOICE_I = (1, 2, 3)
+LEVEL_I = (4, 5, 6)
+DETUNE_I = 7
+SPREAD_I = 8
+MIX_I = 9
+
+#: Frames a mixer pull hands out, and so what every node and tap takes per
+#: pull.
+BLOCK = 256
+
+#: The Level span, in dB. MIDI 1 is -40 dB and 127 is 0 dB, 40/126 dB a
+#: step; MIDI 0 sits one step below -40 and turns the voice off.
+LEVEL_TOP_DB = 0.0
+LEVEL_FLOOR_DB = -40.0
+LEVEL_OFF_DB = LEVEL_FLOOR_DB - (LEVEL_TOP_DB - LEVEL_FLOOR_DB) / 126.0
+
+DETUNE_MAX_CENTS = 25.0
+
+WINDOW_MIN_MS = 5.0
+WINDOW_MAX_MS = 60.0
+#: 1024 frames at 48 kHz.
+WINDOW_DEFAULT_MS = 1024.0 / 48.0
+
+#: The constructor's macro defaults, which NaN falls back to (patch 0).
+DEFAULTS = (0.0, 4.0, 7.0, -12.0, -6.0, -6.0, -9.0, 0.0, 0.0, 1.0)
+
+#: The shifter reads its line at `floor(256 * 2^(semitones / 12))` 256ths
+#: of a frame per frame.
+STEPS = 256
+
+
+def ratio_step(semitones):
+    """The shifter's nearest read-rate step, in 256ths, to an interval."""
+    return int(math.floor(STEPS * 2.0 ** (semitones / 12.0) + 0.5))
+
+
+def step_semitones(step):
+    """The interval at the centre of read-rate step `step`: the node's
+    floor lands on `step` from it, with half a step to spare either way,
+    in single precision as in double."""
+    return 12.0 * math.log((step + 0.5) / STEPS) / math.log(2.0)
+
+
+def whole(value):
+    """A Pitch or Voice value as the whole semitone it plays."""
+    return int(math.floor(value + 0.5))
+
+
+def mix_gains(mix):
+    """(dry, voice) gain at Mix `mix`: the dry at unity up to 1, then
+    2 - Mix; each voice at Mix, capped at 1."""
+    mix = min(2.0, max(0.0, mix))
+    return (1.0 if mix <= 1.0 else 2.0 - mix), min(mix, 1.0)
+
+
+def level_gain(db):
+    """A Level in dB as a gain; 0 for the bottom step, which is off."""
+    if db < LEVEL_FLOOR_DB:
+        return 0.0
+    return 10.0 ** (db / 20.0)
+
+
+def _number(value, default):
+    try:
+        value = float(value)
+    except (TypeError, ValueError):
+        raise ValueError("expected a number, not %r" % (value,))
+    if value != value:
+        return default
+    return value
+
+
+class Harmonizer(_component.Component):
+    """Three pitch shifters, each a fixed interval from your note, blended
+    under the dry: the rig of three Eventide H910s played from one
+    keyboard, so one singer is three-part harmony.
+
+    **The controls.** Voice 1 to Voice 3 set each voice's interval in whole
+    semitones, an octave either way, and Pitch moves all three together, so
+    a voice reaches two octaves either way.
+    Level 1 to Level 3 run from -40 to 0 dB, and the bottom step turns the
+    voice off.
+    Detune pulls voice 1 down and voice 2 up, by up to 25 cents.
+    Spread pans voice 1 left and voice 2 right; the dry and voice 3 stay
+    in the centre.
+    Mix holds the dry at unity up to 1 while the voices rise to their
+    Levels; from 1 to 2 the dry fades, and at 2 the voices play alone.
+    Constructor values land on the nearest of each knob's 128 steps;
+    `window_ms`, 5 to 60 ms (21.33 by default), is fixed for good.
+
+    **What you hear.** Each voice is its own machine: turning one on or
+    off never changes the dry or the other voices.
+    Each voice sits on the closest pitch its shifter can make: within 3.4
+    cents of its interval from unison up, 6.8 cents down to an octave
+    below and 13.7 cents below that.
+    So Detune moves in steps of about 7 cents near unison, and voices 1
+    and 2 sit evenly apart only to within a step.
+    Detune is a steady offset, not a chorus: a voice holds its pitch.
+    Each voice glitches as it splices, more often the further it is
+    shifted and the shorter the window: at the default window a fifth up
+    splices every 43 ms, at any sample rate.
+    A voice at exact unison never splices: it is a fixed short delay, and
+    it combs with the dry.
+    A voice you turn back on starts from silence, not with a scrap of what
+    it played before.
+
+    **Limits.** It moves notes by fixed intervals and does not listen for
+    the key.
+    Each voice rounds off peaks above about -1.4 dBFS.
+    The voices add to the dry: at patch 0 an input that peaks at or below
+    13 900 (-7.4 dBFS) cannot reach full scale.
+    Patch 6 is patch 0 without the octave below, for a board that cannot
+    run three voices in time.
+    The shifter reads its line without interpolation, which you may hear
+    as grit on a shifted voice.
+    On a mono source Spread does nothing.
+    An interval move leaves each voice's splice where it was.
+    A control that jumps makes the output step: move it in small steps
+    from the host if you need it smooth.
+
+    **Wire, latency, tail.** At Mix 0 the output is the input, byte for
+    byte.
+    There is no latency: the dry is a wire, and each shifted voice trails
+    it by between the crossfade, a sixteenth of the window, and the whole
+    window.
+    `tail_samples` covers the window, the crossfade and one block, and is
+    0 at Mix 0 or with every voice off.
+    `reset()` empties the three lines, starts their splices where a new
+    instance's start, and returns to patch 0.
+    The class never reads the host's tempo.
+    """
+
+    NAME = 'Harmonizer'
+    DISPLAY_NAME = 'Harmonizer'
+    CATEGORIES = ('Pitch Shift',)
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioroute",)
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    TAIL_SAMPLES = None
+
+    #: The loudest sum over every patch and every stop is the dry at unity
+    #: and Level 3 at 0 dB over patch 0's other two voices: 3.0 times the
+    #: input, so -9.6 dBFS keeps it inside full scale.
+    INPUT_CEILING_DBFS = -9.6
+
+    MACRO_LABELS = ("Pitch", "Voice 1", "Voice 2", "Voice 3", "Level 1",
+                    "Level 2", "Level 3", "Detune", "Spread", "Mix")
+    MACRO_MODES = {0: "BIPOLAR", 1: "BIPOLAR", 2: "BIPOLAR", 3: "BIPOLAR",
+                   4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR",
+                   7: "UNIPOLAR", 8: "UNIPOLAR", 9: "UNIPOLAR"}
+    _MACRO_RANGES = (
+        (-12.0, 12.0),                      # 0  Pitch, semitones
+        (-12.0, 12.0),                      # 1  Voice 1, semitones
+        (-12.0, 12.0),                      # 2  Voice 2
+        (-12.0, 12.0),                      # 3  Voice 3
+        (LEVEL_OFF_DB, LEVEL_TOP_DB),       # 4  Level 1, dB; MIDI 0 = off
+        (LEVEL_OFF_DB, LEVEL_TOP_DB),       # 5  Level 2
+        (LEVEL_OFF_DB, LEVEL_TOP_DB),       # 6  Level 3
+        (0.0, DETUNE_MAX_CENTS),            # 7  Detune, cents
+        (0.0, 1.0),                         # 8  Spread
+        (0.0, 2.0),                         # 9  Mix; dry at unity to 1
+    )
+
+    #: `_component.macro_of` of the card's settings: +3/+4/+5/+7/+12 are
+    #: 80/85/90/101/127 and -12 is 0; -3/-6/-9/-12 dB are 118/108/99/89 and
+    #: off is 0; 14 cents is 71; Spread 0.5 and Mix 1 are 64.
+    PATCHES = {
+        0: ("Third and fifth above, octave below",
+            (64, 85, 101, 0, 108, 108, 99, 0, 0, 64)),
+        1: ("Octave below, doubled",
+            (64, 0, 0, 64, 118, 118, 0, 71, 64, 64)),
+        2: ("Wide unison",
+            (64, 64, 64, 64, 108, 108, 0, 71, 127, 64)),
+        3: ("Fourths and fifths",
+            (64, 90, 101, 127, 99, 99, 89, 0, 64, 64)),
+        4: ("Octave up and down",
+            (64, 127, 0, 64, 108, 108, 0, 0, 64, 64)),
+        5: ("Minor triad, voices alone",
+            (64, 80, 101, 64, 108, 108, 108, 0, 64, 127)),
+        6: ("Third and fifth - lean",
+            (64, 85, 101, 0, 108, 108, 0, 0, 0, 64)),
+    }
+
+    def _build(self, pitch=0.0, voice1=4.0, voice2=7.0, voice3=-12.0,
+               level1_db=-6.0, level2_db=-6.0, level3_db=-9.0,
+               detune_cents=0.0, spread=0.0, mix=1.0,
+               window_ms=WINDOW_DEFAULT_MS, patch=None):
+        grid = self._grid((pitch, voice1, voice2, voice3, level1_db,
+                           level2_db, level3_db, detune_cents, spread, mix))
+        window_ms = _number(window_ms, WINDOW_DEFAULT_MS)
+        self._window_ms = min(WINDOW_MAX_MS, max(WINDOW_MIN_MS, window_ms))
+        rate = self._sample_rate
+        channels = self._channel_count
+        self._ready = False
+        self._armed = False
+        #: Which voices play their shifter; the others play their tap at 0.
+        self._on = [True, True, True]
+        self._puller = None
+
+        # The borrowed source's only reader: a width-1 MidSide is the source
+        # byte for byte, in whole 256-frame blocks whatever buffers the
+        # source hands out. At Mix 0 the output is this node, and the
+        # Splitter reads it too, so routing around the graph and back never
+        # skips or repeats a source frame.
+        self._head = self._own(audioroute.MidSide(
+            self._source, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        # A MidSide with no source hands out one block of zeros per pull.
+        # The Splitter reads it while the voices are armed (`_arm`), so
+        # arming takes nothing from the source.
+        self._hush = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels),
+            reset=False)
+        self._in = self._own(audioroute.Port(self._hush), reset=False)
+        split = self._own(audioroute.Splitter(self._in, taps=4),
+                          reset=False)
+        self._taps = [split.tap(i) for i in range(4)]
+
+        # Three shifters, each on its own tap: each voice is its own
+        # machine, with its own line and its own splice rate.
+        frames = self._window_frames()
+        self._frames = frames
+        self._overlap = frames // 16
+        self._shifters = []
+        for k in range(3):
+            shifter = self._own(self._shifter(frames, self._overlap))
+            shifter.play(self._taps[k + 1], loop=True)
+            self._shifters.append(shifter)
+
+        # Each mixer voice plays a Port, so switching a voice between its
+        # shifter and its bare tap re-points the port and primes nothing.
+        self._ports = [self._own(audioroute.Port(self._taps[0]),
+                                 reset=False)]
+        for k in range(3):
+            self._ports.append(self._own(audioroute.Port(self._shifters[k]),
+                                         reset=False))
+        # Not reset by the walk: no voice holds a block between two pulls.
+        self._mixer = self._own(audiomixer.Mixer(
+            voice_count=4, **self._pcm(1024 * channels)), reset=False)
+        # A voice's play() primes a block; with the Splitter on the hush it
+        # is zeros, and one pull drops it.
+        for i in range(4):
+            self._mixer.voice[i].play(self._ports[i], loop=True)
+        # The output: a width-1 MidSide, byte for byte, whose reset forwards
+        # nothing, so a host's reset of the output never reaches the Mixer.
+        self._tail = self._own(audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        self._output = self._tail
+        self._pull()
+
+        self._init_macros(tuple(
+            _component.macro_value(self._MACRO_RANGES[i],
+                                   _component.position_of_midi(
+                                       self._mode(i), grid[i]))
+            for i in range(10)))
+        # Land each knob exactly on its step, as patch 0 does.
+        for i in range(10):
+            self._macros[i] = _component.position_of_midi(self._mode(i),
+                                                          grid[i])
+        # A constructor patch lands before the voices are first armed, so
+        # their level gates open at the patch's levels.
+        if patch is not None:
+            self.program_change(patch)
+        self._ready = True
+        self._refresh()
+
+    def _grid(self, asked):
+        """Each constructor value as its knob's nearest MIDI step: NaN is
+        the default, anything past a stop is that stop, and a Level below
+        -40 dB is off."""
+        grid = []
+        for i in range(10):
+            value = _number(asked[i], DEFAULTS[i])
+            span = self._MACRO_RANGES[i]
+            if i in LEVEL_I and value < LEVEL_FLOOR_DB:
+                grid.append(0)
+                continue
+            low = LEVEL_FLOOR_DB if i in LEVEL_I else span[0]
+            value = min(span[1], max(low, value))
+            grid.append(_component.macro_of(span, value, self._mode(i)))
+        return grid
+
+    # -- the parts; each a method, so a test can plant a fault in one -----
+
+    def _window_frames(self):
+        """The window in frames, from milliseconds at the running rate."""
+        return max(1, int(self._window_ms * self._sample_rate / 1000.0
+                          + 0.5))
+
+    def _shifter(self, frames, overlap):
+        width = 2 * self._channel_count
+        return audiodelays.PitchShift(
+            semitones=0.0, mix=1.0, window=frames * width,
+            overlap=overlap * width, **self._pcm(BLOCK * width))
+
+    def _voice_source(self, k):
+        """What voice `k` (0, 1, 2) plays while it is on: its shifter."""
+        return self._shifters[k]
+
+    def _off_source(self, k):
+        """What voice `k` plays while it is off: its bare tap, at level 0,
+        so its shifter is not pulled."""
+        return self._taps[k + 1]
+
+    def _empty(self, k):
+        """Empty voice `k`'s line before it comes back on."""
+        audiocore.reset_buffer(self._shifters[k])
+
+    def _semitones(self, k):
+        """What voice `k` (0, 1, 2) asks for: Pitch + Voice + its share of
+        Detune (voice 1 down, voice 2 up, voice 3 none)."""
+        detune = self._value(DETUNE_I) / 100.0
+        share = (-detune, detune, 0.0)[k]
+        return (whole(self._value(PITCH_I))
+                + whole(self._value(VOICE_I[k])) + share)
+
+    def _node_semitones(self, asked):
+        """The nearest step the node can play, handed over at its centre."""
+        return step_semitones(ratio_step(asked))
+
+    def _level(self, k):
+        return level_gain(self._value(LEVEL_I[k]))
+
+    def _dry_level(self):
+        return mix_gains(self._value(MIX_I))[0]
+
+    def _voice_level(self, k):
+        return self._level(k) * mix_gains(self._value(MIX_I))[1]
+
+    def _pans(self):
+        spread = min(1.0, max(0.0, self._value(SPREAD_I)))
+        return (0.0, -spread, spread, 0.0)
+
+    # -- the controls ----------------------------------------------------
+
+    def _value(self, index):
+        return _component.macro_value(self._MACRO_RANGES[index],
+                                      self._macros[index])
+
+    def _apply_macro(self, index, position):
+        del index, position
+        if self._ready:
+            self._refresh()
+
+    def program_change(self, index, channel=0, note_id=-1,
+                       sample_position=0):
+        """Apply patch `index` whole, then set the graph once."""
+        ready = self._ready
+        self._ready = False
+        try:
+            _component.Component.program_change(
+                self, index, channel, note_id, sample_position)
+        finally:
+            self._ready = ready
+        if ready and type(self).PATCHES.get(index) is not None:
+            self._refresh()
+
+    def reset(self):
+        """Empty the three lines, return their splices to a new node's
+        start, and restore patch 0."""
+        self._check_live()
+        self._clear_nodes()
+        self._stranded = False
+        # The voices are armed again, as the constructor arms them, the
+        # next time the output reaches the mixer.
+        self._armed = False
+        self.program_change(0)
+
+    def _refresh(self):
+        for k in range(3):
+            self._shifters[k].semitones = self._node_semitones(
+                self._semitones(k))
+        self._route()
+
+    def _wanted(self, k):
+        return self._level(k) > 0.0
+
+    def _levels(self):
+        voices = self._mixer.voice
+        pans = self._pans()
+        voices[0].level = self._dry_level()
+        for k in range(3):
+            voices[k + 1].level = self._voice_level(k)
+        if self._channel_count == 2:
+            for i in range(4):
+                voices[i].panning = pans[i]
+
+    def _route(self):
+        """Mix 0 hands out the source; anything else plays the mixer, armed
+        again if the graph was left or reset."""
+        if self._macros[MIX_I] <= 0.0:
+            self._route_around(self._head)
+            return
+        if self._rejoin() or not self._armed:
+            self._arm()
+        else:
+            self._switch()
+        self._output = self._tail
+
+    def _switch(self):
+        """Turn voices on and off. A voice going off plays its bare tap at
+        level 0, so the split stays even and its shifter is not pulled; a
+        voice coming back empties its shifter's line, plays it, then takes
+        its level."""
+        voices = self._mixer.voice
+        for k in range(3):
+            wanted = self._wanted(k)
+            if wanted == self._on[k]:
+                continue
+            if wanted:
+                self._empty(k)
+                self._ports[k + 1].play(self._voice_source(k))
+            else:
+                voices[k + 1].level = 0.0
+                self._ports[k + 1].play(self._off_source(k))
+            self._on[k] = wanted
+        self._levels()
+
+    def _arm(self):
+        """Arm the voices, the same way every time: with the Splitter on
+        the hush and every voice on its shifter, one pull of the mixer opens
+        the voices' level gates on zeros and leaves no voice and no shifter
+        holding a block. Then every line is emptied, which also puts its
+        splice where a new node's starts, the Splitter goes back to the
+        source and the voices that are off go to their taps. So a reset, a
+        return from Mix 0 and a voice turned back on all start their
+        shifters exactly as the constructor does."""
+        self._levels()
+        self._in.play(self._hush)
+        for k in range(3):
+            self._ports[k + 1].play(self._voice_source(k))
+        self._pull()
+        for k in range(3):
+            audiocore.reset_buffer(self._shifters[k])
+        self._in.play(self._head)
+        for k in range(3):
+            self._on[k] = self._wanted(k)
+            if not self._on[k]:
+                self._ports[k + 1].play(self._off_source(k))
+        self._armed = True
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `_tail` and stops: its `play()` primes one block, which pulls
+        the mixer once. `_tail` forwards no reset, so the play rewinds
+        nothing behind it."""
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(self._mixer)
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # smallest that hold a stereo frame.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, **self._pcm(16)), reset=False)
+        voice = self._puller.voice[0]
+        voice.play(self._tail)
+        voice.stop()
+
+    @property
+    def tail_samples(self):
+        """The shifters' lines, every one overwritten, and a block."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        if self._macros[MIX_I] <= 0.0:
+            return 0
+        if not (self._wanted(0) or self._wanted(1) or self._wanted(2)):
+            return 0
+        return self._frames + self._overlap + BLOCK
+
+    @property
+    def window_ms(self):
+        """The window the instance was built with, in milliseconds."""
+        self._check_live()
+        return self._window_ms
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..afc5947 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,13 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("Harmonizer", "plants", "T6a/"):
+        "the plant acts only when a Level comes back from off, a move the"
+        " plant check never makes; T6's own test shows it red on that move",
+    ("Harmonizer", "plants", "T6b/"):
+        "the plant acts only when a Level goes off and comes back, a move"
+        " the plant check never makes; T6's own test shows it red on that"
+        " move",
 }
 
 CPYTHON = sys.implementation.name == "cpython"
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..36ab3d5 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,6 +75,43 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
+    ("Harmonizer", "E1-", "P4"):
+        "reset() empties the three lines and starts every splice where a"
+        " new instance's starts, so a shifted voice then renders as a fresh"
+        " instance (test_reset_renders_as_fresh), not as the uninterrupted"
+        " control",
+    ("Harmonizer", "E4-", "P4"):
+        "a Pitch, Voice or Detune move runs a shifter's read head at another"
+        " rate, so its splice lands elsewhere and stays there (the node's"
+        " by-design cell); a Level off and back, or Mix 0 and back, empties"
+        " the line and starts the splice as a fresh voice's (T6)",
+    ("Harmonizer", "E5-", "P4"):
+        "Mix 0 and back empties the lines and starts every splice as a"
+        " fresh instance's, not the uninterrupted control's",
+    ("Harmonizer", "E6-", "P4"):
+        "a patch change moves intervals, so the splices land elsewhere, or"
+        " turns a voice off and back, which starts its splice afresh",
+    ("Harmonizer", "E9-", "P4"):
+        "as E5: Mix 0 and back starts every splice afresh, at every source"
+        " buffer size",
+    ("Harmonizer", "E11-", "P4"):
+        "moves that reach an interval, a Level's off step or Mix 0 move the"
+        " splices, as E4 to E6",
+    ("Harmonizer", "E4-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step",
+    ("Harmonizer", "E5-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix)",
+    ("Harmonizer", "E6-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (a patch change)",
+    ("Harmonizer", "E9-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix)",
+    ("Harmonizer", "E11-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
new file mode 100644
index 0000000..d476cda
--- /dev/null
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -0,0 +1,1352 @@
+"""`Harmonizer`'s trait and planted-fault tests.
+
+Six traits, T1 to T6, each with its measurement run over the span listed
+with it and the same measurement shown red on a planted fault of the same
+kind. `KIT_PLANTS` hands the plants to the kit, which shows each one
+differs from the clean class and that no knob stop or patch reproduces it.
+`CLAIMS` ties every claim sentence of the docstring to the tests that hold
+it.
+
+Every law a measurement checks against is written out here, never taken
+from the class: the shifter's 1/256 steps, the splice spacing, the window
+in frames, the Mixer's level and pan arithmetic, the Mix law.
+
+Traits 2 to 4 read a ramp probe: the input rises one LSB per frame from
+-16384 to +16383, so with one voice alone every output sample is the
+position the shifter read. A splice is a burst of steps outside 0..4; a
+clean stretch is 256 frames clear of one, across which the output rises by
+exactly the node's step `k`.
+
+The default run takes two of the card's eight seeds or ramp offsets per
+cell; `HARMONIZER_FULL=1` runs all eight. The module is numpy-free and
+imports on MicroPython and CircuitPython, where `unittest` is absent: the
+kit reads `KIT_PLANTS` there.
+"""
+
+import math
+import sys
+from array import array
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                     # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    import os
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.join(_HERE, "..", "lib"))
+    FULL = bool(os.environ.get("HARMONIZER_FULL"))
+except (ImportError, AttributeError, NameError):   # no os.path natively
+    FULL = False
+
+import kit_common as kc                                     # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+try:
+    import synthio
+except ImportError:                     # pragma: no cover
+    synthio = None
+
+VENDOR = "PyDevices"
+
+RATES = (48000, 22050)
+CHANNELS = (2, 1)
+BLOCK = 256
+PITCH = 0
+VOICE = (1, 2, 3)
+LEVEL = (4, 5, 6)
+DETUNE = 7
+SPREAD = 8
+MIX = 9
+
+Harmonizer = rebuilt.module_class("Harmonizer")
+
+SEEDS = tuple(range(1, 9)) if FULL else (1, 2)
+OFFSETS = ((0, 37, 101, 173, 263, 389, 512, 777) if FULL else (0, 263))
+#: Frames read after the Mixer's zero-crossing gates have settled.
+SETTLE = 4096
+
+
+# --------------------------------------------------------------------------
+# The laws, written out
+
+
+def step_of(semitones):
+    """The shifter's nearest read-rate step, in 256ths of a frame."""
+    return int(math.floor(256.0 * 2.0 ** (semitones / 12.0) + 0.5))
+
+
+def step_cents(k):
+    """Half the width of step `k`, in cents: how far a voice can sit from
+    the interval it asked for."""
+    return 1200.0 * math.log((k + 0.5) / k) / math.log(2.0)
+
+
+def window_frames(ms, rate):
+    return int(ms * rate / 1000.0 + 0.5)
+
+
+def crossfade(frames):
+    return frames // 16
+
+
+def splice_gap(frames, k):
+    """Frames between two splices: the read head gains or loses a whole
+    window every `256 / |k - 256|` windows."""
+    if k == 256:
+        return None
+    return frames * 256.0 / abs(k - 256)
+
+
+def semis_of_midi(m):
+    """A Pitch or Voice MIDI step as the whole semitone it plays: a
+    bipolar knob with its centre at 64, -12 to +12."""
+    if m >= 64:
+        value = 12.0 * (m - 64) / 63.0
+    else:
+        value = -12.0 * (64 - m) / 64.0
+    return int(math.floor(value + 0.5))
+
+
+def midi_of_semis(s):
+    """The MIDI step a whole semitone sits on (the nearest)."""
+    best = None
+    for m in range(128):
+        if semis_of_midi(m) == s:
+            if m >= 64:
+                exact = 64 + 63.0 * s / 12.0
+            else:
+                exact = 64 + 64.0 * s / 12.0
+            if best is None or abs(m - exact) < abs(best - exact):
+                best = m
+    return best
+
+
+def cents_of_midi(m):
+    return 25.0 * m / 127.0
+
+
+def db_of_midi(m):
+    """A Level step in dB; MIDI 0 is off (None)."""
+    if m <= 0:
+        return None
+    return -40.0 + 40.0 * (m - 1) / 126.0
+
+
+def mix_of_midi(m):
+    return 2.0 * m / 127.0
+
+
+def gains(mix):
+    """The house Mix law: (dry, voice)."""
+    return (1.0 if mix <= 1.0 else 2.0 - mix), min(mix, 1.0)
+
+
+def f32(x):
+    """`x` rounded to single precision."""
+    import struct
+    return struct.unpack("f", struct.pack("f", x))[0]
+
+
+def mixer_scale(x, mul):
+    """One sample through the Mixer's voice multiply at integer level `mul`
+    (32768 is unity): times `mul / 32767` in single precision, truncated
+    toward zero, clamped."""
+    if mul == 32768:
+        return x
+    y = int(f32(x * f32(mul / 32767.0)))
+    return max(-32768, min(32767, y))
+
+
+def level_int(gain):
+    return int(gain * 32768.0)
+
+
+def pan_muls(level, pan):
+    """(left, right) integer levels of a stereo voice at gain `level` and
+    pan `pan`: a pan right of centre attenuates the left, and the side that
+    is not attenuated still runs at 32767/32768 of the level at centre."""
+    p = int(round(min(32767.0 / 32768, max(-32767.0 / 32768, pan))
+                  * 32768.0))
+    lvl = level_int(level)
+    left, right = 32768, 32768
+    if p >= 0:
+        left = 32767 - p
+    else:
+        right = 32767 + p
+    return (left * lvl) >> 15, (right * lvl) >> 15
+
+
+# --------------------------------------------------------------------------
+# Material
+
+
+class Rng:
+    """A 31-bit LCG: the same uniforms on every interpreter."""
+
+    def __init__(self, seed):
+        self.state = (seed * 2654435761 + 12345) & 0x7FFFFFFF
+
+    def uniform(self, low, high):
+        self.state = (1103515245 * self.state + 12345) & 0x7FFFFFFF
+        return low + (high - low) * (self.state / 2147483648.0)
+
+
+def _clamp(v):
+    return max(-32768, min(32767, int(round(v))))
+
+
+def gauss(frames, channels, sigma, seed, lead=BLOCK):
+    """Gaussian noise at `sigma` LSB, each channel its own, after `lead`
+    frames of silence (a zero opens every level gate at once)."""
+    rng = Rng(seed)
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(lead * channels, frames * channels):
+        u1 = rng.uniform(1e-9, 1.0)
+        u2 = rng.uniform(0.0, 1.0)
+        out[i] = _clamp(sigma * math.sqrt(-2.0 * math.log(u1))
+                        * math.cos(2.0 * math.pi * u2))
+    return out
+
+
+def chord(frames, channels, rate, seed, peak=6000.0, lead=BLOCK):
+    """Three sines between 110 and 880 Hz, random phases per channel,
+    normalised to `peak`, after `lead` frames of silence."""
+    rng = Rng(seed + 1000)
+    freqs = [rng.uniform(110.0, 880.0) for _ in range(3)]
+    phases = [[rng.uniform(0.0, 2.0 * math.pi) for _ in range(3)]
+              for _ in range(channels)]
+    body = []
+    for c in range(channels):
+        y = [0.0] * frames
+        for f, ph in zip(freqs, phases[c]):
+            w = 2.0 * math.pi * f / rate
+            for i in range(lead, frames):
+                y[i] += math.sin(w * (i - lead) + ph)
+        top = max(max(y), -min(y)) or 1.0
+        body.append([peak * v / top for v in y])
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(frames):
+        for c in range(channels):
+            out[i * channels + c] = _clamp(body[c][i])
+    return out
+
+
+def ramp(offset, channels):
+    """The ramp probe: `offset` + 1 frames of silence (a zero opens every
+    level gate at once), then one LSB per frame from -16384 to +16383, the
+    same in every channel."""
+    lead = offset + 1
+    frames = lead + 32768
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(lead, frames):
+        v = -16384 + i - lead
+        for c in range(channels):
+            out[i * channels + c] = v
+    return out
+
+
+def chan(values, channels, which=0):
+    return [values[i] for i in range(which, len(values), channels)]
+
+
+def rms(values):
+    if not values:
+        return 0.0
+    return math.sqrt(sum(v * v for v in values) / len(values))
+
+
+# --------------------------------------------------------------------------
+# Rendering
+
+
+def render(cls, values, rate, channels, frames=None, options=None,
+           patch=None, macros=(), mute_dry=False, actions=None):
+    """`cls` around `values`, then silence, as a list of int16 samples:
+    `patch` first, then each `(macro, MIDI)` of `macros`."""
+    if frames is None:
+        frames = len(values) // channels
+    feed = kc.feed(values, rate, channels)
+    e = cls(feed.port, sample_rate=rate, **(options or {}))
+    try:
+        if patch is not None:
+            e.program_change(patch)
+        for index, value in macros:
+            e.set_macro(index, value)
+        if mute_dry:
+            # The kit's mute_dry reading: the class's own output with the
+            # dry voice at zero, every tap still pulled.
+            e._mixer.voice[0].level = 0.0
+        return list(kc.samples(kc.render(e, frames, actions)))
+    finally:
+        e.deinit()
+
+
+def alone(k, level=127, mix=127):
+    """Macros for voice `k` (0, 1, 2) alone: Mix 2, the others off."""
+    return [(MIX, mix)] + [(LEVEL[j], level if j == k else 0)
+                           for j in range(3)]
+
+
+# --------------------------------------------------------------------------
+# Reading the ramp
+
+
+def jumps(y, start):
+    """Frames whose step from the one before is outside 0..4."""
+    out = []
+    for i in range(max(1, start), len(y)):
+        d = y[i] - y[i - 1]
+        if d < 0 or d > 4:
+            out.append(i)
+    return out
+
+
+def stretches(y, start, jl):
+    """The rise across each clean stretch: 256 frames that start and end
+    at least 4 frames from a jump, taken end to end."""
+    import bisect
+    rises = []
+    a = start
+    n = len(y)
+    while a + 256 + 4 < n:
+        j = bisect.bisect_left(jl, a - 4)
+        if j < len(jl) and jl[j] <= a + 256 + 4:
+            a = jl[j] + 5
+            continue
+        rises.append(y[a + 256] - y[a])
+        a += 256
+    return rises
+
+
+def splices(jl, fade):
+    """Jump frames clustered into splices: within one crossfade of each
+    other they are one splice. Returns each splice's first frame."""
+    starts = []
+    last = None
+    for j in jl:
+        if last is None or j - last > max(fade, 1):
+            starts.append(j)
+        last = j
+    return starts
+
+
+def ramp_read(cls, rate, channels, k_voice, macros, offset, options=None,
+              patch=None):
+    """One voice alone on the ramp: (output channel, analysis start)."""
+    values = ramp(offset, channels)
+    y = render(cls, values, rate, channels, options=options, patch=patch,
+               macros=alone(k_voice) + list(macros))
+    which = 1 if (channels == 2 and k_voice == 1) else 0
+    ms = (options or {}).get("window_ms", 1024.0 / 48.0)
+    w = window_frames(ms, rate)
+    return chan(y, channels, which), offset + 1 + w + crossfade(w) + 8
+
+
+def asked(pitch_m, voice_m, detune_m, k_voice):
+    share = (-1.0, 1.0, 0.0)[k_voice] * cents_of_midi(detune_m) / 100.0
+    return semis_of_midi(pitch_m) + semis_of_midi(voice_m) + share
+
+
+def claimed_stretch(w, k):
+    gap = splice_gap(w, k)
+    return gap is None or gap >= 256 + crossfade(w) + 8
+
+
+# --------------------------------------------------------------------------
+# The planted faults
+
+
+class SharedShifter(Harmonizer):
+    """T1: voices 1 and 2 share one PitchShift, pulled twice a block."""
+
+    def _voice_source(self, k):
+        return self._shifters[0 if k == 1 else k]
+
+
+class DuckedDry(Harmonizer):
+    """T1: the dry ducks by the number of voices that are on."""
+
+    def _dry_level(self):
+        on = sum(1 for k in range(3) if self._level(k) > 0.0)
+        return Harmonizer._dry_level(self) / (1 + on)
+
+
+class Unrounded(Harmonizer):
+    """T2: the node is handed the asked semitones, and floors them."""
+
+    def _node_semitones(self, asked_semitones):
+        return asked_semitones
+
+
+class PitchOnVoice1(Harmonizer):
+    """T2: Pitch moves voice 1 only."""
+
+    def _semitones(self, k):
+        value = Harmonizer._semitones(self, k)
+        if k:
+            value -= math.floor(self._value(PITCH) + 0.5)
+        return value
+
+
+class ChorusDetune(Harmonizer):
+    """T3: voice 1's node takes a +-10 cent, 1.5 Hz LFO: a chorus."""
+
+    def _refresh(self):
+        Harmonizer._refresh(self)
+        self._shifters[0].semitones = synthio.LFO(
+            rate=1.5, scale=0.1,
+            offset=self._node_semitones(self._semitones(0)))
+
+
+class WindowInBytes(Harmonizer):
+    """T4: the window sized in stereo bytes whatever the channel count."""
+
+    def _shifter(self, frames, overlap):
+        import audiodelays
+        return audiodelays.PitchShift(
+            semitones=0.0, mix=1.0, window=frames * 4, overlap=overlap * 4,
+            **self._pcm(BLOCK * 2 * self._channel_count))
+
+
+class WindowAt48k(Harmonizer):
+    """T4: the window sized in frames at 48 kHz whatever the rate."""
+
+    def _window_frames(self):
+        return int(self._window_ms * 48.0 + 0.5)
+
+
+class LevelAsAmplitude(Harmonizer):
+    """T5 a: a Level read as an amplitude over the span (-6 dB is 0.85)."""
+
+    def _level(self, k):
+        db = self._value(LEVEL[k])
+        if db < -40.0:
+            return 0.0
+        return (db + 40.0) / 40.0
+
+
+class CrossfadeMix(Harmonizer):
+    """T5 b: a crossfade Mix law, the dry at 1 - Mix / 2."""
+
+    def _dry_level(self):
+        return max(0.0, 1.0 - self._value(MIX) / 2.0)
+
+
+class SwappedSpread(Harmonizer):
+    """T5 c: voice 1 pans right and voice 2 left."""
+
+    def _pans(self):
+        pans = Harmonizer._pans(self)
+        return (pans[0], pans[2], pans[1], pans[3])
+
+
+class NoEmpty(Harmonizer):
+    """T6: a voice coming back is not emptied."""
+
+    def _empty(self, k):
+        pass
+
+
+class PulledWhileOff(Harmonizer):
+    """T6: an off voice keeps its shifter pulled at level 0, and is not
+    emptied on the way back."""
+
+    def _off_source(self, k):
+        return self._shifters[k]
+
+    def _empty(self, k):
+        pass
+
+
+KIT_PLANTS = {
+    "T1a": SharedShifter,
+    "T1b": DuckedDry,
+    "T2a": Unrounded,
+    "T2b": (PitchOnVoice1, None, {"options": {"pitch": 5.0}}),
+    "T3": ChorusDetune,
+    "T4a": (WindowInBytes, None, {"channels": 1}),
+    "T4b": (WindowAt48k, None, {"rate": 22050}),
+    "T5a": LevelAsAmplitude,
+    "T5b": CrossfadeMix,
+    "T5c": (SwappedSpread, 3),
+    # Both act only when a Level comes back from off, which the kit's
+    # plant check never does; T6's own test shows them red on that move.
+    "T6a": NoEmpty,
+    "T6b": PulledWhileOff,
+}
+
+
+# --------------------------------------------------------------------------
+# T1: each voice is its own machine
+
+
+def t1_cell(cls, rate, channels, patch, mix_m, material, seed):
+    """(all-on render, sum of the four solos, solo RMS problems)."""
+    frames = SETTLE + 2048 + BLOCK
+    if material == "noise":
+        values = gauss(frames, channels, 2000.0, seed)
+    else:
+        values = chord(frames, channels, rate, seed)
+    on = [Harmonizer.PATCHES[patch][1][LEVEL[k]] for k in range(3)]
+    base = [(MIX, mix_m)]
+    full = render(cls, values, rate, channels, patch=patch, macros=base)
+    total = render(cls, values, rate, channels, patch=patch,
+                   macros=base + [(LEVEL[k], 0) for k in range(3)])
+    problems = []
+    x = list(values)
+    x_rms = rms(x[(SETTLE + BLOCK) * channels:])
+    g_wet = gains(mix_of_midi(mix_m))[1]
+    for k in range(3):
+        if not on[k]:
+            continue
+        macros = base + [(LEVEL[j], 0) for j in range(3) if j != k]
+        solo = render(cls, values, rate, channels, patch=patch,
+                      macros=macros, mute_dry=True)
+        want = x_rms * 10.0 ** (db_of_midi(on[k]) / 20.0) * g_wet
+        got = rms(solo[(SETTLE + BLOCK) * channels:])
+        if got <= 0.0 or abs(20.0 * math.log10(got / want)) > 3.0:
+            problems.append((k, got, want))
+        total = [a + b for a, b in zip(total, solo)]
+    return full, total, problems
+
+
+def t1_worst(cls, rate, channels, patch, mix_m, seeds):
+    worst = 0
+    problems = []
+    for material in ("noise", "chord"):
+        for seed in seeds:
+            full, total, bad = t1_cell(cls, rate, channels, patch, mix_m,
+                                       material, seed)
+            worst = max(worst, max(abs(a - b) for a, b in
+                                   zip(full, total)))
+            problems.extend(bad)
+    return worst, problems
+
+
+class T1Independent(TestCase):
+    """Turning one voice on or off never changes the dry or the other
+    voices: the all-on render is the sum of four solos, sample for sample,
+    and each voice solo carries its level."""
+
+    def test_the_sum_of_the_solos(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for patch in (0, 3, 5):
+                    for mix_m in (32, 64, 95):
+                        worst, problems = t1_worst(
+                            Harmonizer, rate, channels, patch, mix_m, SEEDS)
+                        cell = (rate, channels, patch, mix_m)
+                        self.assertEqual(worst, 0, cell)
+                        self.assertEqual(problems, [], cell)
+
+    def test_a_shared_shifter_is_red(self):
+        worst, _ = t1_worst(SharedShifter, 48000, 2, 0, 64, (1,))
+        self.assertGreater(worst, 100)
+
+    def test_a_ducked_dry_is_red(self):
+        worst, _ = t1_worst(DuckedDry, 48000, 2, 0, 64, (1,))
+        self.assertGreater(worst, 100)
+
+
+# --------------------------------------------------------------------------
+# T2: the intervals
+
+
+def t2_cell(cls, rate, channels, k_voice, pitch_m, voice_m, detune_m,
+            patch=None, offsets=OFFSETS):
+    """None if the cell is not claimed, else a list of failures."""
+    if patch is not None:
+        values = Harmonizer.PATCHES[patch][1]
+        voice_m = values[VOICE[k_voice]]
+        detune_m = values[DETUNE]
+        pitch_m = values[PITCH]
+    a = asked(pitch_m, voice_m, detune_m, k_voice)
+    k = step_of(a)
+    w = window_frames(1024.0 / 48.0, rate)
+    if not claimed_stretch(w, k):
+        return None
+    bad = []
+    macros = [(PITCH, pitch_m), (VOICE[k_voice], voice_m),
+              (DETUNE, detune_m)]
+    for offset in offsets:
+        y, start = ramp_read(cls, rate, channels, k_voice, macros, offset,
+                             patch=patch)
+        rises = stretches(y, start, jumps(y, start))
+        if len(rises) < 8 or any(r != k for r in rises):
+            bad.append((offset, k, len(rises), sorted(set(rises))[:4]))
+    return bad
+
+
+class T2Intervals(TestCase):
+    """Each voice reads at `round(256 * 2^(asked / 12))`, the nearest step
+    the shifter has to Pitch + Voice + its Detune share."""
+
+    def _check(self, cls, rate, channels, cells):
+        claimed = 0
+        for cell in cells:
+            bad = t2_cell(cls, rate, channels, *cell)
+            if bad is None:
+                continue
+            claimed += 1
+            self.assertEqual(bad, [], (rate, channels, cell))
+        self.assertGreater(claimed, 0)
+
+    def test_every_voice_1_position(self):
+        seen = set()
+        cells = []
+        for m in range(128):
+            s = semis_of_midi(m)
+            if s not in seen:
+                seen.add(s)
+                cells.append((0, 64, m, 0))
+        self.assertEqual(len(cells), 25)
+        self._check(Harmonizer, 48000, 2, cells)
+
+    def test_pitch_moves_every_voice(self):
+        cells = []
+        for pitch in (-12, 7, 12):
+            for detune_m in (0, 127):
+                for k in range(3):
+                    voice_m = Harmonizer.PATCHES[0][1][VOICE[k]]
+                    cells.append((k, midi_of_semis(pitch), voice_m,
+                                  detune_m))
+        self._check(Harmonizer, 48000, 2, cells)
+
+    def test_every_patch(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                cells = []
+                for patch in sorted(Harmonizer.PATCHES):
+                    levels = Harmonizer.PATCHES[patch][1][4:7]
+                    for k in range(3):
+                        if levels[k]:
+                            cells.append((k, 0, 0, 0, patch))
+                self._check(Harmonizer, rate, channels, cells)
+
+    def test_plus_24_at_22050_is_not_claimed(self):
+        w = window_frames(1024.0 / 48.0, 22050)
+        self.assertLess(splice_gap(w, step_of(24.0)), 158)
+        self.assertFalse(claimed_stretch(w, step_of(24.0)))
+
+    def test_within_half_a_step(self):
+        """Every interval a voice can ask for, at every Detune step, lands
+        on its nearest step: the worst miss is 3.4 cents from unison up,
+        6.8 down to an octave below and 13.7 below that."""
+        worst = {"up": 0.0, "octave": 0.0, "low": 0.0}
+        for s in range(-24, 25):
+            for d in range(128):
+                for share in (-1, 0, 1):
+                    a = s + share * cents_of_midi(d) / 100.0
+                    k = step_of(a)
+                    exact = 256.0 * 2.0 ** (a / 12.0)
+                    self.assertLessEqual(abs(exact - k), 0.5)
+                    miss = abs(1200.0 * math.log(k / 256.0) / math.log(2.0)
+                               - 100.0 * a)
+                    region = ("up" if a >= 0 else
+                              "octave" if a >= -12 else "low")
+                    worst[region] = max(worst[region], miss)
+        self.assertLessEqual(worst["up"], 3.4)
+        self.assertLessEqual(worst["octave"], 6.8)
+        self.assertLessEqual(worst["low"], 13.7)
+        self.assertGreater(worst["low"], 13.5)
+
+    def test_detune_moves_in_steps_of_about_7_cents_near_unison(self):
+        width = 1200.0 * math.log(257.0 / 256.0) / math.log(2.0)
+        self.assertAlmostEqual(width, 6.75, places=2)
+        # So Detune 3 cents leaves both voices on the unison step.
+        self.assertEqual(step_of(0.03), 256)
+        self.assertEqual(step_of(-0.03), 256)
+
+    def test_unrounded_semitones_are_red(self):
+        bad = t2_cell(Unrounded, 48000, 2, 0, 64, 85, 0, offsets=(0,))
+        self.assertTrue(bad)
+
+    def test_pitch_on_voice_1_only_is_red(self):
+        bad = t2_cell(PitchOnVoice1, 48000, 2, 1, midi_of_semis(7), 101, 0,
+                      offsets=(0,))
+        self.assertTrue(bad)
+
+
+# --------------------------------------------------------------------------
+# T3: Detune holds still
+
+
+def t3_cell(cls, rate, channels, patch, detune_m, offsets=OFFSETS):
+    """Failures for voices 1 and 2 at `patch` with Detune at `detune_m`."""
+    values = Harmonizer.PATCHES[patch][1]
+    bad = []
+    interval = semis_of_midi(values[VOICE[0]])
+    k0 = step_of(interval)
+    cents = cents_of_midi(detune_m)
+    # More than half a step either way: the lower half of a step is the
+    # wider in cents.
+    beyond = cents > 1200.0 * math.log(k0 / (k0 - 0.5)) / math.log(2.0)
+    for offset in offsets:
+        ks = []
+        for k_voice in (0, 1):
+            y, start = ramp_read(cls, rate, channels, k_voice,
+                                 [(DETUNE, detune_m)], offset, patch=patch)
+            rises = stretches(y, start, jumps(y, start))
+            if len(rises) < 8 or len(set(rises)) != 1:
+                bad.append((offset, k_voice, len(rises),
+                            sorted(set(rises))[:4]))
+                ks.append(None)
+            else:
+                ks.append(rises[0])
+        if None in ks:
+            continue
+        if beyond and not ks[0] < k0 < ks[1]:
+            bad.append((offset, "order", ks, k0))
+        if not ks[0] <= k0 <= ks[1]:
+            bad.append((offset, "side", ks, k0))
+    return bad
+
+
+class T3SteadyDetune(TestCase):
+    """Detune is a steady offset: every clean stretch of a detuned voice
+    rises by the same step, voice 1 below the undetuned step and voice 2
+    above it wherever Detune is more than half a step."""
+
+    def test_every_eighth_position(self):
+        positions = list(range(0, 128, 8)) + [127]
+        for rate in RATES:
+            for channels in CHANNELS:
+                for patch in (1, 2):
+                    for d in positions:
+                        bad = t3_cell(Harmonizer, rate, channels, patch, d,
+                                      offsets=OFFSETS[:1] if not FULL
+                                      else OFFSETS)
+                        self.assertEqual(bad, [],
+                                         (rate, channels, patch, d))
+
+    def test_a_chorus_is_red(self):
+        for rate in RATES:
+            bad = t3_cell(ChorusDetune, rate, 2, 1, 71, offsets=(0,))
+            self.assertTrue(bad, rate)
+
+
+# --------------------------------------------------------------------------
+# T4: the splice spacing
+
+
+T4_INTERVALS = (4, 7, 12, -5, -7, -12)
+T4_WINDOWS = (5.0, 1024.0 / 48.0, 60.0)
+
+
+def t4_cell(cls, rate, channels, window_ms, interval, offsets=OFFSETS):
+    """None if not claimed, else [(offset, measured mean gap or None)]."""
+    w = window_frames(window_ms, rate)
+    k = step_of(interval)
+    gap = splice_gap(w, k)
+    start = w + crossfade(w) + 8
+    if 5 * gap > 32768 - start:
+        return None
+    out = []
+    for offset in offsets:
+        y, start = ramp_read(cls, rate, channels, 0,
+                             [(VOICE[0], midi_of_semis(interval))], offset,
+                             options={"window_ms": window_ms})
+        starts = splices(jumps(y, start), crossfade(w))
+        if len(starts) < 5:
+            out.append((offset, None, gap))
+            continue
+        mean = (starts[-1] - starts[0]) / float(len(starts) - 1)
+        out.append((offset, mean, gap))
+    return out
+
+
+def t4_bad(cells):
+    return [c for c in cells if c[1] is None or
+            abs(c[1] - c[2]) > 0.01 * c[2]]
+
+
+class T4Window(TestCase):
+    """The mean gap between splices is `window_frames * 256 / |k - 256|`,
+    the same at every rate and on mono."""
+
+    def test_the_gap(self):
+        claimed = 0
+        for rate in RATES:
+            for channels in CHANNELS:
+                for ms in T4_WINDOWS:
+                    for interval in T4_INTERVALS:
+                        cells = t4_cell(Harmonizer, rate, channels, ms,
+                                        interval)
+                        if cells is None:
+                            continue
+                        claimed += 1
+                        self.assertEqual(
+                            t4_bad(cells), [],
+                            (rate, channels, ms, interval, cells))
+        self.assertGreater(claimed, 40)
+
+    def test_a_fifth_up_splices_every_43_ms(self):
+        for rate in RATES:
+            cells = t4_cell(Harmonizer, rate, 2, 1024.0 / 48.0, 7,
+                            offsets=(0,))
+            mean_ms = 1000.0 * cells[0][1] / rate
+            self.assertTrue(42.5 <= mean_ms <= 43.5, (rate, mean_ms))
+
+    def test_unison_never_splices(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for ms in T4_WINDOWS:
+                    y, start = ramp_read(
+                        Harmonizer, rate, channels, 0,
+                        [(VOICE[0], 64)], 0, options={"window_ms": ms})
+                    self.assertEqual(jumps(y, start), [])
+                    w = window_frames(ms, rate)
+                    lag = [i - (y[i] + 16385)
+                           for i in range(start, len(y))]
+                    # A fixed delay, wherever the move to unison left the
+                    # read head: between the crossfade and the window.
+                    self.assertEqual(min(lag), max(lag))
+                    self.assertTrue(crossfade(w) <= lag[0] <= w, lag[0])
+                    # Built at unison, it is one crossfade.
+                    y = render(Harmonizer, ramp(0, channels), rate,
+                               channels, options={
+                                   "window_ms": ms, "voice1": 0.0,
+                                   "level1_db": 0.0, "level2_db": -99.0,
+                                   "level3_db": -99.0, "mix": 2.0})
+                    y = chan(y, channels)
+                    lag = [i - (y[i] + 16385)
+                           for i in range(start, len(y))]
+                    self.assertEqual((min(lag), max(lag)),
+                                     (crossfade(w), crossfade(w)))
+
+    def test_a_shifted_voice_trails_by_the_crossfade_to_the_window(self):
+        for rate in RATES:
+            for interval in (-12, 7, 12):
+                y, start = ramp_read(
+                    Harmonizer, rate, 2, 0,
+                    [(VOICE[0], midi_of_semis(interval))], 0)
+                w = window_frames(1024.0 / 48.0, rate)
+                lag = [i - (y[i] + 16385) for i in range(start, len(y))]
+                self.assertGreaterEqual(min(lag), crossfade(w))
+                self.assertLessEqual(max(lag), w)
+
+    def test_a_window_in_bytes_is_red(self):
+        cells = t4_cell(WindowInBytes, 48000, 1, 1024.0 / 48.0, 7,
+                        offsets=(0,))
+        self.assertTrue(t4_bad(cells))
+
+    def test_a_window_at_48k_is_red(self):
+        cells = t4_cell(WindowAt48k, 22050, 2, 1024.0 / 48.0, 7,
+                        offsets=(0,))
+        self.assertTrue(t4_bad(cells))
+
+
+# --------------------------------------------------------------------------
+# T5: the balance controls
+
+
+T5_FRAMES = SETTLE + 2048 + BLOCK
+
+
+def t5_noise(channels, seed):
+    return gauss(T5_FRAMES, channels, 1000.0, seed)
+
+
+def t5_level(cls, rate, channels, seed):
+    """Worst |error| of each Level against the 0 dB solo scaled by the
+    Mixer's own arithmetic."""
+    values = t5_noise(channels, seed)
+    worst = 0
+    for k in (0, 2):
+        ref = render(cls, values, rate, channels, macros=alone(k, 127))
+        for m in (108, 64, 1):
+            got = render(cls, values, rate, channels, macros=alone(k, m))
+            gain = 10.0 ** (db_of_midi(m) / 20.0)
+            if channels == 2:
+                muls = pan_muls(gain, 0.0)
+            else:
+                muls = (level_int(gain),)
+            for i in range(SETTLE * channels, len(got)):
+                want = mixer_scale(ref[i], muls[i % channels])
+                worst = max(worst, abs(got[i] - want))
+    return worst
+
+
+def t5_mix(cls, rate, channels, seed):
+    values = t5_noise(channels, seed)
+    levels = [(LEVEL[k], 127) for k in range(3)]
+    dry = render(cls, values, rate, channels, macros=levels + [(MIX, 0)])
+    wet = render(cls, values, rate, channels, macros=levels + [(MIX, 127)])
+    worst = 0
+    for m in (32, 64, 95, 127):
+        got = render(cls, values, rate, channels,
+                     macros=levels + [(MIX, m)])
+        g_dry, g_wet = gains(mix_of_midi(m))
+        for i in range(SETTLE * channels, len(got)):
+            want = g_dry * dry[i] + g_wet * wet[i]
+            worst = max(worst, abs(got[i] - want))
+    return worst
+
+
+def t5_spread(cls, rate, seed):
+    """Worst |error| of voices 1 and 2 against their Spread-0 solos through
+    the Mixer's pan arithmetic, and of the dry and voice 3 against their
+    Spread-0 selves."""
+    values = t5_noise(2, seed)
+    worst = 0
+    for s_m in (64, 114):
+        spread = s_m / 127.0
+        for k in (0, 1):
+            ref = render(cls, values, rate, 2,
+                         macros=alone(k) + [(SPREAD, 0)])
+            got = render(cls, values, rate, 2,
+                         macros=alone(k) + [(SPREAD, s_m)])
+            pan = -spread if k == 0 else spread
+            muls = pan_muls(1.0, pan)
+            for i in range(SETTLE * 2, len(got)):
+                # The Spread-0 solo is the voice itself: unity is a wire.
+                want = mixer_scale(ref[i], muls[i % 2])
+                worst = max(worst, abs(got[i] - want))
+        for macros in (alone(2), [(LEVEL[j], 0) for j in range(3)]):
+            ref = render(cls, values, rate, 2, macros=macros + [(SPREAD, 0)])
+            got = render(cls, values, rate, 2,
+                         macros=macros + [(SPREAD, s_m)])
+            worst = max(worst, max(abs(a - b) for a, b in zip(ref, got)))
+    return worst
+
+
+class T5Balance(TestCase):
+    """Level, Mix and Spread do what their labels say, read after the
+    Mixer's level gates have settled."""
+
+    def test_level(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for seed in SEEDS:
+                    self.assertEqual(
+                        t5_level(Harmonizer, rate, channels, seed), 0,
+                        (rate, channels, seed))
+
+    def test_mix(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for seed in SEEDS:
+                    self.assertLess(
+                        t5_mix(Harmonizer, rate, channels, seed), 4,
+                        (rate, channels, seed))
+
+    def test_spread(self):
+        for rate in RATES:
+            for seed in SEEDS:
+                self.assertEqual(t5_spread(Harmonizer, rate, seed), 0,
+                                 (rate, seed))
+
+    def test_mono_spread_does_nothing(self):
+        values = t5_noise(1, 1)
+        for rate in RATES:
+            ref = render(Harmonizer, values, rate, 1, patch=3,
+                         macros=[(SPREAD, 0)])
+            got = render(Harmonizer, values, rate, 1, patch=3,
+                         macros=[(SPREAD, 127)])
+            self.assertEqual(ref, got, rate)
+
+    def test_level_as_amplitude_is_red(self):
+        self.assertGreater(t5_level(LevelAsAmplitude, 48000, 2, 1), 100)
+
+    def test_a_crossfade_mix_is_red(self):
+        self.assertGreater(t5_mix(CrossfadeMix, 48000, 2, 1), 100)
+
+    def test_swapped_spread_is_red(self):
+        self.assertGreater(t5_spread(SwappedSpread, 48000, 1), 100)
+
+
+# --------------------------------------------------------------------------
+# T6: a voice comes back from silence
+
+
+def t6_run(cls, rate, channels, window_ms, seed):
+    """(non-zero samples in the silence, dB of the return against before,
+    voice 3's RMS before)."""
+    def blocks(seconds):
+        return int(seconds * rate / BLOCK + 0.5)
+    n1, n2, n4, n5 = blocks(0.5), blocks(0.3), blocks(0.2), blocks(0.5)
+    first = gauss((n1 + n2) * BLOCK, channels, 2000.0, seed, lead=0)
+    second = gauss(n5 * BLOCK, channels, 2000.0, seed + 100, lead=0)
+    silence = array("h", bytes(2 * (1 + n4) * BLOCK * channels))
+    values = array("h", list(first) + list(silence) + list(second))
+    level = Harmonizer.PATCHES[0][1][LEVEL[2]]
+    off_at = n1
+    on_at = n1 + n2 + 1
+
+    def off(e):
+        e.set_macro(LEVEL[2], 0)
+
+    def on(e):
+        e.set_macro(LEVEL[2], level)
+    y = render(cls, values, rate, channels, options={"window_ms": window_ms},
+               macros=alone(2, level), actions={off_at: off, on_at: on})
+    quarter = blocks(0.25) * BLOCK * channels
+    before = rms(y[off_at * BLOCK * channels - quarter:
+                   off_at * BLOCK * channels])
+    hush = y[on_at * BLOCK * channels:(on_at + n4) * BLOCK * channels]
+    end = (on_at + n4 + n5) * BLOCK * channels
+    after = rms(y[end - quarter:end])
+    loud = sum(1 for v in hush if v)
+    db = 20.0 * math.log10(after / before) if after and before else -999.0
+    return loud, db, before
+
+
+class T6Return(TestCase):
+    """A voice turned back on plays exact silence over silence, and then
+    comes back to its level."""
+
+    def test_the_return(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for ms in (5.0, 60.0):
+                    for seed in SEEDS:
+                        loud, db, before = t6_run(Harmonizer, rate,
+                                                  channels, ms, seed)
+                        cell = (rate, channels, ms, seed)
+                        self.assertGreater(before, 100.0, cell)
+                        self.assertEqual(loud, 0, cell)
+                        self.assertLessEqual(abs(db), 3.0, cell)
+
+    def test_no_emptying_is_red(self):
+        for rate in RATES:
+            loud, _, _ = t6_run(NoEmpty, rate, 2, 60.0, 1)
+            self.assertGreater(loud, 0, rate)
+
+    def test_pulled_while_off_is_red(self):
+        for rate in RATES:
+            loud, _, _ = t6_run(PulledWhileOff, rate, 2, 60.0, 1)
+            self.assertGreater(loud, 0, rate)
+
+
+# --------------------------------------------------------------------------
+# The surface, the wire, the tail
+
+
+class TheSurface(TestCase):
+
+    def _fresh(self, rate=48000, channels=2, **options):
+        feed = kc.feed(array("h", bytes(4 * BLOCK * channels)), rate,
+                       channels)
+        return Harmonizer(feed.port, sample_rate=rate, **options)
+
+    def test_the_spans(self):
+        e = self._fresh()
+        for i in (PITCH,) + VOICE:
+            e.set_macro(i, 0)
+            self.assertEqual(e.macro(i), -12.0)
+            e.set_macro(i, 127)
+            self.assertEqual(e.macro(i), 12.0)
+        for m in range(128):
+            e.set_macro(VOICE[0], m)
+            self.assertEqual(semis_of_midi(m), math.floor(e.macro(1) + 0.5))
+        for i in LEVEL:
+            e.set_macro(i, 127)
+            self.assertAlmostEqual(e.macro(i), 0.0, places=9)
+            e.set_macro(i, 1)
+            self.assertAlmostEqual(e.macro(i), -40.0, places=9)
+            e.set_macro(i, 0)
+            self.assertLess(e.macro(i), -40.0)
+        e.set_macro(DETUNE, 127)
+        self.assertAlmostEqual(e.macro(DETUNE), 25.0, places=9)
+        e.set_macro(SPREAD, 127)
+        self.assertAlmostEqual(e.macro(SPREAD), 1.0, places=9)
+        e.set_macro(MIX, 127)
+        self.assertAlmostEqual(e.macro(MIX), 2.0, places=9)
+        self.assertEqual(Harmonizer.MACRO_LABELS,
+                         ("Pitch", "Voice 1", "Voice 2", "Voice 3",
+                          "Level 1", "Level 2", "Level 3", "Detune",
+                          "Spread", "Mix"))
+        e.deinit()
+
+    def test_constructor_values_land_on_the_grid(self):
+        e = self._fresh(voice1=4.4, level1_db=-6.1, detune_cents=13.0,
+                        spread=0.33, mix=1.3, pitch=-2.2)
+        for i in range(10):
+            midi = e.get_macro(i)
+            self.assertAlmostEqual(midi, round(midi), places=9)
+        self.assertEqual(semis_of_midi(int(round(e.get_macro(1)))), 4)
+        self.assertEqual(semis_of_midi(int(round(e.get_macro(PITCH)))), -2)
+        self.assertAlmostEqual(e.macro(PITCH), -2.25, places=9)
+        e.deinit()
+        e = self._fresh(level2_db=-50.0)
+        self.assertEqual(e.get_macro(LEVEL[1]), 0)
+        e.deinit()
+
+    def test_a_fresh_instance_reads_patch_0(self):
+        e = self._fresh()
+        self.assertEqual(tuple(int(round(e.get_macro(i)))
+                               for i in range(10)),
+                         Harmonizer.PATCHES[0][1])
+        self.assertEqual(e.patch_index, 0)
+        e.deinit()
+
+    def test_the_patches(self):
+        want = {0: ((4, 7, -12), (-6, -6, -9), 0, 0, 1),
+                1: ((-12, -12, 0), (-3, -3, None), 14, 0.5, 1),
+                2: ((0, 0, 0), (-6, -6, None), 14, 1, 1),
+                3: ((5, 7, 12), (-9, -9, -12), 0, 0.5, 1),
+                4: ((12, -12, 0), (-6, -6, None), 0, 0.5, 1),
+                5: ((3, 7, 0), (-6, -6, -6), 0, 0.5, 2),
+                6: ((4, 7, -12), (-6, -6, None), 0, 0, 1)}
+        for patch, (voices, levels, detune, spread, mix) in want.items():
+            v = Harmonizer.PATCHES[patch][1]
+            self.assertEqual(semis_of_midi(v[PITCH]), 0)
+            self.assertEqual(tuple(semis_of_midi(v[i]) for i in VOICE),
+                             voices)
+            for k in range(3):
+                db = db_of_midi(v[LEVEL[k]])
+                if levels[k] is None:
+                    self.assertIsNone(db)
+                else:
+                    self.assertLess(abs(db - levels[k]), 0.2)
+            self.assertLess(abs(cents_of_midi(v[DETUNE]) - detune), 0.1)
+            self.assertLess(abs(v[SPREAD] / 127.0 - spread), 0.01)
+            self.assertLess(abs(mix_of_midi(v[MIX]) - mix), 0.01)
+
+    def test_the_lean_patch(self):
+        lean = Harmonizer.PATCHES[6][1]
+        full = Harmonizer.PATCHES[0][1]
+        self.assertEqual(lean[:6], full[:6])
+        self.assertEqual(lean[LEVEL[2]], 0)
+        self.assertEqual(semis_of_midi(full[VOICE[2]]), -12)
+        self.assertEqual(lean[7:], full[7:])
+
+    def test_the_window(self):
+        for ms, want in ((0.0, 5.0), (4.0, 5.0), (30.0, 30.0),
+                         (61.0, 60.0), (float("nan"), 1024.0 / 48.0)):
+            e = self._fresh(window_ms=ms)
+            self.assertEqual(e.window_ms, want)
+            e.set_macro(MIX, 127)
+            e.reset()
+            self.assertEqual(e.window_ms, want)
+            e.deinit()
+
+    def _material(self, rate, channels):
+        return gauss(8192, channels, 6000.0, 7, lead=0)
+
+    def test_mix_0_is_the_input(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                values = gauss(8192, channels, 12000.0, 3, lead=0)
+                y = render(Harmonizer, values, rate, channels,
+                           macros=[(MIX, 0)])
+                self.assertEqual(y, list(values))
+                y = render(Harmonizer, values, rate, channels,
+                           options={"mix": 0.0}, patch=None)
+                self.assertEqual(y, list(values))
+
+    def test_no_latency(self):
+        for rate in (48000, 44100, 22050):
+            for channels in CHANNELS:
+                values = array("h", bytes(2 * 4096 * channels))
+                for c in range(channels):
+                    values[1000 * channels + c] = 20000
+                y = render(Harmonizer, values, rate, channels,
+                           macros=[(LEVEL[k], 0) for k in range(3)])
+                first = min(i for i in range(len(y)) if y[i]) // channels
+                self.assertEqual(first, 1000)
+                e = self._fresh(rate, channels)
+                self.assertEqual(e.latency_samples, 0)
+                e.deinit()
+
+    def test_the_tail(self):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for ms in T4_WINDOWS:
+                    for patch in sorted(Harmonizer.PATCHES):
+                        values = gauss(4096, channels, 4000.0, patch,
+                                       lead=0)
+                        feed = kc.feed(values, rate, channels)
+                        e = Harmonizer(feed.port, sample_rate=rate,
+                                       window_ms=ms)
+                        e.program_change(patch)
+                        tail = e.tail_samples
+                        w = window_frames(ms, rate)
+                        self.assertEqual(tail, w + crossfade(w) + BLOCK)
+                        y = kc.samples(kc.render(e, 4096 + tail + 4096))
+                        last = kc.last_nonzero_frame(y, channels)
+                        self.assertLess(last, 4096 + tail, (rate, ms))
+                        e.set_macro(MIX, 0)
+                        self.assertEqual(e.tail_samples, 0)
+                        e.set_macro(MIX, 64)
+                        for k in range(3):
+                            e.set_macro(LEVEL[k], 0)
+                        self.assertEqual(e.tail_samples, 0)
+                        e.deinit()
+
+    def test_reset_renders_as_fresh(self):
+        """After `reset()` the output is a fresh instance's, fed the same
+        material from that point, byte for byte; at every patch and from
+        Mix 0."""
+        for rate in RATES:
+            for channels in CHANNELS:
+                for patch, start in ((0, None), (3, None), (5, 0)):
+                    values = gauss(16384, channels, 3000.0, 11, lead=0)
+                    cut = 24 * BLOCK
+                    feed = kc.feed(values, rate, channels)
+                    e = Harmonizer(feed.port, sample_rate=rate)
+                    e.program_change(patch)
+                    if start is not None:
+                        e.set_macro(MIX, start)
+                    kc.render(e, cut)
+                    e.reset()
+                    got = kc.samples(kc.render(e, 16384 - cut))
+                    e.deinit()
+                    rest = values[cut * channels:]
+                    fresh = render(Harmonizer, rest, rate, channels)
+                    self.assertEqual(list(got), fresh,
+                                     (rate, channels, patch))
+
+    def test_never_reads_the_tempo(self):
+        calls = []
+
+        def transport():
+            calls.append(1)
+            return (True, 0.0, 140.0, 4, 4)
+        feed = kc.feed(array("h", bytes(4 * BLOCK)), 48000, 1)
+        e = Harmonizer.create(feed.port, 48000, transport=transport)
+        for i in range(10):
+            e.set_macro(i, 100)
+        e.transport_changed()
+        kc.render(e, 1024)
+        e.reset()
+        self.assertEqual(calls, [])
+        self.assertEqual(e.capabilities, ())
+        e.deinit()
+
+    def test_peaks_round_off_above_the_knee(self):
+        for rate in RATES:
+            for amp in (27000, 32000):
+                values = array("h", [int(amp * math.sin(
+                    2.0 * math.pi * 440.0 * i / rate)) for i in range(8192)])
+                y = render(Harmonizer, values, rate, 1, options={
+                    "voice1": 0.0, "level1_db": 0.0, "level2_db": -99.0,
+                    "level3_db": -99.0, "mix": 2.0})
+                w = window_frames(1024.0 / 48.0, rate)
+                lag = crossfade(w)
+                if amp == 27000:
+                    self.assertEqual(y[lag + 64:8192],
+                                     list(values[64:8192 - lag]))
+                else:
+                    peak = max(abs(v) for v in y)
+                    self.assertTrue(28000 < peak < 28600, peak)
+                    self.assertEqual(round(20.0 * math.log10(
+                        28000 / 32768.0), 1), -1.4)
+
+    def test_patch_0_headroom(self):
+        v = Harmonizer.PATCHES[0][1]
+        g_dry, g_wet = gains(mix_of_midi(v[MIX]))
+        total = g_dry + sum(g_wet * 10.0 ** (db_of_midi(v[LEVEL[k]]) / 20.0)
+                            for k in range(3))
+        bound = 32767.0 / total
+        self.assertTrue(13900 <= bound < 14000, bound)
+        self.assertEqual(round(20.0 * math.log10(13900 / 32768.0), 1), -7.4)
+        for rate in RATES:
+            for channels in CHANNELS:
+                for material in (kc.square(16384, channels, 13900, 200),
+                                 kc.clicks(16384, channels, 13900),
+                                 kc.noise(16384, channels, 13900)):
+                    y = render(Harmonizer, material, rate, channels)
+                    self.assertLess(max(abs(s) for s in y), 32767)
+
+
+CLAIMS = (
+    ("Three pitch shifters, each a fixed interval from your note, blended "
+     "under the dry: the rig of three Eventide H910s played from one "
+     "keyboard, so one singer is three-part harmony.",
+     ("T1Independent.test_the_sum_of_the_solos",
+      "T2Intervals.test_pitch_moves_every_voice")),
+    ("Voice 1 to Voice 3 set each voice's interval in whole semitones, an "
+     "octave either way, and Pitch moves all three together, so a voice "
+     "reaches two octaves either way.",
+     ("TheSurface.test_the_spans",
+      "T2Intervals.test_every_voice_1_position",
+      "T2Intervals.test_pitch_moves_every_voice")),
+    ("Level 1 to Level 3 run from -40 to 0 dB, and the bottom step turns "
+     "the voice off.",
+     ("TheSurface.test_the_spans", "T5Balance.test_level",
+      "T6Return.test_the_return", "TheSurface.test_the_tail")),
+    ("Detune pulls voice 1 down and voice 2 up, by up to 25 cents.",
+     ("TheSurface.test_the_spans",
+      "T3SteadyDetune.test_every_eighth_position")),
+    ("Spread pans voice 1 left and voice 2 right; the dry and voice 3 stay "
+     "in the centre.",
+     "T5Balance.test_spread"),
+    ("Mix holds the dry at unity up to 1 while the voices rise to their "
+     "Levels; from 1 to 2 the dry fades, and at 2 the voices play alone.",
+     ("T5Balance.test_mix", "TheSurface.test_the_spans")),
+    ("Constructor values land on the nearest of each knob's 128 steps; "
+     "`window_ms`, 5 to 60 ms (21.33 by default), is fixed for good.",
+     ("TheSurface.test_constructor_values_land_on_the_grid",
+      "TheSurface.test_a_fresh_instance_reads_patch_0",
+      "TheSurface.test_the_window")),
+    ("Each voice is its own machine: turning one on or off never changes "
+     "the dry or the other voices.",
+     "T1Independent.test_the_sum_of_the_solos"),
+    ("Each voice sits on the closest pitch its shifter can make: within 3.4 "
+     "cents of its interval from unison up, 6.8 cents down to an octave "
+     "below and 13.7 cents below that.",
+     ("T2Intervals.test_within_half_a_step",
+      "T2Intervals.test_every_voice_1_position",
+      "T2Intervals.test_pitch_moves_every_voice",
+      "T2Intervals.test_every_patch")),
+    ("So Detune moves in steps of about 7 cents near unison, and voices 1 "
+     "and 2 sit evenly apart only to within a step.",
+     ("T2Intervals.test_detune_moves_in_steps_of_about_7_cents_near_unison",
+      "T3SteadyDetune.test_every_eighth_position")),
+    ("Detune is a steady offset, not a chorus: a voice holds its pitch.",
+     "T3SteadyDetune.test_every_eighth_position"),
+    ("Each voice glitches as it splices, more often the further it is "
+     "shifted and the shorter the window: at the default window a fifth up "
+     "splices every 43 ms, at any sample rate.",
+     ("T4Window.test_the_gap",
+      "T4Window.test_a_fifth_up_splices_every_43_ms")),
+    ("A voice at exact unison never splices: it is a fixed short delay, and "
+     "it combs with the dry.",
+     "T4Window.test_unison_never_splices"),
+    ("A voice you turn back on starts from silence, not with a scrap of "
+     "what it played before.",
+     "T6Return.test_the_return"),
+    ("It moves notes by fixed intervals and does not listen for the key.",
+     ("T2Intervals.test_every_voice_1_position",
+      "T2Intervals.test_every_patch")),
+    ("Each voice rounds off peaks above about -1.4 dBFS.",
+     "TheSurface.test_peaks_round_off_above_the_knee"),
+    ("The voices add to the dry: at patch 0 an input that peaks at or below "
+     "13 900 (-7.4 dBFS) cannot reach full scale.",
+     "TheSurface.test_patch_0_headroom"),
+    ("Patch 6 is patch 0 without the octave below, for a board that cannot "
+     "run three voices in time.",
+     ("TheSurface.test_the_lean_patch", "TheSurface.test_the_patches")),
+    ("On a mono source Spread does nothing.",
+     "T5Balance.test_mono_spread_does_nothing"),
+    ("An interval move leaves each voice's splice where it was.",
+     "DECLARED:Harmonizer,E4-,P4"),
+    ("A control that jumps makes the output step: move it in small steps "
+     "from the host if you need it smooth.",
+     "DECLARED:Harmonizer,E5-,P5"),
+    ("At Mix 0 the output is the input, byte for byte.",
+     "TheSurface.test_mix_0_is_the_input"),
+    ("There is no latency: the dry is a wire, and each shifted voice trails "
+     "it by between the crossfade, a sixteenth of the window, and the whole "
+     "window.",
+     ("TheSurface.test_no_latency",
+      "T4Window.test_a_shifted_voice_trails_by_the_crossfade_to_the_window")),
+    ("`tail_samples` covers the window, the crossfade and one block, and is "
+     "0 at Mix 0 or with every voice off.",
+     "TheSurface.test_the_tail"),
+    ("`reset()` empties the three lines, starts their splices where a new "
+     "instance's start, and returns to patch 0.",
+     "TheSurface.test_reset_renders_as_fresh"),
+    ("The class never reads the host's tempo.",
+     "TheSurface.test_never_reads_the_tempo"),
+)
+
+
+if __name__ == "__main__" and unittest is not None:
+    unittest.main()

From 80557c7046b6b1f7f937e1c2f0b22924fdc746da Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:54:28 -0500
Subject: [PATCH 26/76] Kit: nogb runs the lifecycle events, so it takes the
 lifecycle's options

---
 tests/support/kit.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/support/kit.py b/tests/support/kit.py
index e334df9..b468d7d 100644
--- a/tests/support/kit.py
+++ b/tests/support/kit.py
@@ -47,8 +47,12 @@ def run_check(check, cls, emit=print, quick=False, plants_module=None,
                                options=options)
     if check == "nogb":
         import kit_nogb
+        # nogb runs the lifecycle events, so it takes the lifecycle's
+        # options (a chain without children whose own defects would read
+        # as the class's).
         return kit_nogb.run(cls, emit, quick=quick, name=name,
-                            options=options)
+                            options=kit_options.lifecycle_options_for(
+                                cls.NAME))
     if check == "claims":
         import kit_claims
         return kit_claims.run(cls, emit, module=claims_module,

From d535b5a6974b75bf88e0ad695ff8d5662a833ac2 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 00:58:25 -0500
Subject: [PATCH 27/76] Node matrix: declare the control-jump step on every
 node (the family's ruled disclosure)

---
 tests/support/node_matrix.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
index 16f0d3e..2d8f733 100644
--- a/tests/support/node_matrix.py
+++ b/tests/support/node_matrix.py
@@ -465,5 +465,13 @@ def _apply_macro(self, index, position):
         " behind the control's",
 }
 
+#: Ruled N1 (2026-10-13): a control that jumps steps the output in every
+#: node (no in-node ramp yet; audiocomponents docs/control-smoothing.md),
+#: so P5 is declared for every node adapter.
+for _name in NODES:
+    DECLARED[(_name, "E", "P5")] = (
+        "a control that jumps steps the output; the in-node 20 ms ramp is"
+        " planned, not built (docs/control-smoothing.md)")
+
 import lifecycle  # noqa: E402
 lifecycle.DECLARED.update(DECLARED)

From b17bdf30ff2e124365183cc0a9c616a6e9048bb7 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:00:35 -0500
Subject: [PATCH 28/76] Lifecycle matrix: CircuitPython's MultiTapDelay keeps
 upstream's stray sample on a Time move that audiodsp#241 fixed elsewhere

---
 CHANGELOG.md                   |  2 +-
 tests/test_lifecycle_matrix.py | 22 +++++++++++++++++++---
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82476b6..c583975 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -291,7 +291,7 @@ there, and are recorded in its changelog.
 
 ### Fixed
 
-- A Time brought back after a shorter one no longer plays a stray sample from before the move in MultiTapDelay and the delays built on `audiodelays.Echo`; PitchShifter, Harmonizer and Octaver start again from scratch on a reset and no longer hang on a source with nothing to give; and a host reset that reaches a Mixer inside an effect keeps the audio its voices hold. All of it is audiodsp's, at the pre-release `AUDIODSP_PIN` now names (v0.6.6rc1).
+- A Time brought back after a shorter one no longer plays a stray sample from before the move in MultiTapDelay and the delays built on `audiodelays.Echo` (on CPython and MicroPython; CircuitPython's own `audiodelays` still plays it); PitchShifter, Harmonizer and Octaver start again from scratch on a reset and no longer hang on a source with nothing to give; and a host reset that reaches a Mixer inside an effect keeps the audio its voices hold. All of it is audiodsp's, at the pre-release `AUDIODSP_PIN` now names (v0.6.6rc1).
 
 - The delays, Reverb and ConvolutionReverb now ring out when their source ends, then rest at exact zero, instead of freezing the tail until the source came back; a one-shot source plays once instead of feeding them for ever. A source that comes up short part-way through a block leaves a whole block with the rest silent, and a host `reset_buffer` on ConvolutionReverb keeps the frames it holds. All of it is audiodsp's, at the commit `AUDIODSP_PIN` now names (audiocomponents#127).
 
diff --git a/tests/test_lifecycle_matrix.py b/tests/test_lifecycle_matrix.py
index cce01be..30540ae 100644
--- a/tests/test_lifecycle_matrix.py
+++ b/tests/test_lifecycle_matrix.py
@@ -46,9 +46,25 @@ class this branch carries, on CPython and on the two native interpreters.
 
 #: P6 differences today: class -> (cells whose line differs between CPython
 #: and a native interpreter in the quick matrix, their digest, the same for
-#: the full matrix, reason). Both native interpreters print the same lines
-#: as each other for every class.
-KNOWN_P6 = {}
+#: the full matrix, reason). MicroPython prints CPython's lines for every
+#: class; the entries below are CircuitPython's.
+#:
+#: Restated at audiodsp v0.6.6rc1 (30cbbf6). Up to eb2d20d every class,
+#: MultiTapDelay included, printed the same lines on all three
+#: interpreters, and this table was empty. audiodsp#241 fixed a stray
+#: sample in `audiodelays.MultiTapDelay` (and Echo): a line shortened under
+#: the write head wrote one more sample past its new end, which played out
+#: of the silence when the delay grew back. CPython and MicroPython take the
+#: fix; CircuitPython builds upstream's own audiodelays, which still plays
+#: the sample, as audiodsp's upstream-diff.md records. So E4's Time-to-0
+#: move renders other bytes there, with the same verdicts on P1 to P5.
+KNOWN_P6 = {
+    "MultiTapDelay": (
+        4, "2320dde0", None, None,
+        "Time to 0 and back: CircuitPython's own audiodelays plays one "
+        "stray sample when the line grows back, which audiodsp#241 fixed "
+        "on CPython and MicroPython only"),
+}
 
 #: LIFECYCLE_FULL=1 runs the full matrix (every event at every patch);
 #: otherwise the quick one (lifecycle.run_class(quick=True)).

From f3d6849ed3cd7f404d14ae1030b30af604d1b235 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:09:02 -0500
Subject: [PATCH 29/76] PitchShifter (rebuilt, Phase 6): a splice shifter with
 Pitch, Fine, Mix, Delay and Feedback, each repeat shifted again

---
 CHANGELOG.md                               |    9 +
 lib/audioeffects/rebuilt/pitchshifter.py   |  469 ++++++++
 tests/support/kit_common.py                |   12 +
 tests/support/lifecycle.py                 |   49 +
 tests/test_cpython_effects_pitchshifter.py | 1150 ++++++++++++++++++++
 5 files changed, 1689 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/pitchshifter.py
 create mode 100644 tests/test_cpython_effects_pitchshifter.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..373be4f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,15 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`PitchShifter` (rebuilt, Phase 6):** a fixed-interval splice shifter
+  in the manner of the first harmonizers, on a Pitch, Fine, Mix, Delay and
+  Feedback surface. Pitch moves in whole semitones an octave either way and
+  Fine detunes by up to 50 cents; the dry passes untouched up to Mix 1;
+  Delay holds the shifted voice back up to 112.5 ms; and with Feedback up
+  every repeat is shifted again, so a fifth climbs a fifth at a time.
+  `window_ms` (15 to 60, 30 by default) sets the splice window at
+  construction. The old `semitones=` option is gone: Pitch and Fine
+  replace it.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
new file mode 100644
index 0000000..0d4b00e
--- /dev/null
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -0,0 +1,469 @@
+"""`PitchShifter` - a fixed-interval splice pitch shifter.
+
+The player's text is the class docstring; the `CLAIMS` table in the class's
+test file ties its claim sentences to tests.
+"""
+
+VENDOR = "PyDevices"
+
+import math
+from array import array
+
+import audiocore
+
+from .. import _component
+
+try:
+    from .digitaldelay import laps_to_zero, whole_frames
+except ImportError:                     # pragma: no cover - after it lands
+    from ..digitaldelay import laps_to_zero, whole_frames
+
+try:
+    import audiodelays
+    import audioecho
+    import audiomixer
+    import audioroute
+except ImportError:                     # pragma: no cover - a stock board
+    audiodelays = audioecho = audiomixer = audioroute = None
+
+
+PITCH_I, FINE_I, MIX_I, DELAY_I, FEEDBACK_I = range(5)
+
+#: The Delay and Feedback spans' tops.
+DELAY_MAX_MS = 112.5
+FEEDBACK_MAX = 0.95
+
+#: The shifter's window, in ms: the default and the clamp.
+WINDOW_MS = 30.0
+WINDOW_MIN_MS = 15.0
+WINDOW_MAX_MS = 60.0
+
+#: The line holds Delay's top and a little; the loop holds Delay's top, the
+#: half window and crossfade it adds, and the window its splicer reads over.
+LINE_MS = 120.0
+LOOP_MS = 250.0
+
+#: The frames one pull of the output hands out.
+BLOCK = 256
+
+#: The node's read rate is whole 256ths of unity (`PitchShift.c:121`).
+STEPS = 256
+
+#: The constructor defaults, which NaN falls back to.
+DEFAULTS = (7.0, 0.0, 1.0, 0.0, 0.0)
+
+
+def crossfade_frames(sample_rate):
+    """The shifter's crossfade: 4/3 ms in whole frames, 64 at 48 kHz."""
+    return (int(sample_rate) + 375) // 750
+
+
+def window_frames(window_ms, sample_rate):
+    """The shifter's window in whole frames at the running rate."""
+    return whole_frames(window_ms, sample_rate)
+
+
+def ratio_step(ratio):
+    """The node's read rate nearest `ratio`, in 256ths."""
+    return int(math.floor(ratio * STEPS + 0.5))
+
+
+def step_centre_semitones(step):
+    """Semitones that put the node on `step`: the centre of the step, so
+    the node's truncation lands on it at any float width."""
+    return 12.0 * math.log((step + 0.5) / STEPS) / math.log(2.0)
+
+
+def step_semitones(step):
+    """The step itself in semitones, for the loop; exactly 0 at unity."""
+    if step == STEPS:
+        return 0.0
+    return 12.0 * math.log(float(step) / STEPS) / math.log(2.0)
+
+
+def _option(value, default, low, high):
+    """A constructor option as a float in [low, high]; NaN is the default."""
+    value = float(value)
+    if value != value:
+        return default
+    if value < low:
+        return low
+    if value > high:
+        return high
+    return value
+
+
+def _rint(value):
+    """Round half away from zero."""
+    if value >= 0.0:
+        return int(value + 0.5)
+    return -int(-value + 0.5)
+
+
+class PitchShifter(_component.Component):
+    """Play your part again a fixed interval up or down, a little behind
+    you, the way the first harmonizer boxes did.
+
+    **The controls.** Pitch is the interval in whole semitones, from an
+    octave down to an octave up.
+    Fine detunes it by up to 50 cents either way.
+    The shifter reads in steps of 1/256 of the speed, so Fine moves in steps
+    of about 7 cents near unity and 13.5 near the octave down, and the
+    interval is within 0.5 % of the one Pitch and Fine name.
+    Mix keeps your dry signal at unity up to its centre, 1, with the shifted
+    voice coming up to unity beside it; at 2 you hear the shifted voice
+    alone, and at 0 the output is your input.
+    Delay holds the shifted voice back by up to 112.5 ms.
+    Feedback, up to 0.95, sends the shifted voice round again, and every
+    repeat is shifted once more: at a fifth up the repeats climb a fifth,
+    then a ninth, then a thirteenth.
+
+    **The splice.** The shifter keeps a short memory of what you play, the
+    window, and reads it at the new speed, splicing back to the other end
+    when it runs out.
+    Off unity, each note comes back anywhere from straight away to one
+    window and 1.3 ms late, plus Delay, the delay sweeping and jumping at
+    every splice; at unity it sits still, 1.3 ms late.
+    Shifting down drops slices of what you play; shifting up repeats them.
+    The window is 30 ms unless you pass `window_ms`, 15 to 60, when you
+    build it: a longer window splices less often and arrives later.
+
+    **The dry.** Up to Mix 1 your dry signal passes untouched, sample for
+    sample, with the shifted voice added on top, so a hot input can reach
+    the rail.
+
+    **Mono, latency, tail.** A one-channel source gets a one-channel
+    shifter with the same window.
+    Latency is zero samples: the dry is never delayed.
+    `tail_samples` is an upper bound on how long the output takes to reach
+    exact zero once your input stops, at every Feedback.
+    `reset()` empties the shifter and both delay lines and returns to
+    patch 0.
+    The class never reads the host's tempo.
+
+    **Limits shared by the family.**
+    A control that jumps makes the output step: move it in small steps from
+    the host if you need it smooth.
+    """
+
+    NAME = 'PitchShifter'
+    DISPLAY_NAME = 'Pitch Shifter'
+    CATEGORIES = ('Pitch Shift',)
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioecho", "audioroute")
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    TAIL_SAMPLES = None
+
+    #: Where no patch can reach the rail. At Mix 1 the dry and the shifted
+    #: voice each reach the input's peak, and the repeats add Feedback^n of
+    #: it: 1 + 1 / (1 - 0.5535) = 3.24 times the peak at patches 4 and 5,
+    #: which -10.21 dBFS keeps under full scale. Feedback at its top stacks
+    #: up to 21 times, and the kit declares those cells.
+    INPUT_CEILING_DBFS = -10.5
+
+    MACRO_LABELS = ("Pitch", "Fine", "Mix", "Delay", "Feedback")
+    MACRO_MODES = {
+        0: "BIPOLAR",
+        1: "BIPOLAR",
+        2: "BIPOLAR",
+        3: "UNIPOLAR",
+        4: "UNIPOLAR",
+    }
+    _MACRO_RANGES = (
+        (-12.0, 12.0),                  # 0  Pitch, semitones; plays whole
+        (-50.0, 50.0),                  # 1  Fine, cents
+        (0.0, 2.0),                     # 2  Mix; MIDI 64 is 1.0
+        (0.0, DELAY_MAX_MS),            # 3  Delay, ms
+        (0.0, FEEDBACK_MAX),            # 4  Feedback
+    )
+
+    #: `_component.macro_of` of the card's patch settings.
+    PATCHES = {
+        0: ("Fifth Above", (101, 64, 64, 0, 0)),
+        1: ("Octave Up", (127, 64, 64, 0, 0)),
+        2: ("Octave Down", (0, 64, 64, 0, 0)),
+        3: ("Doubler", (64, 75, 64, 17, 0)),
+        4: ("Rising Fifths", (101, 64, 64, 102, 74)),
+        5: ("Falling Fourths", (37, 64, 64, 113, 74)),
+        6: ("Shifted Only", (101, 64, 127, 0, 0)),
+    }
+
+    def _build(self, pitch=7.0, fine=0.0, mix=1.0, delay_ms=0.0,
+               feedback=0.0, window_ms=WINDOW_MS, patch=None):
+        spans = self._MACRO_RANGES
+        values = tuple(
+            _option(value, DEFAULTS[index], spans[index][0], spans[index][1])
+            for index, value in enumerate(
+                (pitch, fine, mix, delay_ms, feedback)))
+        window_ms = _option(window_ms, WINDOW_MS, WINDOW_MIN_MS,
+                            WINDOW_MAX_MS)
+        rate = self._sample_rate
+        #: The window and the crossfade, in whole frames at this rate.
+        self._window = self._window_frames(window_ms)
+        self._overlap = crossfade_frames(rate)
+        self._ready = False
+        self._wired = False
+        #: Whether the loop's splicer has run since its line was last
+        #: emptied: it then reads half a window later (`_loop_frames`).
+        self._engaged = False
+        self._step = STEPS
+        self._loop_shift = 0.0
+        self._delay_frames = 1
+        self._feedback = 0.0
+        self._build_graph()
+        self._init_macros(values)
+        # Every knob lands on its 0-127 step, as a host would set it, so a
+        # fresh instance reads patch 0 exactly and no constructor value is
+        # kept beside the grid.
+        for index in range(len(values)):
+            span = spans[index]
+            mode = self._mode(index)
+            self._macros[index] = _component.position_of_midi(
+                mode, _component.macro_of(span, values[index], mode))
+        if patch is not None:
+            self.program_change(patch)
+        self._ready = True
+        self._refresh()
+
+    def _build_graph(self):
+        rate = self._sample_rate
+        channels = self._channel_count
+        width = 2 * channels
+        # The borrowed source's only reader: a width-1 MidSide is the source
+        # byte for byte in 256-frame blocks, and it is what Mix 0 hands
+        # back, so a move to or from Mix 0 never skips or repeats a frame.
+        self._head = self._own(audioroute.MidSide(
+            self._source, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        # A MidSide with no source: one block of zeros per pull, which the
+        # shifter and the voices prime from (`_wire`).
+        self._hush = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels),
+            reset=False)
+        self._in = self._own(audioroute.Port(self._hush), reset=False)
+        # A Splitter's ring cannot be rewound; its taps are read in step,
+        # 256 frames a pull each, so it holds nothing between pulls.
+        self._split = self._own(audioroute.Splitter(self._in, taps=2),
+                                reset=False)
+        self._shift = self._own(audiodelays.PitchShift(
+            semitones=step_centre_semitones(STEPS), mix=1.0,
+            window=self._window * width, overlap=self._overlap * width,
+            **self._pcm(BLOCK * width)))
+        self._shift.play(self._split.tap(1))
+        self._line = self._own(audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=channels, max_delay_ms=LINE_MS,
+            delay_frames=1, feedback=0.0, mix=2.0, damping_hz=0.0,
+            cut_hz=0.0), reset=self._clear_line)
+        self._line.play(self._shift)
+        self._loop = self._own(audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=channels, max_delay_ms=LOOP_MS,
+            delay_frames=self._loop_frames(), feedback=0.0, mix=0.0,
+            damping_hz=0.0, cut_hz=0.0,
+            loop_window_ms=self._window * 1000.0 / rate),
+            reset=self._clear_loop)
+        self._loop.play(self._line)
+        # Not reset by the walk: neither voice holds a block between two
+        # pulls (`_wire`), so there is nothing of its own to clear.
+        self._mixer = self._own(audiomixer.Mixer(
+            voice_count=2, buffer_size=BLOCK * width * 2,
+            channel_count=channels, bits_per_sample=16,
+            samples_signed=True, sample_rate=rate), reset=False)
+        # The output: a width-1 MidSide, byte for byte, whose reset forwards
+        # nothing. A host's reset of the output would otherwise reach the
+        # Mixer, and CircuitPython's own Mixer handles that differently from
+        # audiodsp's.
+        self._tail = self._own(audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        self._silence = audiocore.RawSample(
+            array("h", bytes(2 * 2 * channels)), sample_rate=rate,
+            channel_count=channels)
+        #: Where `audiocore.get_buffer` is compiled out, the one-voice
+        #: mixer `_pull` primes from `_tail`; built the first time it is
+        #: needed.
+        self._puller = None
+        self._output = self._head
+
+    def _wire(self):
+        """Play the voices, the first time the output reaches the mixer.
+
+        A voice's `play()`, like the shifter's, primes a block from its
+        source. With the Splitter on `_hush` that block is zeros, and one
+        pull of the mixer hands it out, so wiring takes nothing from the
+        borrowed source and leaves no voice holding a block: a reset or a
+        return from Mix 0 never meets a block a voice is still waiting to
+        play. The level gates are opened first, as
+        `_component.open_level_gates` opens them."""
+        voices = self._mixer.voice
+        self._levels()
+        for voice in voices:
+            voice.play(self._silence, loop=True)
+        self._pull()
+        voices[0].play(self._split.tap(0))
+        voices[1].play(self._loop)
+        self._pull()
+        self._in.play(self._head)
+        self._clear_nodes(only=(self._shift, self._line, self._loop))
+        self._wired = True
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `_tail` and stops: its `play()` primes one block, which pulls
+        the mixer once. `_tail` forwards no reset, so the play rewinds
+        nothing behind it."""
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(self._mixer)
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # smallest that hold a frame.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, buffer_size=16,
+                channel_count=self._channel_count, bits_per_sample=16,
+                samples_signed=True, sample_rate=self._sample_rate),
+                reset=False)
+        voice = self._puller.voice[0]
+        voice.play(self._tail)
+        voice.stop()
+
+    def _clear_line(self):
+        self._line.clear()
+
+    def _clear_loop(self):
+        """Empty the loop. Its splicer goes back to the unshifted read, so
+        its delay is set again for the read it will take."""
+        self._loop.clear()
+        self._engaged = self._loop_shift != 0.0
+        self._loop.set(delay_frames=self._loop_frames())
+
+    # -- the maps ------------------------------------------------------
+
+    def _window_frames(self, window_ms):
+        """The shifter's window in whole frames at the running rate."""
+        return window_frames(window_ms, self._sample_rate)
+
+    def _ratio(self, semitones):
+        """The speed an interval of `semitones` reads at."""
+        return 2.0 ** (semitones / 12.0)
+
+    def _loop_semitones(self, step):
+        """What the loop's splicer is handed: the shifter's own step."""
+        return step_semitones(step)
+
+    def _value(self, index):
+        return _component.macro_value(self._MACRO_RANGES[index],
+                                      self._macros[index])
+
+    def _pitch(self):
+        """Pitch in whole semitones."""
+        pitch = _rint(self._value(PITCH_I))
+        return max(-12, min(12, pitch))
+
+    def _mix(self):
+        return max(0.0, min(2.0, self._value(MIX_I)))
+
+    def macro(self, index):
+        """What macro `index` currently stands for, in its own units; for
+        Pitch, the whole semitones it plays."""
+        self._check_live()
+        if index == PITCH_I:
+            return float(self._pitch())
+        return _component.Component.macro(self, index)
+
+    def _loop_frames(self):
+        """The loop's delay: repeats fall every line delay plus half the
+        window and crossfade, the first pass's mean. Once its splicer has
+        run the loop reads half a window later of its own accord."""
+        frames = self._delay_frames + (self._window + self._overlap) // 2
+        if self._engaged:
+            return frames - self._window * 0.5
+        return frames
+
+    def _levels(self):
+        mix = self._mix()
+        voices = self._mixer.voice
+        voices[0].level = min(1.0, 2.0 - mix)
+        voices[1].level = min(1.0, mix)
+
+    # -- applying ------------------------------------------------------
+
+    def _apply_macro(self, index, position):
+        if self._ready:
+            self._refresh()
+
+    def program_change(self, index, channel=0, note_id=-1,
+                       sample_position=0):
+        """Apply patch `index` whole, then refresh the graph once."""
+        ready = self._ready
+        self._ready = False
+        try:
+            _component.Component.program_change(
+                self, index, channel, note_id, sample_position)
+        finally:
+            self._ready = ready
+        if ready and type(self).PATCHES.get(index) is not None:
+            self._refresh()
+
+    def _refresh(self):
+        rate = self._sample_rate
+        cents = self._pitch() * 100.0 + self._value(FINE_I)
+        step = ratio_step(self._ratio(cents / 100.0))
+        self._step = step
+        self._shift.semitones = step_centre_semitones(step)
+        self._delay_frames = max(1, whole_frames(self._value(DELAY_I), rate))
+        self._line.set(delay_frames=self._delay_frames)
+        feedback = max(0.0, min(FEEDBACK_MAX, self._value(FEEDBACK_I)))
+        self._feedback = feedback
+        self._loop_shift = self._loop_semitones(step)
+        if self._loop_shift != 0.0:
+            self._engaged = True
+        self._loop.set(loop_semitones=self._loop_shift,
+                       delay_frames=self._loop_frames(),
+                       feedback=feedback, mix=feedback)
+        self._route()
+
+    def _route(self):
+        """Point the output at the source's reader at Mix 0, or at the
+        mixer, emptying the shifter and both lines when it comes back."""
+        if self._mix() <= 0.0:
+            self._route_around(self._head)
+            return
+        if not self._wired:
+            self._wire()
+        else:
+            self._levels()
+            self._rejoin()
+        self._output = self._tail
+
+    @property
+    def tail_samples(self):
+        """Frames until the output is exactly zero once the input stops,
+        as an upper bound.
+
+        The shifter hands out what it holds for at most one window and
+        crossfade after its input stops, the line adds its delay, and the
+        loop then goes round `laps_to_zero(Feedback)` times, each lap at
+        most its delay plus the window its splicer reads across, and a frame
+        for the read between two. At Feedback 0 the loop is a wire."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        """`tail_samples` without the liveness check: a plain method, so a
+        subclass can reach it on MicroPython, whose `property` has no
+        `fget`."""
+        if self._mix() <= 0.0:
+            return 0
+        reach = self._delay_frames + self._window + self._overlap + 1
+        if self._feedback <= 0.0:
+            return reach
+        lap = int(math.ceil(self._loop_frames())) + self._window + 2
+        return reach + laps_to_zero(self._feedback) * lap
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0835be1..0e3baf3 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -31,6 +31,18 @@
 DECLARED = {
 }
 
+# PitchShifter at Feedback's top: the repeats stack on the dry, up to 21
+# times the input's peak on a DC, so the rail is reachable below any useful
+# ceiling; the docstring says a hot input can reach it. The square, sine and
+# DC cells there, at every rate and channel count.
+for _material in ("square", "sine", "dc"):
+    for _rate in RATES:
+        for _channels in CHANNELS:
+            DECLARED[("PitchShifter", "ceiling", "%s/%d/%d/m4=127" % (
+                _material, _rate, _channels))] = (
+                "Feedback 0.95 stacks repeats on the dry, up to 21 times the"
+                " input's peak: a hot input reaches the rail by design")
+
 CPYTHON = sys.implementation.name == "cpython"
 
 
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..8204abb 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -75,6 +75,55 @@
 #: cell prints `decl` instead of RED and is counted as a declared exception.
 #: Nothing else skips a cell.
 DECLARED = {
+    # PitchShifter: the splice phase, the ruling's N2. A splice shifter's
+    # output depends on where its read position sits in the window, and
+    # nothing but a fresh start puts two shifters at the same place.
+    ("PitchShifter", "E1-", "P4"):
+        "reset() starts the shifter and the loop's splicer where new ones"
+        " start (audiodsp#240), so the class then plays what a fresh"
+        " instance plays from that point, not what the uninterrupted"
+        " control plays (N2)",
+    ("PitchShifter", "E4-m0=", "P4"):
+        "a Pitch move runs the read position at another speed, so the splice"
+        " phase lands elsewhere; putting it back would click (N2)",
+    ("PitchShifter", "E4-m1=", "P4"):
+        "a Fine move that changes the ratio step moves the splice phase, as"
+        " Pitch does (N2)",
+    ("PitchShifter", "E4-m2=0", "P4"):
+        "a return from Mix 0 starts the shifter and both lines empty, at a"
+        " fresh splice phase, not the uninterrupted control's (N2)",
+    ("PitchShifter", "E5-", "P4"):
+        "a return from Mix 0 starts the shifter and both lines empty, at a"
+        " fresh splice phase, not the uninterrupted control's (N2)",
+    ("PitchShifter", "E9-", "P4"):
+        "a return from Mix 0 starts the shifter and both lines empty, at a"
+        " fresh splice phase, not the uninterrupted control's (N2)",
+    ("PitchShifter", "E6-", "P4"):
+        "a patch with another interval moves the splice phase (N2)",
+    ("PitchShifter", "E11-", "P4"):
+        "moves of the interval or of Mix through 0 before a pull move the"
+        " splice phase (N2)",
+    ("PitchShifter", "E4-m2=", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix)",
+    ("PitchShifter", "E4-m3=", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Delay jumps the line's read)",
+    ("PitchShifter", "E4-m4=", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Feedback)",
+    ("PitchShifter", "E5-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix)",
+    ("PitchShifter", "E6-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (a patch change)",
+    ("PitchShifter", "E9-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix)",
+    ("PitchShifter", "E11-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (Mix and a patch change)",
     ("AnalogDelay", "E", "P5"):
         "a control that jumps steps the output (family, audiocomponents#117);"
         " a Time move bends the pitch while the line walks, by design",
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
new file mode 100644
index 0000000..faf9cea
--- /dev/null
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -0,0 +1,1150 @@
+"""`PitchShifter`'s trait and planted-fault tests.
+
+Four traits: T1 the interval, T2 the splice's arrivals, T3 the repeats
+shifted again, T4 the untouched dry. Each has its measurement, run over the
+cells listed with it, and the same measurement shown red on a planted fault
+of the same kind. `KIT_PLANTS` hands the plants to the kit, which shows
+each one differs from the clean class and that no knob stop or patch
+reproduces it.
+
+Every law a measurement checks against is written out here, never taken
+from the class: the ratio grid, the window and crossfade in frames, the
+Delay and Feedback grids.
+
+The unit tests run a share of each trait's cells; `figures()` runs every
+cell the card names, eight seed sets each, and prints the evidence pack's
+numbers. The module is numpy-free and imports on MicroPython and
+CircuitPython, where `unittest` is absent: the kit reads `KIT_PLANTS`
+there, and running the file with `--figures` prints the figures on
+whichever interpreter runs it:
+
+    MICROPYPATH=lib:tests/support micropython \\
+        tests/test_cpython_effects_pitchshifter.py --figures T1
+"""
+
+import math
+import sys
+from array import array
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                     # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    import os
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.join(_HERE, "..", "lib"))
+except (ImportError, AttributeError, NameError):   # no os.path natively
+    pass
+
+import kit_common as kc                                     # noqa: E402
+from audioeffects import _component                         # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+VENDOR = "PyDevices"
+
+RATES = (48000, 22050)
+CHANNELS = (2, 1)
+WINDOWS = (15.0, 30.0, 60.0)
+BLOCK = 256
+SEEDS = tuple(range(1, 9))
+PITCH_I, FINE_I, MIX_I, DELAY_I, FEEDBACK_I = range(5)
+
+PitchShifter = rebuilt.module_class("PitchShifter")
+
+
+# --------------------------------------------------------------------------
+# The card's laws, written out independently of the class
+
+
+def law_window(window_ms, rate):
+    """The shifter's window in whole frames."""
+    window_ms = min(60.0, max(15.0, window_ms))
+    return int(math.floor(window_ms * rate / 1000.0 + 0.5))
+
+
+def law_overlap(rate):
+    """The crossfade: 4/3 ms in whole frames, 64 at 48 kHz."""
+    return int(math.floor(rate * 4.0 / 3000.0 + 0.5))
+
+
+def law_delay_ms(ms):
+    """Delay on its 0-127 grid, 112.5 ms at the top."""
+    return 112.5 * int(ms * 127.0 / 112.5 + 0.5) / 127.0
+
+
+def law_frames(ms, rate):
+    """The line's delay in whole frames, at least one."""
+    return max(1, int(math.floor(law_delay_ms(ms) * rate / 1000.0 + 0.5)))
+
+
+def law_feedback(feedback):
+    """Feedback on its 0-127 grid, 0.95 at the top."""
+    return 0.95 * int(feedback * 127.0 / 0.95 + 0.5) / 127.0
+
+
+def law_step(pitch, fine=0.0):
+    """The node's read rate nearest the interval, in 256ths."""
+    return int(math.floor(2.0 ** ((pitch + fine / 100.0) / 12.0) * 256 + 0.5))
+
+
+def law_ratio(pitch, fine=0.0):
+    return law_step(pitch, fine) / 256.0
+
+
+def wanted(pitch, fine=0.0):
+    return 2.0 ** ((pitch + fine / 100.0) / 12.0)
+
+
+# --------------------------------------------------------------------------
+# Material and rendering: integer arithmetic, the same on every interpreter
+
+
+class Lcg:
+    def __init__(self, seed):
+        self.state = (seed * 2654435761 + 1) & 0x7FFFFFFF
+
+    def next(self):
+        self.state = (self.state * 1103515245 + 12345) & 0x7FFFFFFF
+        return self.state >> 7
+
+    def uniform(self, low, high):
+        return low + (high - low) * (self.next() % 1000001) / 1000000.0
+
+
+def rint(x):
+    """Round half away from zero."""
+    if x >= 0:
+        return int(x + 0.5)
+    return -int(-x + 0.5)
+
+
+def sine(frames, hz, rate, amp, channels, phase=0.0, start=0):
+    out = array("h", bytes(2 * (start + frames) * channels))
+    w = 2.0 * math.pi * hz / rate
+    for n in range(frames):
+        v = rint(amp * math.sin(w * n + phase))
+        for c in range(channels):
+            out[(start + n) * channels + c] = v
+    return out
+
+
+def render(cls, values, rate, channels, frames, moves=None, **options):
+    """`frames` frames of a fresh instance fed `values` in 256-frame blocks
+    and then silence; `moves` maps a pull index to a callable."""
+    feed = kc.feed(values, rate, channels)
+    e = cls(feed.port, **options)
+    try:
+        return kc.samples(kc.render(e, frames, moves))
+    finally:
+        e.deinit()
+
+
+def first_nonzero(out, channels, lo, hi):
+    """The first frame in [lo, hi) with a non-zero sample, or None."""
+    for n in range(lo, min(hi, len(out) // channels)):
+        for c in range(channels):
+            if out[n * channels + c]:
+                return n
+    return None
+
+
+# --------------------------------------------------------------------------
+# Planted faults
+
+
+class LinearRatio(PitchShifter):
+    """T1: the speed is linear in the interval between the stops,
+    1 + n/12 up and 1 + n/24 down, equal at 0 and +-12."""
+
+    def _ratio(self, semitones):
+        if semitones >= 0.0:
+            return 1.0 + semitones / 12.0
+        return 1.0 + semitones / 24.0
+
+
+class WindowAt48k(PitchShifter):
+    """T2: the window turned into frames at 48 kHz whatever the rate."""
+
+    def _window_frames(self, window_ms):
+        return int(math.floor(window_ms * 48.0 + 0.5))
+
+
+class FlatLoop(PitchShifter):
+    """T3: the loop's splicer is never engaged, so every repeat is the
+    first pass's interval again."""
+
+    def _loop_semitones(self, step):
+        return 0.0
+
+
+class DryThroughShifter(PitchShifter):
+    """T4: the dry is the shifter's own, through its `mix` and its knee,
+    instead of the Splitter's tap."""
+
+    def _levels(self):
+        mix = self._mix()
+        self._shift.mix = min(1.0, mix) * 0.5
+        voices = self._mixer.voice
+        voices[0].level = 0.0
+        voices[1].level = 1.0
+
+
+#: The kit's plant table. T2's plant shows only off 48 kHz; T3's only
+#: where Feedback is up, at the first patch that has it.
+KIT_PLANTS = {
+    "T1": LinearRatio,
+    "T2": (WindowAt48k, None, {"rate": 22050}),
+    "T3": (FlatLoop, 4),
+    "T4": DryThroughShifter,
+}
+
+
+# --------------------------------------------------------------------------
+# T1: the interval
+
+
+T1_PITCHES = (-12, -11, -7, -5, -1, 0, 1, 5, 7, 12)
+T1_CELLS = tuple((p, 0.0) for p in T1_PITCHES) + ((0, -50.0), (0, 50.0))
+
+
+def t1_read(cls, rate, channels, window_ms, pitch, fine):
+    """The measured speed over the wanted one, and the crossings counted.
+
+    A sine whose period divides the window, so a splice jumps whole
+    periods; 0.6 s at Mix 2, Delay 0, Feedback 0, at -12 dBFS; upward zero
+    crossings, interpolated, from 0.1 s."""
+    window = law_window(window_ms, rate)
+    k = max(1, int(200.0 * window / rate + 0.5))
+    hz = k * float(rate) / window
+    amp = rint(32767 * 10.0 ** (-12.0 / 20.0))
+    frames = int(0.6 * rate)
+    values = sine(frames, hz, rate, amp, channels)
+    out = render(cls, values, rate, channels, frames, pitch=pitch,
+                 fine=fine, mix=2.0, window_ms=window_ms)
+    crossings = []
+    for n in range(int(0.1 * rate), frames - 1):
+        a = out[n * channels]
+        b = out[(n + 1) * channels]
+        if a < 0 <= b:
+            crossings.append(n + float(-a) / (b - a))
+    if len(crossings) < 10:
+        return None, len(crossings)
+    measured = (len(crossings) - 1) * rate / (crossings[-1] - crossings[0])
+    return measured / hz / wanted(pitch, fine), len(crossings)
+
+
+def t1_cells(full=False):
+    """(rate, channels, window, pitch, fine). The unit test runs every
+    interval at every rate, channel count and window: 144 short renders."""
+    for rate in RATES:
+        for channels in CHANNELS:
+            for window in WINDOWS:
+                for pitch, fine in T1_CELLS:
+                    yield rate, channels, window, pitch, fine
+
+
+# --------------------------------------------------------------------------
+# T2: the splice's arrivals
+
+
+T2_PITCHES = ((-12, 0.0), (-5, 0.0), (0, 0.0), (7, 0.0), (12, 0.0),
+              (0, 50.0))
+T2_DELAYS = (0.0, 60.0, 100.0)
+
+
+def t2_read(cls, rate, channels, window_ms, pitch, fine, delay_ms, seed,
+            clicks=200):
+    """Each click's arrival, frames after the line's delay, or None for a
+    click that never arrived.
+
+    Single full-scale clicks at random spacings of 1.05 to 1.5 x (W + O),
+    Mix 2, Feedback 0. An arrival is the first non-zero output frame in
+    [click + D, next click + D)."""
+    window = law_window(window_ms, rate)
+    overlap = law_overlap(rate)
+    span = window + overlap
+    delay = law_frames(delay_ms, rate)
+    rng = Lcg(seed * 7919 + rate + channels)
+    at = []
+    n = BLOCK
+    for _ in range(clicks):
+        at.append(n)
+        n += int(rng.uniform(1.05, 1.5) * span)
+    end = n
+    frames = end + delay + 2 * span
+    values = array("h", bytes(2 * frames * channels))
+    for c in at:
+        for ch in range(channels):
+            values[c * channels + ch] = 32767
+    out = render(cls, values, rate, channels, frames, pitch=pitch, fine=fine,
+                 mix=2.0, delay_ms=delay_ms, window_ms=window_ms)
+    arrivals = []
+    for i, c in enumerate(at):
+        nxt = at[i + 1] if i + 1 < len(at) else end
+        hit = first_nonzero(out, channels, c + delay, nxt + delay)
+        arrivals.append(None if hit is None else hit - c - delay)
+    return arrivals
+
+
+def t2_verdict(arrivals, rate, window_ms, pitch, fine):
+    """The card's bars on one seed set: a list of what failed, empty when
+    it holds, and the numbers."""
+    window = law_window(window_ms, rate)
+    overlap = law_overlap(rate)
+    got = [a for a in arrivals if a is not None]
+    fails = []
+    if law_step(pitch, fine) == 256:
+        if len(got) != len(arrivals) or any(a != overlap for a in got):
+            fails.append("unity: not every click exactly D + O late")
+        return fails, {"arrived": len(got) / float(len(arrivals))}
+    ratio = law_ratio(pitch, fine)
+    figures = {"arrived": len(got) / float(len(arrivals))}
+    if not got:
+        return ["no click arrived"], figures
+    late = max(got)
+    early = min(got)
+    figures["max"] = late / (window / max(ratio, 1.0))
+    figures["min"] = early / float(window)
+    figures["past"] = late - (window + overlap)
+    if figures["arrived"] < 0.3:
+        fails.append("arrived %.2f < 0.3" % figures["arrived"])
+    if late > window + overlap:
+        fails.append("an arrival %d past W + O %d" % (late, window + overlap))
+    if late < 0.85 * window / max(ratio, 1.0):
+        fails.append("max %.3f of W / max(r, 1)" % figures["max"])
+    if early > 0.2 * window:
+        fails.append("min %.3f of W" % figures["min"])
+    return fails, figures
+
+
+def t2_cells(full=False):
+    """(rate, channels, window, (pitch, fine), delay, seeds). Every interval
+    and Delay at 48 kHz stereo and the default window; every rate, channel
+    count and window at each interval, Delay rotating. The unit test runs
+    two seed sets a cell and eight at the worst cells the card names; the
+    figures run eight everywhere."""
+    seen = set()
+    for interval in T2_PITCHES:
+        for delay in T2_DELAYS:
+            key = (48000, 2, 30.0, interval, delay)
+            seen.add(key)
+            yield key + ((SEEDS if full else SEEDS[:2]),)
+    turn = 0
+    for rate in RATES:
+        for channels in CHANNELS:
+            for window in WINDOWS:
+                for interval in T2_PITCHES:
+                    delay = T2_DELAYS[turn % 3]
+                    turn += 1
+                    key = (rate, channels, window, interval, delay)
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    worst = (interval == (12, 0.0) and rate == 48000
+                             and window == 60.0)
+                    seeds = SEEDS if (full or worst) else SEEDS[:1]
+                    yield key + (seeds,)
+
+
+# --------------------------------------------------------------------------
+# T3: the repeats, shifted again
+
+
+T3_PITCHES = (-7, -5, 5, 7, 12)
+T3_FEEDBACKS = (0.3, 0.6, 0.9)
+T3_DELAY_MS = 100.0
+CENTS_STEP = 10.0
+
+
+def hann_burst(frames, hz, rate, amp, phase):
+    out = []
+    w = 2.0 * math.pi * hz / rate
+    for n in range(frames):
+        g = 0.5 - 0.5 * math.cos(2.0 * math.pi * n / (frames - 1))
+        out.append(rint(amp * g * math.sin(w * n + phase)))
+    return out
+
+
+def goertzel_power(values, hz, rate):
+    coeff = 2.0 * math.cos(2.0 * math.pi * hz / rate)
+    s1 = s2 = 0.0
+    for x in values:
+        s0 = x + coeff * s1 - s2
+        s2 = s1
+        s1 = s0
+    return s1 * s1 + s2 * s2 - coeff * s1 * s2
+
+
+def strongest(values, low, high, rate):
+    """The frequency in [low, high], 10-cent steps, with the most power."""
+    if low > high:
+        low, high = high, low
+    steps = int(1200.0 * math.log(high / low) / math.log(2.0) / CENTS_STEP)
+    best = None
+    best_hz = low
+    for i in range(steps + 1):
+        hz = low * 2.0 ** (i * CENTS_STEP / 1200.0)
+        p = goertzel_power(values, hz, rate)
+        if best is None or p > best:
+            best = p
+            best_hz = hz
+    return best_hz
+
+
+def t3_read(cls, rate, channels, window_ms, pitch, feedback, seed):
+    """Per pass k = 1, 2, 3: (error in cents from f r^k, energy over one
+    repeat period round its centre).
+
+    A 40 ms Hann sine burst at -8 dBFS, f in 300-600 Hz and a random phase
+    per seed; Mix 2, Delay 100 ms. Pass k's 40 ms gate (Hann-weighted) is
+    centred at the burst's centre + D + (W + O)/2 + (k - 1)(D + (W + O)/2)."""
+    rng = Lcg(seed * 104729 + rate + channels + pitch)
+    hz = rng.uniform(300.0, 600.0)
+    phase = rng.uniform(0.0, 2.0 * math.pi)
+    window = law_window(window_ms, rate)
+    overlap = law_overlap(rate)
+    delay = law_frames(T3_DELAY_MS, rate)
+    period = delay + (window + overlap) / 2.0
+    gate = int(0.04 * rate)
+    start = BLOCK
+    burst = hann_burst(gate, hz, rate, rint(32767 * 10.0 ** (-8.0 / 20.0)),
+                       phase)
+    centre = start + gate / 2.0
+    frames = int(centre + 3.5 * period + gate) + BLOCK
+    values = array("h", bytes(2 * frames * channels))
+    for n, v in enumerate(burst):
+        for c in range(channels):
+            values[(start + n) * channels + c] = v
+    out = render(cls, values, rate, channels, frames, pitch=pitch, mix=2.0,
+                 delay_ms=T3_DELAY_MS, feedback=feedback,
+                 window_ms=window_ms)
+    ratio = law_ratio(pitch)
+    taper = [0.5 - 0.5 * math.cos(2.0 * math.pi * n / (gate - 1))
+             for n in range(gate)]
+    passes = []
+    for k in (1, 2, 3):
+        mid = centre + period * k
+        lo = int(mid - gate / 2.0)
+        piece = [out[(lo + n) * channels] * taper[n] for n in range(gate)]
+        peak = strongest(piece, hz * ratio ** (k - 1), hz * ratio ** (k + 1),
+                         rate)
+        error = 1200.0 * math.log(peak / (hz * ratio ** k)) / math.log(2.0)
+        energy = 0.0
+        for n in range(int(mid - period / 2.0), int(mid + period / 2.0)):
+            for c in range(channels):
+                v = out[n * channels + c]
+                energy += v * v
+        passes.append((error, energy))
+    return passes
+
+
+def t3_verdict(passes, pitch, feedback, window_ms):
+    """The card's bars: each pass nearest r^k, within half the interval;
+    and pass k's energy at least Feedback^(2(k-1)) of pass 1's, less
+    15 dB (pass 2 only at the 60 ms window)."""
+    fails = []
+    bar = abs(pitch) * 50.0
+    played = law_feedback(feedback)
+    first = passes[0][1]
+    levels = []
+    for k, (error, energy) in enumerate(passes, 1):
+        if abs(error) >= bar:
+            fails.append("pass %d %.0f cents off" % (k, error))
+        if k == 1:
+            continue
+        if first <= 0.0:
+            fails.append("pass 1 silent")
+            continue
+        db = 10.0 * math.log(max(energy, 1e-30) / first) / math.log(10.0)
+        want = 20.0 * (k - 1) * math.log(played) / math.log(10.0)
+        levels.append(db - want)
+        if k == 3 and window_ms >= 60.0:
+            continue
+        if db < want - 15.0:
+            fails.append("pass %d %.1f dB below Feedback^%d" % (
+                k, db - want, k - 1))
+    return fails, levels
+
+
+def t3_cells(full=False):
+    """(rate, channels, window, pitch, feedback, seeds). Every interval and
+    Feedback at 48 kHz stereo and the default window; every rate, channel
+    count and window at each interval, Feedback rotating. Two seed sets a
+    cell in the unit test, eight in the figures."""
+    seen = set()
+    for pitch in T3_PITCHES:
+        for feedback in T3_FEEDBACKS:
+            key = (48000, 2, 30.0, pitch, feedback)
+            seen.add(key)
+            yield key + ((SEEDS if full else SEEDS[:2]),)
+    turn = 0
+    for rate in RATES:
+        for channels in CHANNELS:
+            for window in WINDOWS:
+                for pitch in T3_PITCHES:
+                    feedback = T3_FEEDBACKS[turn % 3]
+                    turn += 1
+                    key = (rate, channels, window, pitch, feedback)
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    yield key + ((SEEDS if full else SEEDS[:1]),)
+
+
+# --------------------------------------------------------------------------
+# T4: the dry, untouched
+
+
+T4_MIXES = (0.25, 0.5, 1.0)
+
+
+def t4_material(frames, channels, seed):
+    """A full-scale ramp interleaved, frame by frame, with full-scale
+    noise, each channel its own noise."""
+    rng = Lcg(seed)
+    out = array("h", bytes(2 * frames * channels))
+    for n in range(frames):
+        for c in range(channels):
+            if n % 2 == 0:
+                v = -32768 + (n * 65535) // (frames - 1)
+            else:
+                v = rng.next() % 65536 - 32768
+            out[n * channels + c] = v
+    return out
+
+
+def t4_read(cls, rate, channels, window_ms, mix, pitch, delay_ms, feedback,
+            seed, frames=8192):
+    """The worst |out_m - x - m out_2| over every sample where
+    |x + m out_2| <= 32767, from fresh instances at Mix m and at Mix 2."""
+    values = t4_material(frames, channels, seed)
+    common = dict(pitch=pitch, delay_ms=delay_ms, feedback=feedback,
+                  window_ms=window_ms)
+    out_m = render(cls, values, rate, channels, frames, mix=mix, **common)
+    out_2 = render(PitchShifter, values, rate, channels, frames, mix=2.0,
+                   **common)
+    worst = 0
+    for i in range(frames * channels):
+        x = values[i]
+        wet = mix * out_2[i]
+        if abs(x + wet) > 32767:
+            continue
+        d = abs(out_m[i] - x - wet)
+        if d > worst:
+            worst = d
+    return worst
+
+
+def t4_cells(full=False):
+    """(rate, channels, window, mix, pitch, delay, feedback, seeds)."""
+    for mix in T4_MIXES:
+        for pitch in (-5, 7):
+            for delay in (0.0, 60.0):
+                for feedback in (0.0, 0.6):
+                    yield (48000, 2, 30.0, mix, pitch, delay, feedback,
+                           SEEDS if full else SEEDS[:2])
+    for rate in RATES:
+        for channels in CHANNELS:
+            for window in WINDOWS:
+                if (rate, channels, window) == (48000, 2, 30.0):
+                    continue
+                yield (rate, channels, window, 1.0, 7, 60.0, 0.6,
+                       SEEDS if full else SEEDS[:1])
+
+
+# --------------------------------------------------------------------------
+# Running without `audiocore.get_buffer`
+
+
+def without_get_buffer(build, moves, frames=4096, seed=3, rate=48000,
+                       channels=2, hide=True):
+    """Render with `audiocore.get_buffer` hidden from the class, as on a
+    CircuitPython board build, while it builds and while it moves; with
+    `hide` false, the same render with it in place."""
+    import types
+    from audioeffects.rebuilt import pitchshifter as module
+    real = module.audiocore
+    fake = types.ModuleType("audiocore")
+    for name in dir(real):
+        if name != "get_buffer" or not hide:
+            setattr(fake, name, getattr(real, name))
+
+    def hidden(action):
+        def run(e):
+            module.audiocore = _component.audiocore = fake
+            try:
+                action(e)
+            finally:
+                module.audiocore = _component.audiocore = real
+        return run
+
+    rng = Lcg(seed)
+    values = array("h", [rng.next() % 40001 - 20000
+                         for _ in range(frames * channels)])
+    feed = kc.feed(values, rate, channels)
+    module.audiocore = _component.audiocore = fake
+    try:
+        e = build(feed.port)
+    finally:
+        module.audiocore = _component.audiocore = real
+    try:
+        out = kc.samples(kc.render(
+            e, frames, dict((k, hidden(f)) for k, f in moves.items())))
+    finally:
+        e.deinit()
+    return values, out
+
+
+GET_BUFFER_CASES = (
+    ("built at the defaults", PitchShifter, {}),
+    ("reset before the first pull", PitchShifter, {0: lambda e: e.reset()}),
+    ("reset twice before the first pull", PitchShifter,
+     {0: lambda e: (e.reset(), e.reset())}),
+    ("built at Mix 0, then patch 0", lambda src: PitchShifter(src, mix=0.0),
+     {3: lambda e: e.program_change(0)}),
+    ("built at Mix 0, reset", lambda src: PitchShifter(src, mix=0.0),
+     {3: lambda e: e.reset()}),
+    ("Mix 0 before the first block, back", PitchShifter,
+     {0: lambda e: e.set_macro(MIX_I, 0), 4: lambda e: e.set_macro(MIX_I, 64)}),
+    ("Mix 0 after playing, reset twice", PitchShifter,
+     {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: (e.reset(), e.reset())}),
+    ("a patch change and a reset in one block", PitchShifter,
+     {2: lambda e: (e.program_change(4), e.reset())}),
+)
+
+
+# --------------------------------------------------------------------------
+# The tests
+
+
+class TheSurface(TestCase):
+    def test_macros_patches_tier_latency(self):
+        self.assertEqual(PitchShifter.MACRO_LABELS,
+                         ("Pitch", "Fine", "Mix", "Delay", "Feedback"))
+        self.assertEqual(PitchShifter.MACRO_MODES,
+                         {0: "BIPOLAR", 1: "BIPOLAR", 2: "BIPOLAR",
+                          3: "UNIPOLAR", 4: "UNIPOLAR"})
+        self.assertEqual(PitchShifter.TIER, _component.AUDIODSP)
+        self.assertEqual(PitchShifter.CAPABILITIES, ())
+        self.assertEqual(PitchShifter.LATENCY_SAMPLES, 0)
+
+    def test_the_spans(self):
+        e = PitchShifter(kc.feed(array("h", bytes(16)), 48000, 2).port)
+        try:
+            ends = []
+            for index in range(5):
+                row = []
+                for midi in (0, 64, 127):
+                    e.set_macro(index, midi)
+                    row.append(e.macro(index))
+                ends.append(row)
+            self.assertEqual(ends, [[-12.0, 0.0, 12.0], [-50.0, 0.0, 50.0],
+                                    [0.0, 1.0, 2.0], [0.0, 112.5 * 64 / 127,
+                                                      112.5],
+                                    [0.0, 0.95 * 64 / 127, 0.95]])
+        finally:
+            e.deinit()
+
+    def test_pitch_plays_whole_semitones(self):
+        e = PitchShifter(kc.feed(array("h", bytes(16)), 48000, 2).port)
+        try:
+            reached = set()
+            for midi in range(128):
+                e.set_macro(PITCH_I, midi)
+                value = e.macro(PITCH_I)
+                self.assertEqual(value, float(int(value)))
+                position = _component.position_of_midi("BIPOLAR", midi)
+                exact = -12.0 + 24.0 * position
+                self.assertEqual(value, float(rint(exact)), midi)
+                reached.add(int(value))
+            self.assertEqual(reached, set(range(-12, 13)))
+        finally:
+            e.deinit()
+
+    def test_fine_steps_are_the_ratio_grid(self):
+        # Consecutive Fine positions land on consecutive 256ths, or the
+        # same one: about 7 cents a step near unity, 13.5 near -12.
+        self.assertAlmostEqual(1200.0 * math.log(257.0 / 256) / math.log(2),
+                               6.75, places=2)
+        self.assertAlmostEqual(1200.0 * math.log(129.0 / 128) / math.log(2),
+                               13.47, places=2)
+        for pitch, low, high in ((0, 249, 264), (-12, 124, 132)):
+            e = PitchShifter(kc.feed(array("h", bytes(16)), 48000, 2).port,
+                             pitch=pitch)
+            try:
+                steps = []
+                for midi in range(128):
+                    e.set_macro(FINE_I, midi)
+                    steps.append(e._step)
+                    self.assertEqual(
+                        e._step, law_step(pitch, e.macro(FINE_I)), midi)
+                for a, b in zip(steps, steps[1:]):
+                    self.assertIn(b - a, (0, 1))
+                self.assertEqual((steps[0], steps[-1]), (low, high))
+            finally:
+                e.deinit()
+
+    def test_patches_are_the_card_settings_on_the_grid(self):
+        card = {
+            0: (7, 0, 1, 0, 0), 1: (12, 0, 1, 0, 0), 2: (-12, 0, 1, 0, 0),
+            3: (0, 9, 1, 15, 0), 4: (7, 0, 1, 90, 0.55),
+            5: (-5, 0, 1, 100, 0.55), 6: (7, 0, 2, 0, 0)}
+        for index, values in card.items():
+            want = tuple(
+                _component.macro_of(PitchShifter._MACRO_RANGES[i], values[i],
+                                    PitchShifter.MACRO_MODES[i])
+                for i in range(5))
+            self.assertEqual(PitchShifter.PATCHES[index][1], want, index)
+
+    def test_a_fresh_instance_reads_patch_0(self):
+        e = PitchShifter(kc.feed(array("h", bytes(16)), 48000, 2).port)
+        try:
+            self.assertEqual(tuple(e.get_macro(i) for i in range(5)),
+                             PitchShifter.PATCHES[0][1])
+            self.assertEqual(e.patch_index, 0)
+        finally:
+            e.deinit()
+
+    def test_patches_play_the_same_whatever_the_constructor_said(self):
+        # No constructor value is kept beside the grid, so a patch is the
+        # same on every instance.
+        values = sine(4096, 330.0, 48000, 9000, 2)
+        for patch in sorted(PitchShifter.PATCHES):
+            renders = []
+            for options in ({}, dict(pitch=-3.4, fine=17.3, mix=0.37,
+                                     delay_ms=13.3, feedback=0.71)):
+                renders.append(render(PitchShifter, values, 48000, 2, 8192,
+                                      patch=patch, **options))
+            self.assertEqual(renders[0], renders[1], patch)
+
+    def test_window_ms_is_set_at_construction(self):
+        for rate in (48000, 44100, 22050):
+            for asked, played in ((30.0, 30.0), (15.0, 15.0), (60.0, 60.0),
+                                  (5.0, 15.0), (90.0, 60.0),
+                                  (float("nan"), 30.0)):
+                e = PitchShifter(kc.feed(array("h", bytes(16)), rate, 2).port,
+                                 window_ms=asked)
+                try:
+                    self.assertEqual(e._window, law_window(played, rate))
+                    self.assertEqual(e._overlap, law_overlap(rate))
+                finally:
+                    e.deinit()
+        self.assertEqual(law_overlap(48000), 64)
+
+    def test_mix_0_is_the_input(self):
+        for channels in CHANNELS:
+            rng = Lcg(5)
+            values = array("h", [rng.next() % 65536 - 32768
+                                 for _ in range(4096 * channels)])
+            out = render(PitchShifter, values, 48000, channels, 4096,
+                         mix=0.0)
+            self.assertEqual(out, values)
+            moves = {4: lambda e: e.set_macro(MIX_I, 0)}
+            out = render(PitchShifter, values, 48000, channels, 4096,
+                         moves=moves)
+            self.assertEqual(out[4 * BLOCK * channels:],
+                             values[4 * BLOCK * channels:])
+
+    def test_mix_2_is_the_shifted_voice_alone(self):
+        # At unity the shifted voice is the input D + O frames late, and
+        # nothing else plays: no dry.
+        for rate in RATES:
+            for delay_ms in (0.0, 60.0, 112.5):
+                late = law_frames(delay_ms, rate) + law_overlap(rate)
+                rng = Lcg(9)
+                frames = 8192
+                values = array("h", [rng.next() % 50001 - 25000
+                                     for _ in range(frames * 2)])
+                out = render(PitchShifter, values, rate, 2, frames + late,
+                             pitch=0.0, mix=2.0, delay_ms=delay_ms)
+                self.assertEqual(out[:late * 2], array("h", bytes(4 * late)))
+                self.assertEqual(out[late * 2:], values, (rate, delay_ms))
+
+    def test_a_hot_input_reaches_the_rail_at_mix_1(self):
+        values = sine(8192, 220.0, 48000, 32767, 2)
+        out = render(PitchShifter, values, 48000, 2, 8192, pitch=0.0)
+        self.assertEqual(max(out), 32767)
+        self.assertEqual(min(out), -32768)
+
+    def test_a_mono_source_is_one_channel_of_a_stereo_one(self):
+        for rate in RATES:
+            for options in ({}, dict(patch=4), dict(patch=5, window_ms=15.0),
+                            dict(pitch=-12, mix=1.5, window_ms=60.0)):
+                rng = Lcg(11)
+                mono = array("h", [rng.next() % 40001 - 20000
+                                   for _ in range(8192)])
+                stereo = array("h", bytes(4 * 8192))
+                for n in range(8192):
+                    stereo[2 * n] = stereo[2 * n + 1] = mono[n]
+                a = render(PitchShifter, mono, rate, 1, 16384, **options)
+                b = render(PitchShifter, stereo, rate, 2, 16384, **options)
+                # A Mixer voice at a level below 1 rounds a stereo frame
+                # and a mono one a last bit apart.
+                worst = max(abs(x - y) for x, y in zip(a, b[::2]))
+                self.assertLessEqual(worst, 1, (rate, options))
+                self.assertGreater(max(a), 1000)
+
+    def test_no_latency(self):
+        values = array("h", bytes(4 * 2048))
+        values[2 * 700] = values[2 * 700 + 1] = 12000
+        for patch in sorted(PitchShifter.PATCHES):
+            out = render(PitchShifter, values, 48000, 2, 2048, patch=patch)
+            if patch == 6:
+                # The shifted voice alone has no dry to arrive on time.
+                continue
+            self.assertEqual(out[2 * 700], 12000, patch)
+            self.assertEqual(out[2 * 699], 0, patch)
+        e = PitchShifter(kc.feed(values, 48000, 2).port)
+        try:
+            self.assertEqual(e.latency_samples, 0)
+        finally:
+            e.deinit()
+
+    def test_tail_samples(self):
+        # The bound holds where the output is longest: every patch, and
+        # Feedback at the top with Delay and the window at theirs.
+        cases = [dict(patch=p) for p in sorted(PitchShifter.PATCHES)]
+        cases.append(dict(feedback=0.95, delay_ms=112.5, window_ms=60.0,
+                          pitch=12))
+        cases.append(dict(feedback=0.95, delay_ms=112.5, window_ms=60.0,
+                          pitch=-12))
+        cases.append(dict(feedback=0.95, pitch=0, fine=0.0))
+        for rate in RATES:
+            for options in cases:
+                rng = Lcg(13)
+                frames = 4096
+                values = array("h", [rng.next() % 65536 - 32768
+                                     for _ in range(frames * 2)])
+                feed = kc.feed(values, rate, 2)
+                e = PitchShifter(feed.port, **options)
+                try:
+                    tail = e.tail_samples
+                    stream = kc.Stream(e)
+                    stream.to(frames + tail + 2 * BLOCK)
+                    last = stream.last
+                    self.assertLessEqual(last, frames + tail,
+                                         (rate, options, tail))
+                    self.assertGreater(last, frames, (rate, options))
+                finally:
+                    e.deinit()
+
+    def test_tail_is_zero_at_mix_0(self):
+        e = PitchShifter(kc.feed(array("h", bytes(16)), 48000, 2).port,
+                         mix=0.0)
+        try:
+            self.assertEqual(e.tail_samples, 0)
+        finally:
+            e.deinit()
+
+    def test_reset_empties_the_graph_and_returns_to_patch_0(self):
+        # After a reset the class renders what a fresh instance renders
+        # from that point of the source on.
+        for rate in RATES:
+            for channels in CHANNELS:
+                rng = Lcg(17)
+                frames = 16384
+                values = array("h", [rng.next() % 40001 - 20000
+                                     for _ in range(frames * channels)])
+                at = 12 * BLOCK
+                feed = kc.feed(values, rate, channels)
+                e = PitchShifter(feed.port, patch=5)
+                try:
+                    kc.render(e, at)
+                    e.reset()
+                    self.assertEqual(e.patch_index, 0)
+                    self.assertEqual(
+                        tuple(e.get_macro(i) for i in range(5)),
+                        PitchShifter.PATCHES[0][1])
+                    after = kc.samples(kc.render(e, frames - at))
+                finally:
+                    e.deinit()
+                fresh = render(PitchShifter, values[at * channels:], rate,
+                               channels, frames - at)
+                self.assertEqual(after, fresh, (rate, channels))
+
+    def test_the_tempo_is_never_read(self):
+        reads = []
+
+        def transport():
+            reads.append(1)
+            return (True, 0.0, 120.0, 4, 4)
+
+        e = PitchShifter.create(kc.feed(array("h", bytes(16)), 48000, 2).port,
+                                48000, transport=transport)
+        try:
+            for i in range(5):
+                for v in (0, 64, 127):
+                    e.set_macro(i, v)
+                    e.transport_changed()
+            for patch in PitchShifter.PATCHES:
+                e.program_change(patch)
+            e.reset()
+            self.assertEqual(e.capabilities, ())
+        finally:
+            e.deinit()
+        self.assertEqual(reads, [])
+
+    def test_without_get_buffer_plays_what_it_plays_with_it(self):
+        for channels in CHANNELS:
+            for what, build, moves in GET_BUFFER_CASES:
+                _, plain = without_get_buffer(build, moves, channels=channels,
+                                              hide=False)
+                _, hidden = without_get_buffer(build, moves,
+                                               channels=channels)
+                self.assertEqual(plain, hidden, (what, channels))
+
+
+class T1TheInterval(TestCase):
+    def test_pitch_moves_by_the_semitones_it_reads(self):
+        for rate, channels, window, pitch, fine in t1_cells():
+            ratio, count = t1_read(PitchShifter, rate, channels, window,
+                                   pitch, fine)
+            cell = (rate, channels, window, pitch, fine)
+            self.assertIsNotNone(ratio, (cell, count))
+            self.assertLess(abs(ratio - 1.0), 0.005, cell)
+
+    def test_linear_ratio_is_red(self):
+        for pitch in (7, -5):
+            ratio, _ = t1_read(LinearRatio, 48000, 2, 30.0, pitch, 0.0)
+            self.assertGreater(abs(ratio - 1.0), 0.04, pitch)
+
+
+class T2TheSplice(TestCase):
+    def test_arrivals_drift_between_at_once_and_one_window_late(self):
+        for rate, channels, window, (pitch, fine), delay, seeds in \
+                t2_cells():
+            for seed in seeds:
+                arrivals = t2_read(PitchShifter, rate, channels, window,
+                                   pitch, fine, delay, seed)
+                fails, _ = t2_verdict(arrivals, rate, window, pitch, fine)
+                self.assertEqual(fails, [], (rate, channels, window, pitch,
+                                             fine, delay, seed))
+
+    def test_window_at_48k_is_red(self):
+        arrivals = t2_read(WindowAt48k, 22050, 2, 30.0, 7, 0.0, 0.0, 1)
+        fails, _ = t2_verdict(arrivals, 22050, 30.0, 7, 0.0)
+        self.assertTrue(any("past W + O" in f for f in fails), fails)
+
+
+class T3TheRepeats(TestCase):
+    def test_each_repeat_is_shifted_again(self):
+        for rate, channels, window, pitch, feedback, seeds in t3_cells():
+            for seed in seeds:
+                passes = t3_read(PitchShifter, rate, channels, window,
+                                 pitch, feedback, seed)
+                fails, _ = t3_verdict(passes, pitch, feedback, window)
+                self.assertEqual(fails, [], (rate, channels, window, pitch,
+                                             feedback, seed))
+
+    def test_flat_loop_is_red(self):
+        passes = t3_read(FlatLoop, 48000, 2, 30.0, 7, 0.6, 1)
+        fails, _ = t3_verdict(passes, 7, 0.6, 30.0)
+        self.assertTrue(any(f.startswith("pass 2") for f in fails), fails)
+        self.assertGreater(abs(passes[1][0]), 600.0)
+
+
+class T4TheDry(TestCase):
+    def test_the_dry_is_untouched(self):
+        for rate, channels, window, mix, pitch, delay, feedback, seeds in \
+                t4_cells():
+            for seed in seeds:
+                worst = t4_read(PitchShifter, rate, channels, window, mix,
+                                pitch, delay, feedback, seed)
+                self.assertLessEqual(worst, 2, (rate, channels, window, mix,
+                                                pitch, delay, feedback, seed))
+
+    def test_dry_through_shifter_is_red(self):
+        worst = t4_read(DryThroughShifter, 48000, 2, 30.0, 1.0, 7, 0.0, 0.0,
+                        1)
+        self.assertGreater(worst, 1000)
+
+
+#: Every claim sentence of the class docstring and the test that holds it.
+CLAIMS = (
+    ("Pitch is the interval in whole semitones, from an octave down to an "
+     "octave up.",
+     ("test_the_spans", "test_pitch_plays_whole_semitones")),
+    ("Fine detunes it by up to 50 cents either way.",
+     ("test_the_spans", "test_pitch_moves_by_the_semitones_it_reads")),
+    ("The shifter reads in steps of 1/256 of the speed, so Fine moves in "
+     "steps of about 7 cents near unity and 13.5 near the octave down, and "
+     "the interval is within 0.5 % of the one Pitch and Fine name.",
+     ("test_fine_steps_are_the_ratio_grid",
+      "test_pitch_moves_by_the_semitones_it_reads",
+      "test_linear_ratio_is_red")),
+    ("Mix keeps your dry signal at unity up to its centre, 1, with the "
+     "shifted voice coming up to unity beside it; at 2 you hear the shifted "
+     "voice alone, and at 0 the output is your input.",
+     ("test_the_spans", "test_the_dry_is_untouched",
+      "test_mix_2_is_the_shifted_voice_alone", "test_mix_0_is_the_input")),
+    ("Delay holds the shifted voice back by up to 112.5 ms.",
+     ("test_the_spans", "test_mix_2_is_the_shifted_voice_alone")),
+    ("Feedback, up to 0.95, sends the shifted voice round again, and every "
+     "repeat is shifted once more: at a fifth up the repeats climb a fifth, "
+     "then a ninth, then a thirteenth.",
+     ("test_the_spans", "test_each_repeat_is_shifted_again",
+      "test_flat_loop_is_red")),
+    ("Off unity, each note comes back anywhere from straight away to one "
+     "window and 1.3 ms late, plus Delay, the delay sweeping and jumping at "
+     "every splice; at unity it sits still, 1.3 ms late.",
+     ("test_arrivals_drift_between_at_once_and_one_window_late",
+      "test_window_at_48k_is_red", "test_mix_2_is_the_shifted_voice_alone")),
+    ("The window is 30 ms unless you pass `window_ms`, 15 to 60, when you "
+     "build it: a longer window splices less often and arrives later.",
+     ("test_window_ms_is_set_at_construction",
+      "test_arrivals_drift_between_at_once_and_one_window_late")),
+    ("Up to Mix 1 your dry signal passes untouched, sample for sample, with "
+     "the shifted voice added on top, so a hot input can reach the rail.",
+     ("test_the_dry_is_untouched", "test_dry_through_shifter_is_red",
+      "test_a_hot_input_reaches_the_rail_at_mix_1")),
+    ("A one-channel source gets a one-channel shifter with the same window.",
+     "test_a_mono_source_is_one_channel_of_a_stereo_one"),
+    ("Latency is zero samples: the dry is never delayed.",
+     ("test_no_latency", "test_the_dry_is_untouched")),
+    ("`tail_samples` is an upper bound on how long the output takes to "
+     "reach exact zero once your input stops, at every Feedback.",
+     ("test_tail_samples", "test_tail_is_zero_at_mix_0")),
+    ("`reset()` empties the shifter and both delay lines and returns to "
+     "patch 0.",
+     "test_reset_empties_the_graph_and_returns_to_patch_0"),
+    ("The class never reads the host's tempo.",
+     "test_the_tempo_is_never_read"),
+    ("A control that jumps makes the output step: move it in small steps "
+     "from the host if you need it smooth.",
+     "DECLARED:PitchShifter,E4-m2=,P5"),
+)
+
+
+# --------------------------------------------------------------------------
+# The figures on whichever interpreter runs this file
+
+
+def figures(which=("T1", "T2", "T3", "T4", "L")):
+    """Print each trait's numbers over every cell the card names, eight
+    seed sets each: the evidence pack's rows."""
+    name = sys.implementation.name
+    if "T1" in which:
+        worst = 0.0
+        fewest = None
+        for rate, channels, window, pitch, fine in t1_cells(True):
+            ratio, count = t1_read(PitchShifter, rate, channels, window,
+                                   pitch, fine)
+            worst = max(worst, abs(ratio - 1.0) if ratio else 1.0)
+            fewest = count if fewest is None else min(fewest, count)
+        plant = [t1_read(LinearRatio, 48000, 2, 30.0, p, 0.0)[0] - 1.0
+                 for p in (7, -5)]
+        print("%s|T1|cells 144|worst %.4f %%|fewest crossings %d|plant +7 "
+              "%.2f %% -5 %.2f %%" % (name, 100 * worst, fewest,
+                                      100 * plant[0], 100 * plant[1]))
+    if "T2" in which:
+        cells = fails = 0
+        lo_arrived = 1.0
+        lo_max = 9.0
+        hi_min = 0.0
+        past = None
+        for rate, channels, window, (pitch, fine), delay, seeds in \
+                t2_cells(True):
+            for seed in seeds:
+                arrivals = t2_read(PitchShifter, rate, channels, window,
+                                   pitch, fine, delay, seed)
+                bad, got = t2_verdict(arrivals, rate, window, pitch, fine)
+                cells += 1
+                fails += 1 if bad else 0
+                if bad:
+                    print("%s|T2|RED|%r|%r" % (name, (rate, channels, window,
+                                                      pitch, fine, delay,
+                                                      seed), bad))
+                if "max" in got:
+                    lo_arrived = min(lo_arrived, got["arrived"])
+                    lo_max = min(lo_max, got["max"])
+                    hi_min = max(hi_min, got["min"])
+                    past = got["past"] if past is None else max(past,
+                                                                got["past"])
+        plant = t2_verdict(t2_read(WindowAt48k, 22050, 2, 30.0, 7, 0.0, 0.0,
+                                   1), 22050, 30.0, 7, 0.0)[1]
+        print("%s|T2|renders %d|red %d|fewest arrived %.3f|max a / (W/max(r,"
+              "1)) lowest %.3f|min a / W highest %.3f|latest past W+O %d|"
+              "plant past W+O %d" % (name, cells, fails, lo_arrived, lo_max,
+                                     hi_min, past, plant["past"]))
+    if "T3" in which:
+        cells = fails = 0
+        worst_cents = 0.0
+        worst_db = 99.0
+        cents_at = db_at = None
+        for rate, channels, window, pitch, feedback, seeds in t3_cells(True):
+            for seed in seeds:
+                passes = t3_read(PitchShifter, rate, channels, window, pitch,
+                                 feedback, seed)
+                bad, levels = t3_verdict(passes, pitch, feedback, window)
+                cells += 1
+                fails += 1 if bad else 0
+                if bad:
+                    print("%s|T3|RED|%r|%r" % (name, (rate, channels, window,
+                                                      pitch, feedback, seed),
+                                               bad))
+                cell = (rate, channels, window, pitch, feedback, seed)
+                for error, _ in passes:
+                    if abs(error) / (abs(pitch) * 100.0) > worst_cents:
+                        worst_cents = abs(error) / (abs(pitch) * 100.0)
+                        cents_at = cell
+                for k, level in enumerate(levels, 2):
+                    if k == 3 and window >= 60.0:
+                        continue
+                    if level < worst_db:
+                        worst_db = level
+                        db_at = cell + (k,)
+        plant = t3_read(FlatLoop, 48000, 2, 30.0, 7, 0.6, 1)
+        print("%s|T3|renders %d|red %d|worst error %.1f %% of the interval "
+              "at %r|worst level %.1f dB from Feedback^(k-1) at %r|plant "
+              "pass 2 %.0f cents, pass 3 %.0f" % (
+                  name, cells, fails, 100 * worst_cents, cents_at, worst_db,
+                  db_at, plant[1][0], plant[2][0]))
+    if "L" in which:
+        for rate in (48000, 44100):
+            for channels in CHANNELS:
+                values = array("h", bytes(2 * channels * 4096))
+                for c in range(channels):
+                    values[1000 * channels + c] = 12000
+                dry = render(PitchShifter, values, rate, channels, 4096,
+                             pitch=0.0)
+                wet = render(PitchShifter, values, rate, channels, 4096,
+                             pitch=0.0, mix=2.0)
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                stated = e.latency_samples
+                e.deinit()
+                print("%s|L|%d|%d|latency_samples %d|dry click at +%d|"
+                      "shifted voice at unity, Mix 2, at +%d (D + O = %d)"
+                      % (name, rate, channels, stated,
+                         first_nonzero(dry, channels, 0, 4096) - 1000,
+                         first_nonzero(wet, channels, 0, 4096) - 1000,
+                         law_frames(0.0, rate) + law_overlap(rate)))
+    if "T4" in which:
+        cells = 0
+        worst = 0
+        for rate, channels, window, mix, pitch, delay, feedback, seeds in \
+                t4_cells(True):
+            for seed in seeds:
+                worst = max(worst, t4_read(PitchShifter, rate, channels,
+                                           window, mix, pitch, delay,
+                                           feedback, seed))
+                cells += 1
+        plant = t4_read(DryThroughShifter, 48000, 2, 30.0, 1.0, 7, 0.0, 0.0,
+                        1)
+        print("%s|T4|renders %d|worst %d LSB|plant %d LSB" % (
+            name, cells, worst, plant))
+
+
+if __name__ == "__main__":
+    if unittest is not None and "--figures" not in sys.argv:
+        unittest.main()
+    else:
+        # By name, not as __main__: a plant reads VENDOR from the module
+        # that defines it, and natively __main__ is not one it can find.
+        import test_cpython_effects_pitchshifter as module
+        picked = [a for a in sys.argv[1:] if a[:1] in ("T", "L")]
+        module.figures(tuple(picked) or ("T1", "T2", "T3", "T4", "L"))

From 32c5a0e303e2a13deffe266e7ba986bfe3739063 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:19:33 -0500
Subject: [PATCH 30/76] Octaver: review fixes (Octave 2 on tails, ceiling,
 range, decay, wire)

- Octave 2's divider counts down to Sensitivity's level, moved with it: at
  SubOctave's default threshold (-40 dBFS) it stopped counting on every
  decaying tail and passed Octave 1's pitch. New T4 case on a decaying
  sine; the default threshold is a plant.
- The peak gain is 4.24 times (a square, all three levels at full, Tones
  open): INPUT_CEILING_DBFS is -13, and the test sets all three levels.
- Patch 0 is claimed from E2 to E4. A note with a weak fundamental can drop
  out at A4, mono or stereo, pinned by seed; the cause was not channel
  cancellation.
- The decay is claimed at A2 only: E2's margin sits inside its seed spread.
- The wire keeps every frame on any host buffer size: the source is read
  through a width-1 MidSide that hands 256-frame blocks, the wire hands
  that out, and the Mixer renders 256 frames a pull (it rendered 128).
  A move into the wire before the first pull after arming still skips the
  primed block; the docstring says so. No get_buffer, so boards match.
- The lifecycle matrix runs E5 and E9 on Octave 1 as the Mix; the new
  declared rows say why.
- T1's onset runs all four notes.
---
 lib/audioeffects/rebuilt/octaver.py   | 113 +++++++++-----
 tests/support/lifecycle.py            |  33 ++++
 tests/test_cpython_effects_octaver.py | 212 +++++++++++++++++++-------
 3 files changed, 270 insertions(+), 88 deletions(-)

diff --git a/lib/audioeffects/rebuilt/octaver.py b/lib/audioeffects/rebuilt/octaver.py
index 1aabdab..6b32df0 100644
--- a/lib/audioeffects/rebuilt/octaver.py
+++ b/lib/audioeffects/rebuilt/octaver.py
@@ -100,21 +100,24 @@ class Octaver(_component.Component):
     **What you hear.** The octave is exactly half your note and sounds
     within 2 ms of it.
     Octave 2 is Octave 1 divided again: two octaves down, not a fourth
-    below the note.
-    On low notes, to A2, the octave follows your note's decay within 1 dB:
-    it has no envelope of its own.
+    below the note, until Octave 1 itself stops.
+    On an A2 the octave follows your note's decay within 1 dB: it has no
+    envelope of its own.
     Below Sensitivity the octaves are silent, with no ghost and no hum.
     With the Tones open the octave carries a fifth above it 4.4 dB
     quieter, as the pedal's multiplication does, wherever Tracking is set.
     Turning Tone 1 down thins that fifth more on high notes than on low
     ones.
 
-    **Its range.** At patch 0, on a mono source, every note from low E
-    (E2) to A4 divides cleanly, even with a strong second harmonic.
+    **Its range.** At patch 0 every note from low E (E2) to E4 divides
+    cleanly, even with a strong second harmonic.
     The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.
     Below the range a low note's second harmonic clocks the divider and it
     skips; above it the clock is low-passed under Sensitivity and the
     octave goes silent.
+    At patch 0 a note with a weak fundamental can drop out at A4, mono or
+    stereo: after the clock's low-pass its fundamental is under
+    Sensitivity.
     Between -90 and -84.5 dBFS Sensitivity changes nothing: that whole
     stretch is one step of the clock.
 
@@ -123,16 +126,16 @@ class Octaver(_component.Component):
     A stereo source is clocked on its mid: with the right channel 45
     degrees ahead of the left, the fifth sits 3.2 dB under the octave
     instead of 4.4, on both channels.
-    So near the top of the range a stereo note whose channels cancel each
-    other's fundamental can drop out: one stereo A4 in eight did, at
-    patch 0.
-    The output can peak at 2.8 times the input (a square wave, with Octave
-    2 at full), so keep the input under -9 dBFS.
+    The output can peak at about 4.2 times the input (a square, all three
+    levels at full with the Tones open), so keep the input under -13 dBFS.
     A control that jumps makes the output step: move it in small steps
     from the host if you need it smooth.
 
     **Wire, latency, tail.** With both octaves at 0 and Direct at 1 the
-    output is the input, byte for byte.
+    output is the input, byte for byte, however the host's buffers are
+    cut.
+    Reaching that setting before the first block after an octave comes in
+    skips that one block of 256 frames.
     There is no latency.
     `tail_samples` covers the all-pass and the two Tone filters ringing
     down.
@@ -153,9 +156,9 @@ class Octaver(_component.Component):
     TAIL_SAMPLES = None
 
     #: The worst peak gain over the kit's material, every patch and every
-    #: stop, is 2.75 (a square, Octave 2 at full): -9 dBFS keeps it inside
-    #: full scale.
-    INPUT_CEILING_DBFS = -9.0
+    #: stop, is 4.24 (a square, all three levels at full with the Tones
+    #: open): -13 dBFS keeps it inside full scale.
+    INPUT_CEILING_DBFS = -13.0
 
     MACRO_LABELS = ("Direct", "Octave 1", "Octave 2", "Tracking", "Tone 1",
                     "Tone 2", "Sensitivity")
@@ -198,12 +201,24 @@ def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
             array("h", bytes(2 * 2 * channels)),
             sample_rate=rate, channel_count=channels), reset=False)
 
+        # The input adapter: a width-1 MidSide, the identity byte for byte,
+        # that hands the source on in the palette's 256-frame blocks. The
+        # Splitter reads it, and the wire hands it out, so whatever part of
+        # a source buffer it holds plays next whichever way the output
+        # goes. Handing out the source itself skipped what the adapter, the
+        # Splitter and the dry voice had read ahead whenever the host's
+        # buffers were not 256 frames.
+        self._adapter = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels),
+            reset=False)
+        self._adapter.play(self._source)
+
         # One Splitter, three legs: the dry voice, the signal the octave is
         # made of, and the clock that says when to turn it over. The clock
         # and the signal are kept apart because `SubOctave` clocks on what
         # it divides, so a tracking filter in front of it would darken the
         # octave too (12 dB from E2 to G3, measured on the card's probes).
-        split = self._own(audioroute.Splitter(self._source, taps=3),
+        split = self._own(audioroute.Splitter(self._adapter, taps=3),
                           reset=False)
         self._dry = split.tap(0)
         self._allpass = None
@@ -228,9 +243,12 @@ def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
         self._tone2.play(self._divider2)
 
         # Not reset: the voices keep the source frames they have taken, and
-        # a Mixer reset is no reset of anything this class holds.
+        # a Mixer reset is no reset of anything this class holds. A Mixer
+        # renders half its buffer per pull, so BLOCK frames take four bytes
+        # a sample: with half that, every other pull left a voice holding
+        # half a block, which a move into the wire then skipped.
         self._mixer = self._own(audiomixer.Mixer(
-            voice_count=3, **self._pcm(BLOCK * channels * 2)), reset=False)
+            voice_count=3, **self._pcm(BLOCK * channels * 4)), reset=False)
         self._output = self._mixer
 
         self._init_macros(tuple(
@@ -243,8 +261,6 @@ def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
                 self._macros[i] = position
                 self._apply_macro(i, position)
 
-        _component.open_level_gates(self._mixer, self._mixer.voice,
-                                    self._silence)
         self._ready = True
         self._route()
         if patch is not None:
@@ -326,11 +342,20 @@ def _octave(self, signal, square):
             channel_count=self._channel_count))
 
     def _second(self, tap):
-        """Octave 1's output divided again."""
+        """Octave 1's output divided again, counting down to Sensitivity:
+        at `SubOctave`'s own threshold (0.01, -40 dBFS) it would stop
+        counting on every decaying tail and pass Octave 1's f/2."""
         return self._own(audiomath.SubOctave(
-            tap, order=1, mix=1.0, sample_rate=self._sample_rate,
+            tap, order=1, mix=1.0,
+            threshold=self._threshold2(DEFAULTS[SENS_I]),
+            sample_rate=self._sample_rate,
             channel_count=self._channel_count))
 
+    def _threshold2(self, sensitivity_db):
+        """The second divider's threshold: Sensitivity's own level, so it
+        counts as far down as the clock leg does."""
+        return 10.0 ** (sensitivity_db / 20.0)
+
     def _set_tracking(self, hz):
         if self._allpass is not None:
             self._allpass.frequency = hz
@@ -355,8 +380,9 @@ def _apply_macro(self, index, position):
         elif index == TONE2_I:
             self._tone2.frequency = self._hz(self._value(TONE2_I))
         elif index == SENS_I:
-            self._comparator.set(
-                pre_gain=self._pre_gain(self._value(SENS_I)))
+            sensitivity = self._value(SENS_I)
+            self._comparator.set(pre_gain=self._pre_gain(sensitivity))
+            self._divider2.set(threshold=self._threshold2(sensitivity))
         else:
             self._route()
 
@@ -372,30 +398,43 @@ def _levels(self):
         voices[2].level = self._value(OCTAVE2_I)
 
     def _route(self):
-        """Direct at 1 with both octaves at 0 hands out the source itself;
-        anything else plays the mixer, re-armed if the graph was left."""
+        """Direct at 1 with both octaves at 0 hands out the input adapter,
+        the source byte for byte; anything else plays the mixer, re-armed
+        if the graph was left."""
         if self._is_wire():
-            self._route_around(self._source)
-            self._armed = False
+            self._route_around(self._adapter)
             return
         if not self._ready:
             self._levels()
             return
         if self._rejoin() or not self._armed:
-            # The nodes are clear; the voices still hold the blocks they
-            # had queued. Armed as `_build` arms them: levels, gates,
-            # voices, then the port.
-            self._levels()
-            _component.open_level_gates(self._mixer, self._mixer.voice,
-                                        self._silence)
-            voices = self._mixer.voice
-            voices[0].play(self._dry, loop=True)
-            voices[1].play(self._octave1, loop=True)
-            voices[2].play(self._tone2, loop=True)
+            self._arm()
             self._armed = True
         self._output = self._mixer
         self._levels()
 
+    def _arm(self):
+        """Levels, gates, then the voices, as the graph is first built and
+        whenever it comes back from the wire (its nodes are clear by then).
+
+        A voice's `play()` primes one block from its source, which the next
+        pull plays on time. Between two pulls after that no voice holds a
+        block and every tap is caught up, because the adapter hands
+        256-frame blocks and the Mixer pulls 256 frames: a move into the
+        wire hands out the adapter with nothing left behind. Only a move
+        into the wire before the first pull after arming skips the primed
+        block. Re-arming on the way back, rather than letting the voices
+        carry on, is what keeps that block from playing late, after a
+        stretch of the wire; `audiocore.get_buffer`, which could hand it
+        out at once, is compiled out of CircuitPython's board builds."""
+        self._levels()
+        _component.open_level_gates(self._mixer, self._mixer.voice,
+                                    self._silence)
+        voices = self._mixer.voice
+        voices[0].play(self._dry, loop=True)
+        voices[1].play(self._octave1, loop=True)
+        voices[2].play(self._tone2, loop=True)
+
     @property
     def tail_samples(self):
         """The all-pass and both Tone filters ringing down, end to end."""
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 1142b9f..15b8ed0 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -68,6 +68,7 @@
 #: the macro labelled "Mix".
 MIX_INDEX = {
     "SlapbackDelay": 1,        # "Level": the slap's level; 0 is the dry
+    "Octaver": 1,              # "Octave 1": 0 is the wire at patch 0
 }
 
 #: Where a class cannot satisfy a property by design, it says so HERE, one
@@ -97,6 +98,38 @@
     ("Octaver", "E11-", "P4"):
         "a flip-flop divider keeps its count: moves that add or drop a"
         " crossing leave the octave inverted",
+    ("Octaver", "E5-", "P4"):
+        "a flip-flop divider keeps its count: the clear on the way back"
+        " from the wire (Octave 1 at 0) leaves the octave inverted for good",
+    ("Octaver", "E9-", "P4"):
+        "a flip-flop divider keeps its count: the clear on the way back"
+        " from the wire (Octave 1 at 0) leaves the octave inverted for good",
+    ("Octaver", "E9-", "P1"):
+        "E9's P1 holds the wire from before the first pull: a voice's play()"
+        " primed one block from the source when the graph was armed, so the"
+        " wire starts one block in (disclosed; no audiocore.get_buffer on a"
+        " board build to hand the primed block out)",
+    ("Octaver", "E10-mix0", "P4"):
+        "the wire and back before the first pull: the way back re-arms the"
+        " voices, which skips the block they primed when the graph was"
+        " built, so the run is one block early against the control for good"
+        " (disclosed; no audiocore.get_buffer on a board build to hand the"
+        " primed block out; the same on the class before the wire fix)",
+    ("Octaver", "E", "P1"):
+        "Octave 1 at 0 is the wire only while Octave 2 is at 0 and Direct"
+        " at 1 (the defaults, patches 0, 3 and 4); at patches 1, 2 and 5,"
+        " and through an event that moves Direct or Octave 2 or changes to"
+        " one of those patches, it is a level move, and the output is not"
+        " the source by design. Where it is the wire, P1 holds it from"
+        " before the first pull, and the block the voices primed when the"
+        " graph was built is skipped (disclosed, as E9's row says); E5's"
+        " P1, a move into the wire mid-stream, is ok",
+    ("Octaver", "E5-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (the octave leaves and comes back)",
+    ("Octaver", "E9-", "P5"):
+        "family limit, disclosed (audiocomponents#117): a control that jumps"
+        " makes the output step (the octave leaves and comes back)",
     ("Octaver", "E4-", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step",
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
index 5cd7ca1..79daeb1 100644
--- a/tests/test_cpython_effects_octaver.py
+++ b/tests/test_cpython_effects_octaver.py
@@ -52,11 +52,18 @@
          "G3": 196.0, "B3": 246.9, "E3": 164.8, "A3": 220.0, "E4": 329.6,
          "A4": 440.0, "E5": 659.3}
 
-#: Each patch's tracking window (card T2 and T5).
+#: Each patch's tracking window (card T2).
 WINDOWS = {0: ("E2", "A2", "D3", "G3", "B3", "E4", "A4"),
            3: ("E1", "A1", "E2", "A2", "D3", "G3"),
            4: ("D3", "G3", "B3", "E4", "A4", "E5")}
 
+#: The notes T5 claims clean at each patch. Patch 0 stops at E4: at A4 a
+#: draw with a weak fundamental drops out, mono and stereo
+#: (`T5_DROPOUTS`).
+T5_WINDOWS = {0: ("E2", "A2", "D3", "G3", "B3", "E4"),
+              3: WINDOWS[3],
+              4: WINDOWS[4]}
+
 
 # --------------------------------------------------------------------------
 # The laws, written out
@@ -360,6 +367,26 @@ def t4_split(cls, rate, channels, name, tones_open):
     return level_db(y, f / 4.0, rate) - level_db(y, 0.75 * f, rate)
 
 
+def t4_decay(cls, rate, name, tones_open):
+    """Octave 2's f/4 over its f/2, per 16/f window, on a sine decaying
+    -6 to -86 dBFS over 4 s at Sensitivity -90 dBFS, over every window
+    that ends before Octave 1's last sound (after the first two)."""
+    f = NOTES[name]
+    n = 4 * rate
+    x = [16384.0 * 10.0 ** (-80.0 * i / n / 20.0)
+         * math.sin(2.0 * math.pi * f * i / rate) for i in range(n)]
+    values = pcm(x)
+    tones = OPEN if tones_open else ()
+    sens = ((SENS, 0),)
+    oct1 = render(cls, values, rate, 1, macros=ONLY1 + tones + sens)
+    oct2 = render(cls, values, rate, 1, macros=ONLY2 + tones + sens)
+    last = max(i for i in range(len(oct1)) if oct1[i])
+    width = int(round(16.0 * rate / f))
+    return [level_db(oct2[k * width:(k + 1) * width], f / 4.0, rate)
+            - level_db(oct2[k * width:(k + 1) * width], f / 2.0, rate)
+            for k in range(2, last // width)]
+
+
 def t5_margin(y, f, rate):
     """Octave 1's f/2 over the strongest of f/4, 3f/4, f and 2f."""
     main = level_db(y, f / 2.0, rate)
@@ -512,6 +539,15 @@ def _second(self, tap):
             channel_count=self._channel_count))
 
 
+class DefaultThreshold(Octaver):
+    """T4: Octave 2's divider at `SubOctave`'s default threshold, 0.01
+    (-40 dBFS), whatever Sensitivity says: under it the divider stops
+    counting and passes Octave 1's f/2."""
+
+    def _threshold2(self, sensitivity_db):
+        return 0.01
+
+
 class ClockWire(Octaver):
     """T5: both clock filters taken out of the clock leg."""
 
@@ -532,6 +568,17 @@ def _tone1_hz(self):
         return self._hz(2.0 * Octaver._tone1_hz(self))
 
 
+class DryVoice(Octaver):
+    """Not a plant: the octave voices held at 0 on the mixer's path, so a
+    test can follow the dry through the wire and back byte for byte."""
+
+    def _levels(self):
+        voices = self._mixer.voice
+        voices[0].level = 1.0
+        voices[1].level = 0.0
+        voices[2].level = 0.0
+
+
 KIT_PLANTS = {
     "T1": PitchShiftOctave,
     "T2-held": (HeldAllPass, 3),
@@ -542,6 +589,7 @@ def _tone1_hz(self):
     "T3-wire": WireOctave,
     "T3-bin": OneBinCurve,
     "T4": (FourthBelow, 1),
+    "T4-thresh": (DefaultThreshold, 1),
     "T5": ClockWire,
     "T6": DoubleTone,
 }
@@ -550,10 +598,12 @@ def _tone1_hz(self):
 # --------------------------------------------------------------------------
 # The trait tests (CPython: unittest)
 
-#: T5's one stereo draw that drops out at the top of patch 0's window
-#: (seed 7, at both rates): its mid's fundamental sits under Sensitivity
-#: once the clock filter has taken 55 dB off it.
-T5_STEREO_DROPOUT = (0, "A4", 7)
+#: The draws of R that drop out at A4 at patch 0, at both rates:
+#: (channels, seed). Their fundamentals are the three weakest of seeds 0 to
+#: 39 (67.0 to 67.7 dB re 1 LSB, the median 73.1; stereo seed 7's mid is
+#: as weak as its left channel), and after the clock filter's 55 dB at
+#: 440 Hz they sit under Sensitivity.
+T5_DROPOUTS = ((1, 13), (1, 34), (2, 7))
 
 
 def _within(value, target, tolerance):
@@ -576,7 +626,7 @@ def test_the_pitch_is_half_the_note(self):
     def test_the_onset_is_within_2_ms(self):
         for rate in RATES:
             for channels in (1, 2):
-                for f in (82.41, 110.0, 196.0):
+                for f in self.NOTES_HZ:
                     onset = t1_onset_ms(Octaver, rate, channels, f)
                     self.assertIsNotNone(onset)
                     self.assertLessEqual(onset, 2.0, (rate, channels, f))
@@ -638,11 +688,15 @@ def test_no_mid_side_is_red(self):
 
 
 class T3Dynamics(TestCase):
-    """(a) On R decaying 40 dB at E2 and A2, Octave 1's f/2 tracks the
-    note's f within 1 dB, median at least -20 dB. (b) Once the clock is
-    3 dB under Sensitivity, Octave 1 is 60 dB under the input."""
+    """(a) On R decaying 40 dB at A2, Octave 1's f/2 tracks the note's f
+    within 1 dB, median at least -20 dB. (b) Once the clock is 3 dB under
+    Sensitivity, Octave 1 is 60 dB under the input."""
 
-    ENVELOPE_NOTES = ("E2", "A2")
+    #: A note is claimed where its worst draw clears the 1 dB bar by more
+    #: than the spread between draws. D3's worst draws cross the bar; E2's
+    #: worst of 32 (0.86 dB) clears it by 0.14 against draws from 0.06 to
+    #: 0.86, so neither is claimed. A2's worst of 32 is 0.29.
+    ENVELOPE_NOTES = ("A2",)
 
     def test_the_octave_follows_the_decay(self):
         for rate in RATES:
@@ -688,6 +742,21 @@ def test_two_octaves_down(self):
     def test_a_fourth_below_is_red(self):
         self.assertLess(t4_split(FourthBelow, 48000, 1, "E2", True), 6.0)
 
+    def test_two_octaves_down_as_the_note_dies(self):
+        """A decaying sine: f/4 stays 6 dB over f/2 until Octave 1 stops."""
+        for rate in RATES:
+            for name in ("E2", "A2"):
+                for tones_open in (True, False):
+                    splits = t4_decay(Octaver, rate, name, tones_open)
+                    self.assertGreater(len(splits), 4)
+                    self.assertGreaterEqual(min(splits), 6.0,
+                                            (rate, name, tones_open,
+                                             splits))
+
+    def test_the_default_threshold_is_red(self):
+        splits = t4_decay(DefaultThreshold, 48000, "A2", False)
+        self.assertLess(min(splits), 6.0, splits)
+
 
 class T5Range(TestCase):
     """8/8 draws of R divide cleanly (f/2 20 dB over its neighbours) at
@@ -695,12 +764,8 @@ class T5Range(TestCase):
 
     def _window(self, rate, channels):
         for patch in (0, 3, 4):
-            for name in WINDOWS[patch]:
+            for name in T5_WINDOWS[patch]:
                 clean, low = t5_clean(Octaver, rate, channels, patch, name)
-                if (channels == 2 and (patch, name)
-                        == T5_STEREO_DROPOUT[:2]):
-                    self.assertEqual(clean, 7, (patch, name, rate, low))
-                    continue
                 self.assertEqual(clean, 8, (rate, channels, patch, name,
                                             low))
 
@@ -712,21 +777,19 @@ def test_the_windows_stereo(self):
         for rate in RATES:
             self._window(rate, 2)
 
-    def test_a_stereo_note_can_drop_out_at_the_top(self):
-        patch, name, seed = T5_STEREO_DROPOUT
-        f = NOTES[name]
+    def test_a_weak_fundamental_can_drop_out_at_a4(self):
+        f = NOTES["A4"]
         for rate in RATES:
             n = rate // 2
-            left = rich(f, n, seed, rate)
-            right = rich(f, n, seed, rate, shift=0.3)
-            stereo = render(Octaver, pcm(left, right), rate, 2, patch=patch,
-                            macros=ONLY1)
-            mono = render(Octaver, pcm(left), rate, 1, patch=patch,
-                          macros=ONLY1)
-            self.assertLess(
-                t5_margin(tail_part(channel(stereo, 2)), f, rate), 20.0)
-            self.assertGreaterEqual(t5_margin(tail_part(mono), f, rate),
-                                    20.0)
+            for channels, seed in T5_DROPOUTS:
+                left = rich(f, n, seed, rate)
+                right = rich(f, n, seed, rate, shift=0.3) \
+                    if channels == 2 else None
+                y = render(Octaver, pcm(left, right), rate, channels,
+                           patch=0, macros=ONLY1)
+                self.assertLess(
+                    t5_margin(tail_part(channel(y, channels)), f, rate),
+                    20.0, (rate, channels, seed))
 
     def test_outside_the_window(self):
         rate = 48000
@@ -863,6 +926,44 @@ def test_the_wire_is_the_input(self):
                                     raw[BLOCK * 8 * fsize:BLOCK * 16 * fsize])
                 self.assertEqual(last, raw[BLOCK * 16 * fsize:])
 
+    def test_the_wire_keeps_every_frame(self):
+        """Into the wire and back on a source whose buffers are not the
+        class's 256 frames: every source frame comes out once, on time.
+        Into it before the first pull, the voices' primed block is
+        skipped, and nothing else: the rest comes out once, in order, and
+        that block never plays late. The octave voices are held at 0
+        (`DryVoice`), so the output is the source throughout."""
+        import lifecycle
+        rate = 48000
+        for channels in (1, 2):
+            values = self._material(rate, channels)
+            fsize = 2 * channels
+            raw = bytes(values)
+            for kind in ("100", "256", "300", "1000", "raw"):
+                feed = lifecycle.Feed(values, rate, channels, kind,
+                                      loop=False)
+                e = DryVoice(feed.port, sample_rate=rate)
+                out = kc.render(e, BLOCK * 20)
+                e.set_macro(OCT1, 0)
+                out += kc.render(e, BLOCK * 10)
+                e.set_macro(OCT1, 89)
+                out += kc.render(e, BLOCK * 30)
+                e.deinit()
+                self.assertEqual(out, raw[:len(out)], (channels, kind))
+                # Into the wire before anything was pulled: one block on.
+                feed = lifecycle.Feed(values, rate, channels, kind,
+                                      loop=False)
+                e = DryVoice(feed.port, sample_rate=rate)
+                e.set_macro(OCT1, 0)
+                out = kc.render(e, BLOCK * 10)
+                e.set_macro(OCT1, 89)
+                out += kc.render(e, BLOCK * 10)
+                e.deinit()
+                skip = BLOCK * fsize
+                self.assertEqual(out, raw[skip:skip + len(out)],
+                                 (channels, kind))
+                self.assertEqual(len(out), BLOCK * 20 * fsize)
+
     def test_no_latency(self):
         for rate in (48000, 44100, 22050):
             values = array("h", bytes(2 * 4096))
@@ -962,21 +1063,25 @@ def intermodulation(freqs):
 
     def test_the_peak_gain(self):
         """The kit's square and sine at its own amplitude, at the settings
-        the ceiling found worst and at every patch."""
+        the ceiling found worst, all three levels at full with the Tones at
+        both stops, and at every patch."""
         import kit_ceiling
         rate = 48000
         amp = 3277
         worst = 0.0
-        configs = [(None, k) for k in ((OCT1, 127), (OCT2, 127),
-                                       (TONE1, 0))]
-        configs += [(p, None) for p in sorted(Octaver.PATCHES)]
+        full = ((DIRECT, 127), (OCT1, 127), (OCT2, 127))
+        configs = [(None, (k,)) for k in ((OCT1, 127), (OCT2, 127),
+                                          (TONE1, 0))]
+        configs += [(None, full + ((TONE1, t), (TONE2, t)))
+                    for t in (0, 127)]
+        configs += [(p, ()) for p in sorted(Octaver.PATCHES)]
         for which in ("square", "sine"):
             values = kit_ceiling.material(which, rate, 1, amp)
-            for patch, knob in configs:
+            for patch, knobs in configs:
                 y = render(Octaver, values, rate, 1, patch=patch,
-                           macros=(knob,) if knob else ())
+                           macros=knobs)
                 worst = max(worst, max(abs(v) for v in y) / float(amp))
-        self.assertTrue(2.6 <= worst <= 2.8, worst)
+        self.assertTrue(4.1 <= worst <= 4.3, worst)
         self.assertLessEqual(worst * 10.0 ** (
             Octaver.INPUT_CEILING_DBFS / 20.0), 1.0)
 
@@ -1010,10 +1115,11 @@ def test_the_peak_gain(self):
      ("T1Divider.test_the_pitch_is_half_the_note",
       "T1Divider.test_the_onset_is_within_2_ms")),
     ("Octave 2 is Octave 1 divided again: two octaves down, not a fourth "
-     "below the note.",
-     "T4SecondOctave.test_two_octaves_down"),
-    ("On low notes, to A2, the octave follows your note's decay within "
-     "1 dB: it has no envelope of its own.",
+     "below the note, until Octave 1 itself stops.",
+     ("T4SecondOctave.test_two_octaves_down",
+      "T4SecondOctave.test_two_octaves_down_as_the_note_dies")),
+    ("On an A2 the octave follows your note's decay within 1 dB: it has "
+     "no envelope of its own.",
      "T3Dynamics.test_the_octave_follows_the_decay"),
     ("Below Sensitivity the octaves are silent, with no ghost and no hum.",
      "T3Dynamics.test_silent_below_sensitivity"),
@@ -1024,9 +1130,9 @@ def test_the_peak_gain(self):
     ("Turning Tone 1 down thins that fifth more on high notes than on low "
      "ones.",
      "T6Tone.test_tone_1_is_a_two_pole_low_pass"),
-    ("At patch 0, on a mono source, every note from low E (E2) to A4 "
-     "divides cleanly, even with a strong second harmonic.",
-     "T5Range.test_the_windows_mono"),
+    ("At patch 0 every note from low E (E2) to E4 divides cleanly, even "
+     "with a strong second harmonic.",
+     ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo")),
     ("The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.",
      ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo")),
     ("Below the range a low note's second harmonic clocks the divider and "
@@ -1044,20 +1150,24 @@ def test_the_peak_gain(self):
      "instead of 4.4, on both channels.",
      ("T2Multiplication.test_stereo_45_degrees",
       "T2Multiplication.test_in_phase_stereo_reads_as_mono")),
-    ("So near the top of the range a stereo note whose channels cancel "
-     "each other's fundamental can drop out: one stereo A4 in eight did, "
-     "at patch 0.",
-     ("T5Range.test_a_stereo_note_can_drop_out_at_the_top",
-      "T5Range.test_the_windows_stereo")),
-    ("The output can peak at 2.8 times the input (a square wave, with "
-     "Octave 2 at full), so keep the input under -9 dBFS.",
+    ("At patch 0 a note with a weak fundamental can drop out at A4, mono "
+     "or stereo: after the clock's low-pass its fundamental is under "
+     "Sensitivity.",
+     "T5Range.test_a_weak_fundamental_can_drop_out_at_a4"),
+    ("The output can peak at about 4.2 times the input (a square, all "
+     "three levels at full with the Tones open), so keep the input under "
+     "-13 dBFS.",
      "TheSurface.test_the_peak_gain"),
     ("A control that jumps makes the output step: move it in small steps "
      "from the host if you need it smooth.",
      "DECLARED:Octaver,E4-,P5"),
     ("With both octaves at 0 and Direct at 1 the output is the input, byte "
-     "for byte.",
-     "TheSurface.test_the_wire_is_the_input"),
+     "for byte, however the host's buffers are cut.",
+     ("TheSurface.test_the_wire_is_the_input",
+      "TheSurface.test_the_wire_keeps_every_frame")),
+    ("Reaching that setting before the first block after an octave comes "
+     "in skips that one block of 256 frames.",
+     "TheSurface.test_the_wire_keeps_every_frame"),
     ("There is no latency.", "TheSurface.test_no_latency"),
     ("`tail_samples` covers the all-pass and the two Tone filters ringing "
      "down.",

From 310fa23d49e8b3ecb45cb49074f08d152522b427 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:22:08 -0500
Subject: [PATCH 31/76] Harmonizer: declare the CircuitPython-only E10 cells
 (its PitchShift keeps positions across a reset)

---
 tests/support/lifecycle.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 36ab3d5..96e2e54 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -97,6 +97,15 @@
     ("Harmonizer", "E11-", "P4"):
         "moves that reach an interval, a Level's off step or Mix 0 move the"
         " splices, as E4 to E6",
+    ("Harmonizer", "E10-reset", "P4"):
+        "CircuitPython only: its own audiodelays.PitchShift keeps its read"
+        " and write positions across reset_buffer (audiodsp#240 is in"
+        " audiodsp's port only), so a reset before the first pull cannot"
+        " put the splices back where the constructor left them; CPython"
+        " and MicroPython are ok (ruled a CircuitPython-own difference)",
+    ("Harmonizer", "E10-mix0", "P4"):
+        "CircuitPython only: as E10-reset, the return from Mix 0 empties the"
+        " lines but CircuitPython's PitchShift keeps its positions",
     ("Harmonizer", "E4-", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step",

From 1d4658cb8bb34e8caa6da0036ea6b6e949cac01b Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:25:11 -0500
Subject: [PATCH 32/76] Lifecycle matrix: skip a cell that cannot finish on one
 interpreter; CircuitPython's upstream Echo and pitch nodes at E8

---
 tests/support/LIFECYCLE.md     | 12 +++++++--
 tests/support/lifecycle.py     | 38 +++++++++++++++++++++++++--
 tests/test_lifecycle_matrix.py | 48 +++++++++++++++++++++++++++++++++-
 tests/test_node_matrix.py      |  6 +++--
 4 files changed, 97 insertions(+), 7 deletions(-)

diff --git a/tests/support/LIFECYCLE.md b/tests/support/LIFECYCLE.md
index 69a63bc..0d01f41 100644
--- a/tests/support/LIFECYCLE.md
+++ b/tests/support/LIFECYCLE.md
@@ -105,8 +105,16 @@ free-running LFO) adds a row to `DECLARED` in `lifecycle.py`:
     }
 
 The key is (class `NAME`, event name prefix, property); the cell then prints
-`decl` and counts as a declared exception. Nothing else skips a cell. The
-test file's `KNOWN_RED` is different: it records what is red today, as
+`decl` and counts as a declared exception.
+
+A cell that cannot finish on one interpreter, such as a node there that
+never returns from a pull, is skipped there instead: a row in `SKIP`, keyed
+(class `NAME`, event name prefix, `sys.implementation.name`), makes the cell
+print `na(skip: <reason>)` on every property without building anything, and
+P6 leaves it out. Today's rows are the E8 cells of the three nodes
+CircuitPython takes from upstream's `audiodelays` (Echo, PitchShift and
+GranularPitchShift); a class built on them adds its own. Nothing else skips
+a cell. The test file's `KNOWN_RED` is different: it records what is red today, as
 findings, one row per (class, event prefix, property) with the number and a
 digest of its red cells, so the suite goes red when a cell changes either
 way. The test runs the quick matrix; `LIFECYCLE_FULL=1` runs the full one,
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..129c4d1 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -243,6 +243,25 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (Mix)',
 }
 
+#: Cells that are not run at all on one interpreter, one row per (class or
+#: adapter NAME, event name prefix, `sys.implementation.name`): reason. A
+#: skipped cell prints `na(skip: <reason>)` on every property and builds
+#: nothing. It is for a cell that cannot finish there, such as a node that
+#: never returns from a pull, so that the rest of the matrix still runs; a
+#: cell that finishes and is red belongs in DECLARED or KNOWN_RED instead.
+SKIP = {
+    ("NodeEcho", "E8-", "circuitpython"):
+        "upstream's Echo never returns from a pull on a looped source that"
+        " ends empty; audiodsp#242 fixed it on CPython and MicroPython",
+    ("NodePitchShift", "E8-", "circuitpython"):
+        "upstream's PitchShift never returns from a pull on a looped source"
+        " that ends empty; audiodsp#243 fixed it on CPython and MicroPython",
+    ("NodeGranularPitchShift", "E8-", "circuitpython"):
+        "upstream's GranularPitchShift never returns from a pull on a looped"
+        " source that ends empty; audiodsp#243 fixed it on CPython and"
+        " MicroPython",
+}
+
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
 
 
@@ -1092,6 +1111,16 @@ def e3(cls, rate, channels, patch, options):
     return res
 
 
+def _skip(cls, ev, impl=None):
+    """SKIP's reason for this cell on `impl` (this interpreter by
+    default), or None."""
+    impl = impl or sys.implementation.name
+    for (name, prefix, where), reason in SKIP.items():
+        if name == cls.NAME and where == impl and ev.name.startswith(prefix):
+            return reason
+    return None
+
+
 PROPS = ("P1", "P2", "P3", "P4", "P5")
 
 
@@ -1139,8 +1168,13 @@ def run_class(cls, options=None, rates=RATES, channels=CHANNELS,
                         if only is not None and ev.name.split("-")[0] \
                                 not in only:
                             continue
-                        res = run_cell(cls, ev, rate, ch, patch, options,
-                                       controls)
+                        reason = _skip(cls, ev)
+                        if reason is not None:
+                            res = dict((prop, "na(skip: %s)" % reason)
+                                       for prop in PROPS)
+                        else:
+                            res = run_cell(cls, ev, rate, ch, patch, options,
+                                           controls)
                         line = fmt(name, ev.name, rate, ch, patch, res)
                         emit(line)
                         cells += 1
diff --git a/tests/test_lifecycle_matrix.py b/tests/test_lifecycle_matrix.py
index 30540ae..af364b8 100644
--- a/tests/test_lifecycle_matrix.py
+++ b/tests/test_lifecycle_matrix.py
@@ -31,6 +31,10 @@ class this branch carries, on CPython and on the two native interpreters.
 import lifecycle                                          # noqa: E402
 from audioeffects import rebuilt                          # noqa: E402
 
+#: `_component` reads VENDOR off the module a class is defined in, and the
+#: skip test's plant is defined here.
+VENDOR = "PyDevices"
+
 PHASE5 = ("DigitalDelay", "SlapbackDelay", "TapeDelay", "PingPongDelay",
           "MultiTapDelay", "AnalogDelay", "Reverb", "ConvolutionReverb")
 
@@ -88,6 +92,13 @@ def parse(lines):
     return cells
 
 
+def skipped(props):
+    """True for a cell `lifecycle.SKIP` kept from running: P6 leaves it
+    out, since the interpreter that ran it prints real verdicts."""
+    return props is not None and all(
+        verdict.startswith("na(skip") for prop, verdict in props.items())
+
+
 def red_cells(cells):
     out = set()
     for key, props in cells.items():
@@ -248,7 +259,9 @@ def _p6(self, family):
             ours = parse(self.cpython[name])
             theirs = parse([l for l in got if l.startswith(name + "|")])
             keys = [key for key in sorted(set(ours) | set(theirs))
-                    if ours.get(key) != theirs.get(key)]
+                    if ours.get(key) != theirs.get(key)
+                    and not skipped(theirs.get(key))
+                    and not skipped(ours.get(key))]
             entry = KNOWN_P6.get(name)
             if entry is not None:
                 count, dig = (entry[2], entry[3]) if FULL else entry[:2]
@@ -310,6 +323,39 @@ def test_a_declared_exception_prints_decl(self):
                                     "P1")]
         self.assertEqual(got, "decl")
 
+    def test_a_skipped_cell_prints_na_and_never_runs(self):
+        class Raises(lifecycle.Plain):
+            NAME = "LifecycleRaises"
+
+            def _build(self, *args, **kwargs):
+                raise RuntimeError("the skipped cell ran")
+
+        def e8(emit):
+            lifecycle.run_class(Raises, rates=(48000,), channels=(2,),
+                                patches=[None], only=["E8"], emit=emit)
+
+        # The control: without the row the cell runs, and the plant raises.
+        with self.assertRaises(RuntimeError):
+            e8(lambda line: None)
+        row = ("LifecycleRaises", "E8-", sys.implementation.name)
+        lifecycle.SKIP[row] = "planted skip"
+        try:
+            lines = []
+            e8(lines.append)
+        finally:
+            del lifecycle.SKIP[row]
+        props = parse(lines)[("LifecycleRaises", "E8-end", 48000, 2, "d")]
+        self.assertEqual(props, dict((prop, "na(skip: planted skip)")
+                                     for prop in lifecycle.PROPS))
+        self.assertTrue(skipped(props))
+        # A row for another interpreter leaves the cell to run.
+        lifecycle.SKIP[("LifecycleRaises", "E8-", "elsewhere")] = "planted"
+        try:
+            with self.assertRaises(RuntimeError):
+                e8(lambda line: None)
+        finally:
+            del lifecycle.SKIP[("LifecycleRaises", "E8-", "elsewhere")]
+
     def test_known_red_catches_both_directions(self):
         one = ("X", "E1-a", "P1", 48000, 2, "d")
         two = ("X", "E1-b", "P1", 48000, 2, "d")
diff --git a/tests/test_node_matrix.py b/tests/test_node_matrix.py
index 2c7165b..08019f3 100644
--- a/tests/test_node_matrix.py
+++ b/tests/test_node_matrix.py
@@ -25,7 +25,8 @@
 import lifecycle                                          # noqa: E402
 import node_matrix                                        # noqa: E402
 from tests.test_lifecycle_matrix import (FULL, check_known,  # noqa: E402
-                                   native_binaries, parse, red_cells)
+                                   native_binaries, parse, red_cells,
+                                   skipped)
 
 VENDOR = "PyDevices"
 
@@ -99,7 +100,8 @@ def _p6(self, family):
             ours = parse(self.cpython[name])
             theirs = parse([l for l in got if l.startswith(name + "|")])
             for key in sorted(set(ours) | set(theirs)):
-                if ours.get(key) != theirs.get(key):
+                if ours.get(key) != theirs.get(key) \
+                        and not skipped(theirs.get(key)):
                     problems.append("%s: %s cpython %s, %s %s" % (
                         family, "|".join(map(str, key)), ours.get(key),
                         family, theirs.get(key)))

From 93b1a1dec4973cff3f1b6561366d74969e652188 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:31:19 -0500
Subject: [PATCH 33/76] Harmonizer T1: hold each solo channel to the input's at
 the voice's gain and pan

---
 tests/test_cpython_effects_harmonizer.py | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
index d476cda..71ae744 100644
--- a/tests/test_cpython_effects_harmonizer.py
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -486,7 +486,8 @@ def _empty(self, k):
 
 
 def t1_cell(cls, rate, channels, patch, mix_m, material, seed):
-    """(all-on render, sum of the four solos, solo RMS problems)."""
+    """(all-on render, sum of the four solos, solo RMS problems: a
+    channel more than 3 dB from the input's at the voice's gain and pan)."""
     frames = SETTLE + 2048 + BLOCK
     if material == "noise":
         values = gauss(frames, channels, 2000.0, seed)
@@ -499,18 +500,28 @@ def t1_cell(cls, rate, channels, patch, mix_m, material, seed):
                    macros=base + [(LEVEL[k], 0) for k in range(3)])
     problems = []
     x = list(values)
-    x_rms = rms(x[(SETTLE + BLOCK) * channels:])
+    lo = (SETTLE + BLOCK) * channels
     g_wet = gains(mix_of_midi(mix_m))[1]
+    spread = Harmonizer.PATCHES[patch][1][SPREAD] / 127.0
     for k in range(3):
         if not on[k]:
             continue
         macros = base + [(LEVEL[j], 0) for j in range(3) if j != k]
         solo = render(cls, values, rate, channels, patch=patch,
                       macros=macros, mute_dry=True)
-        want = x_rms * 10.0 ** (db_of_midi(on[k]) / 20.0) * g_wet
-        got = rms(solo[(SETTLE + BLOCK) * channels:])
-        if got <= 0.0 or abs(20.0 * math.log10(got / want)) > 3.0:
-            problems.append((k, got, want))
+        gain = 10.0 ** (db_of_midi(on[k]) / 20.0) * g_wet
+        # Each channel against the input's, at the voice's gain and its
+        # pan: voice 1 sits left of centre and voice 2 right by Spread.
+        pan = (-spread, spread, 0.0)[k] if channels == 2 else 0.0
+        if channels == 2:
+            sides = [m / 32768.0 for m in pan_muls(1.0, pan)]
+        else:
+            sides = [1.0]
+        for c in range(channels):
+            want = rms(chan(x[lo:], channels, c)) * gain * sides[c]
+            got = rms(chan(solo[lo:], channels, c))
+            if got <= 0.0 or abs(20.0 * math.log10(got / want)) > 3.0:
+                problems.append((k, c, got, want))
         total = [a + b for a, b in zip(total, solo)]
     return full, total, problems
 

From 916341e7f49ec9687b693269e75da2d2ea7d8830 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:40:30 -0500
Subject: [PATCH 34/76] ShimmerHall (rebuilt, Phase 6): a pitch shifter around
 the rebuilt Reverb's hall, Bloom and Rise, with its six traits and planted
 faults

---
 CHANGELOG.md                              |   11 +
 lib/audioeffects/rebuilt/shimmerhall.py   |  662 ++++++++++++
 tests/test_cpython_effects_shimmerhall.py | 1198 +++++++++++++++++++++
 3 files changed, 1871 insertions(+)
 create mode 100644 lib/audioeffects/rebuilt/shimmerhall.py
 create mode 100644 tests/test_cpython_effects_shimmerhall.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 437eacd..0b48a96 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,17 @@ there, and are recorded in its changelog.
 
 ### Added
 
+- **`ShimmerHall` (rebuilt, Phase 6):** a pitch shifter around a hall, in
+  two characters. Bloom sends the shifted copy into the hall once, Bloom
+  after you play, on `audiodelays.PitchShift`; Rise puts the shift inside
+  an `audioecho.FeedbackDelay` loop (`loop_semitones`), so each pass comes
+  back shifted again until Damping darkens it away. Nine macros (Character,
+  Shimmer, Rise, Bloom, Interval, Decay, Size, Damping, Mix) and six
+  patches replace the old Shimmer / Echo / Space / Tone surface and its
+  constructor arguments. The hall is the rebuilt `Reverb`. The dry passes
+  untouched up to Mix 1, Mix 0 is a byte-exact wire, and the input ceiling
+  is -24 dBFS. It lives in `lib/audioeffects/rebuilt/shimmerhall.py`, beside
+  the old class in `rack.py`, until it is promoted.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
new file mode 100644
index 0000000..7e11ccd
--- /dev/null
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -0,0 +1,662 @@
+"""`ShimmerHall` - a hall that rings an octave above what you play.
+
+You play into a hall, and a pitch shifter beside it makes the tail ring at
+the Interval you choose. Character picks how it is built. In Bloom the
+shifted copy goes into the hall once, Bloom after you play, and the whole
+hall waits for it. In Rise the shifter sits in a feedback loop: the hall
+starts at once, and each pass comes back shifted again, so the tail climbs
+while Damping darkens every pass until it fades.
+
+Shimmer (0 to 1) is how loud the shifted copy goes into the hall. Bloom (20
+to 800 ms) is the wait in Bloom and the time between passes in Rise. Rise (0
+to 0.9) is how strongly each pass returns, in Rise only. Interval picks one
+of five shifts: -12, -5, +7, +12 or +24 semitones. Decay (0.3 to 10 s), Size
+(0.5 to 1.5) and Damping (500 Hz to 16 kHz) set the hall, and Damping also
+darkens each pass of the loop. Mix (0 to 2) is `audiodelays.Echo`'s: your
+dry signal at unity up to 1, the hall alone at 2.
+
+In Bloom, move Bloom and the shifted copy moves by the same time, within 512
+frames. Its energy centres within 2.5 semitones of the Interval. In Rise the
+loop's short window spreads the first pass wider: within 2.5 semitones at -5
+and +7, 3.5 at +12 and 6 at -12 and +24.
+
+In Rise at +12 each octave arrives one Bloom after the one below, within
+20 %. Moving Rise from 0.3 to 0.9 brings the third pass back 16 to 22 dB
+stronger against the first, and in Bloom Rise changes nothing. With Damping
+at 800 Hz the fourth pass is at least 12 dB weaker against the first than
+at 16 kHz.
+
+Up to Mix 1 your dry signal passes untouched, sample for sample: the
+shimmer is only ever in the hall. At Mix 0 the output is your input, byte
+for byte. Latency is zero. Keep your input at or under -24 dBFS: with
+Decay, Size, Shimmer and Rise at the top, a steady loud input fills the
+hall to the rail.
+
+`tail_samples` bounds how long the output takes to reach exact zero once
+your input stops. `reset()` empties the hall, the line and the shifter, and
+restores patch 0.
+
+The patches: Octave Bloom (the defaults), Short Stagger, Fifth Halo, Slow
+Rise, Rise Damped, Falling Octaves.
+
+**Limits**
+
+A control that jumps makes the output step: move it in small steps from the
+host if you need it smooth.
+
+Moving Character or Size empties the hall: the tail drops and the dry
+carries on.
+
+Interval is a fixed shift in semitones, with no key awareness. Both
+shifters splice, so the shifted copy has a slight flutter. At a lower sample
+rate the band ends lower, so the climb reaches the top of it sooner. A mono source
+gets a mono rack. It needs a board with PSRAM.
+
+A value outside a macro's span clamps to the nearer stop, and NaN takes the
+default; an `interval` other than the five raises `ValueError`.
+"""
+
+VENDOR = "PyDevices"
+
+import math
+from array import array
+
+import audiocore
+
+from .. import _component
+
+try:
+    from .digitaldelay import laps_to_zero, whole_frames
+except ImportError:                     # pragma: no cover - after it lands
+    from ..digitaldelay import laps_to_zero, whole_frames
+try:
+    from .tapedelay import tone_excess
+except ImportError:                     # pragma: no cover - after it lands
+    from ..tapedelay import tone_excess
+# The module, not the class: a Component class at this module's top level
+# would be listed as a second provider here (`rebuilt.known()`).
+try:
+    from . import reverb as _reverb
+except ImportError:                     # pragma: no cover - after it lands
+    from .. import reverb as _reverb
+
+try:
+    import audioecho
+except ImportError:                     # pragma: no cover - a stock board
+    audioecho = None
+try:
+    import audiodelays
+except ImportError:                     # pragma: no cover - a stock board
+    audiodelays = None
+try:
+    import audioroute
+except ImportError:                     # pragma: no cover - a stock board
+    audioroute = None
+try:
+    import audiomixer
+except ImportError:                     # pragma: no cover - a stock board
+    audiomixer = None
+
+
+#: Frames per pull: the palette's block.
+BLOCK = 256
+
+(CHARACTER_I, SHIMMER_I, RISE_I, BLOOM_I, INTERVAL_I, DECAY_I, SIZE_I,
+ DAMPING_I, MIX_I) = range(9)
+
+CHARACTERS = ("bloom", "rise")
+
+#: Interval's five zones, in semitones, low to high on the 0-127 grid.
+INTERVALS = (-12, -5, 7, 12, 24)
+
+#: Where each zone sits on the grid when the constructor or a patch names it.
+INTERVAL_MIDI = (0, 32, 64, 96, 127)
+
+RISE_MAX = 0.9
+
+#: Bloom's shifter: its window and crossfade, in ms.
+WINDOW_MS = 40.0
+OVERLAP_MS = 10.0
+
+#: Rise's shifter: the loop's window. A shifted loop reads half of it late
+#: (`docs/upstream-diff.md`, `loop_semitones`), so Rise's line is set that
+#: much short of Bloom.
+LOOP_WINDOW_MS = 25.0
+
+#: The line: Bloom's top plus the loop window, the furthest a shifted tap
+#: reads.
+LINE_MS = 800.0 + LOOP_WINDOW_MS
+
+#: `audiodelays.PitchShift` reads in whole 256ths of unity
+#: (`PitchShift.c:121`), rounding down.
+STEPS = 256
+
+#: Each macro's patch-0 step; the constructor defaults are these steps'
+#: values, so a fresh instance is patch 0.
+DEFAULT_STEPS = (0, 89, 85, 90, 96, 94, 64, 91, 32)
+
+
+def _default(index, span):
+    return _component.macro_value(
+        span, _component.position_of_midi("UNIPOLAR", DEFAULT_STEPS[index]))
+
+
+#: The constructor defaults: each patch-0 step's value. NaN falls back to
+#: these.
+SHIMMER = _default(1, (0.0, 1.0))
+RISE = _default(2, (0.0, RISE_MAX))
+BLOOM_MS = _default(3, (20.0, 800.0, "log"))
+DECAY = _default(5, (0.3, 10.0, "log"))
+SIZE = _default(6, (0.5, 1.5))
+DAMPING_HZ = _default(7, (500.0, 16000.0, "log"))
+MIX = _default(8, (0.0, 2.0))
+DEFAULTS = (0.0, SHIMMER, RISE, BLOOM_MS, _default(4, (0.0, 5.0)), DECAY,
+            SIZE, DAMPING_HZ, MIX)
+
+#: The hall's macros the rack drives, by `Reverb`'s labels.
+_HALL_DECAY_I = _reverb.Reverb.MACRO_LABELS.index("Decay")
+_HALL_SIZE_I = _reverb.Reverb.MACRO_LABELS.index("Size")
+_HALL_DAMPING_I = _reverb.Reverb.MACRO_LABELS.index("Damping")
+
+#: Which of the rack's macros drive which of the hall's.
+_HALL_MACROS = ((DECAY_I, _HALL_DECAY_I), (SIZE_I, _HALL_SIZE_I),
+                (DAMPING_I, _HALL_DAMPING_I))
+
+
+def _hall_patch():
+    """The hall at the rack's patch 0, on `Reverb`'s grid: Concert Hall's
+    Diffusion, Bandwidth, Low Cut, Mod Depth, Mod Rate, Width and Tone, the
+    hall character, no Predelay (Bloom is the predelay), the tail alone,
+    and the rack's own Decay, Size and Damping steps."""
+    concert = None
+    for _index, (name, values) in _reverb.Reverb.PATCHES.items():
+        if name == "Concert Hall":
+            concert = list(values)
+    labels = _reverb.Reverb.MACRO_LABELS
+    concert[labels.index("Character")] = 127
+    concert[labels.index("Predelay")] = 0
+    concert[labels.index("Mix")] = 127
+    for ours, theirs in _HALL_MACROS:
+        concert[theirs] = DEFAULT_STEPS[ours]
+    return tuple(concert)
+
+
+HALL_PATCH = _hall_patch()
+
+
+def _hall_options():
+    """`Reverb`'s constructor options at `HALL_PATCH`'s grid values."""
+    spans = _reverb.Reverb._MACRO_RANGES
+    names = ("decay", "size", "predelay_ms", "diffusion", "damping_hz",
+             "bandwidth_hz", "low_cut_hz", "mod_depth_ms", "mod_rate_hz",
+             "width", "tone_db", "mix")
+    options = {"character": "hall"}
+    for index, name in zip(range(1, 13), names):
+        mode = _reverb.Reverb.MACRO_MODES.get(index, "UNIPOLAR")
+        position = _component.position_of_midi(mode, HALL_PATCH[index])
+        options[name] = _component.macro_value(spans[index], position)
+    return options
+
+
+def step_centre_semitones(step):
+    """Semitones that put `audiodelays.PitchShift` on `step`: the centre of
+    the step, so the node's truncation lands on it at any float width."""
+    return 12.0 * math.log((step + 0.5) / STEPS) / math.log(2.0)
+
+
+def interval_step(semitones):
+    """The shifter's read rate nearest `semitones`, in 256ths."""
+    return int(math.floor(2.0 ** (semitones / 12.0) * STEPS + 0.5))
+
+
+def _option(value, default):
+    """A constructor option as a float; NaN is the option's default."""
+    value = float(value)
+    if value != value:
+        return default
+    return value
+
+
+def _between(value, low, high):
+    if value < low:
+        return low
+    if value > high:
+        return high
+    return value
+
+
+class ShimmerHall(_component.Component):
+    """A pitch shifter around a hall. The module docstring is the player's
+    page."""
+
+    NAME = 'ShimmerHall'
+    DISPLAY_NAME = 'Shimmer Hall'
+    CATEGORIES = ('Effect Rack', 'Reverb')
+    VERSION = '0.1.0'
+
+    TIER = _component.AUDIODSP
+    REQUIRES = ("audioroute", "audioecho", "audioverb")
+
+    CAPABILITIES = ()
+    LATENCY_SAMPLES = 0
+    INPUT_CEILING_DBFS = -24.0
+    TAIL_SAMPLES = None
+
+    MACRO_LABELS = ("Character", "Shimmer", "Rise", "Bloom", "Interval",
+                    "Decay", "Size", "Damping", "Mix")
+    MACRO_MODES = {
+        0: "TOGGLE",
+        1: "UNIPOLAR",
+        2: "UNIPOLAR",
+        3: "UNIPOLAR",
+        4: "UNIPOLAR",
+        5: "UNIPOLAR",
+        6: "UNIPOLAR",
+        7: "UNIPOLAR",
+        8: "UNIPOLAR",
+    }
+    _MACRO_RANGES = (
+        (0.0, 1.0),                     # 0 Character: Bloom < 0.5 <= Rise
+        (0.0, 1.0),                     # 1 Shimmer
+        (0.0, RISE_MAX),                # 2 Rise, the loop's feedback
+        (20.0, 800.0, "log"),           # 3 Bloom, ms
+        (0.0, 5.0),                     # 4 Interval, zone min(4, int(v))
+        (0.3, 10.0, "log"),             # 5 Decay, s (the hall's)
+        (0.5, 1.5),                     # 6 Size (the hall's)
+        (500.0, 16000.0, "log"),        # 7 Damping, Hz
+        (0.0, 2.0),                     # 8 Mix; dry at unity to 1
+    )
+
+    #: `_component.macro_of` of the card's settings.
+    PATCHES = {
+        0: ("Octave Bloom", DEFAULT_STEPS),
+        1: ("Short Stagger", (0, 76, 85, 38, 96, 77, 38, 102, 25)),
+        2: ("Fifth Halo", (0, 102, 85, 103, 64, 108, 89, 84, 38)),
+        3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 102, 38)),
+        4: ("Rise Damped", (127, 102, 113, 87, 96, 94, 64, 51, 32)),
+        5: ("Falling Octaves", (127, 89, 85, 93, 0, 102, 64, 76, 32)),
+    }
+
+    def _build(self, character="bloom", shimmer=SHIMMER, rise=RISE,
+               bloom_ms=BLOOM_MS, interval=12, decay=DECAY, size=SIZE,
+               damping_hz=DAMPING_HZ, mix=MIX, patch=None):
+        if character not in CHARACTERS:
+            raise ValueError("character must be 'bloom' or 'rise', not %r"
+                             % (character,))
+        if isinstance(interval, bool) or interval not in INTERVALS:
+            raise ValueError("interval must be one of %r semitones"
+                             % (INTERVALS,))
+        spans = self._MACRO_RANGES
+        defaults = DEFAULTS
+        options = (None, shimmer, rise, bloom_ms, None, decay, size,
+                   damping_hz, mix)
+        # A default lands on its own 0-127 step, so a fresh instance reads
+        # patch 0 exactly. Any other value is kept as the knob's position,
+        # between steps if it falls there, as a host with finer resolution
+        # than MIDI would set it: it is the knob, not a value kept beside
+        # it, so a patch or a move replaces it.
+        positions = [1.0 if character == "rise" else 0.0]
+        for index in range(1, len(spans)):
+            if index == INTERVAL_I:
+                positions.append(_component.position_of_midi(
+                    "UNIPOLAR", INTERVAL_MIDI[INTERVALS.index(interval)]))
+                continue
+            span = spans[index]
+            value = _between(_option(options[index], defaults[index]),
+                             span[0], span[1])
+            if value == defaults[index]:
+                positions.append(_component.position_of_midi(
+                    "UNIPOLAR", DEFAULT_STEPS[index]))
+            else:
+                positions.append(_component.macro_position(span, value))
+
+        rate = self._sample_rate
+        channels = self._channel_count
+        width = 2 * channels
+        #: True once the macros are seeded; until then nothing is pushed.
+        self._ready = False
+        #: True once the voices have been played (`_wire`).
+        self._wired = False
+        #: True while the wet chain is Rise's.
+        self._rise = None
+        #: What each node was last handed, by name.
+        self._handed = {}
+        self._feedback = 0.0
+        self._delay = 1.0
+        self._bloom = 1
+
+        # The borrowed source's only reader: a width-1 MidSide is the source
+        # byte for byte in 256-frame blocks, and it is what Mix 0 hands
+        # back, so a move to or from Mix 0 never skips or repeats a frame.
+        self._head = self._own(audioroute.MidSide(
+            self._source, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        # A MidSide with no source: one block of zeros per pull, which the
+        # shifter and the voices prime from (`_wire`).
+        self._hush = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels),
+            reset=False)
+        self._in = self._own(audioroute.Port(self._hush), reset=False)
+        # A Splitter's taps are read in step, 256 frames a pull each, so it
+        # holds nothing between pulls and is not reset.
+        self._split = self._own(audioroute.Splitter(self._in, taps=2),
+                                reset=False)
+        self._dry_tap = self._split.tap(0)
+        self._wet_tap = self._split.tap(1)
+        # Bloom's shifter reads the wet tap through a port of its own. A
+        # shifter's `play()` primes a block from its source and holds it,
+        # so it is played on `_hush` and that block is pulled out at once
+        # (`_drain`): the shifter then holds nothing, and whichever of the
+        # two characters reads the wet tap reads it in step with the dry.
+        self._shift_in = self._own(audioroute.Port(self._hush), reset=False)
+        self._shift = self._own(audiodelays.PitchShift(
+            semitones=0.0, mix=0.0,
+            window=whole_frames(WINDOW_MS, rate) * width,
+            overlap=whole_frames(OVERLAP_MS, rate) * width,
+            **self._pcm(BLOCK * width)))
+        self._shift.play(self._shift_in)
+        self._fd = self._own(audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=channels, max_delay_ms=LINE_MS,
+            delay_frames=1, feedback=0.0, mix=2.0, damping_hz=0.0,
+            cut_hz=0.0, loop_drive=0.0, loop_window_ms=LOOP_WINDOW_MS),
+            reset=self._clear_line)
+        self._hall = self._Hall(self._fd)
+        self._own(self._hall, reset=self._hall._clear,
+                  deinit=self._hall.deinit)
+        # Not reset by the walk: neither voice holds a block between two
+        # pulls (`_wire`), so there is nothing of its own to clear, and a
+        # Mixer's reset reaches its voices' sources.
+        self._mixer = self._own(audiomixer.Mixer(
+            voice_count=2, buffer_size=BLOCK * width * 2,
+            channel_count=channels, bits_per_sample=16,
+            samples_signed=True, sample_rate=rate), reset=False)
+        # The output: a width-1 MidSide over the mixer, byte for byte, whose
+        # reset forwards nothing. A host's reset of the output would
+        # otherwise reach the Mixer, and CircuitPython's own Mixer handles
+        # that differently from audiodsp's.
+        self._tail = self._own(audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        self._silence = audiocore.RawSample(
+            array("h", bytes(2 * 2 * channels)), sample_rate=rate,
+            channel_count=channels)
+        #: Where `audiocore.get_buffer` is compiled out, the one-voice
+        #: mixer `_drain` primes from; built the first time it is needed.
+        self._puller = None
+        self._drain(self._shift)
+        self._shift_in.play(self._wet_tap)
+        self._output = self._head
+
+        self._init_macros(tuple(defaults))
+        self._macros = positions
+        if patch is not None:
+            self.program_change(patch)
+        self._ready = True
+        self._refresh()
+
+    # -- the maps ------------------------------------------------------
+
+    def _value(self, index):
+        return _component.macro_value(self._MACRO_RANGES[index],
+                                      self._macros[index])
+
+    def _is_rise(self):
+        return self._macros[CHARACTER_I] >= 0.5
+
+    def _interval(self):
+        """Interval in semitones: the zone its position sits in."""
+        zone = int(self._value(INTERVAL_I))
+        if zone > 4:
+            zone = 4
+        if zone < 0:
+            zone = 0
+        return INTERVALS[zone]
+
+    def _mix(self):
+        return _between(self._value(MIX_I), 0.0, 2.0)
+
+    def macro(self, index):
+        """What macro `index` currently stands for, in its own units; for
+        Interval, the semitones it plays."""
+        self._check_live()
+        if index == INTERVAL_I:
+            return float(self._interval())
+        return _component.Component.macro(self, index)
+
+    # -- hooks a planted fault overrides --------------------------------
+
+    def _semitones(self):
+        """The interval the shifters are handed."""
+        return self._interval()
+
+    def _stagger_frames(self, bloom_ms):
+        """Bloom's stagger: the line's delay, in whole frames."""
+        return max(1, whole_frames(bloom_ms, self._sample_rate))
+
+    def _loop_frames(self, bloom_ms):
+        """Rise's line: Bloom less the half window a shifted read adds, so
+        the repeats fall Bloom apart."""
+        frames = whole_frames(bloom_ms, self._sample_rate) \
+            - LOOP_WINDOW_MS * 0.0005 * self._sample_rate
+        return max(1.0, frames)
+
+    def _loop_feedback(self):
+        """What the line sends round: Rise in Rise, nothing in Bloom."""
+        if self._is_rise():
+            return _between(self._value(RISE_I), 0.0, RISE_MAX)
+        return 0.0
+
+    def _loop_damping(self):
+        """The loop's low-pass: Damping in Rise, out in Bloom."""
+        if self._is_rise():
+            return self._hz(_between(self._value(DAMPING_I), 500.0,
+                                     16000.0))
+        return 0.0
+
+    def _dry_source(self):
+        """What the dry voice plays: the Splitter's dry tap."""
+        return self._dry_tap
+
+    # -- applying ------------------------------------------------------
+
+    def _apply_macro(self, index, position):
+        del index, position
+        if self._ready:
+            self._refresh()
+
+    def program_change(self, index, channel=0, note_id=-1,
+                       sample_position=0):
+        """Apply patch `index` whole, then refresh the graph once."""
+        ready = self._ready
+        self._ready = False
+        try:
+            _component.Component.program_change(
+                self, index, channel, note_id, sample_position)
+        finally:
+            self._ready = ready
+        if ready and type(self).PATCHES.get(index) is not None:
+            self._refresh()
+
+    def _hand(self, node, key, **settings):
+        """Hand `node` only the settings that changed since it was last
+        handed them."""
+        changed = {}
+        for name, value in settings.items():
+            tag = key + name
+            if self._handed.get(tag) != value:
+                self._handed[tag] = value
+                changed[name] = value
+        if changed:
+            if node is self._fd:
+                node.set(**changed)
+            else:
+                for name, value in changed.items():
+                    setattr(node, name, value)
+
+    def _refresh(self):
+        rise = self._is_rise()
+        bloom_ms = self._value(BLOOM_I)
+        shimmer = _between(self._value(SHIMMER_I), 0.0, 1.0)
+        semitones = self._semitones()
+        recut = self._rise is not None and rise != self._rise
+        self._feedback = self._loop_feedback()
+        self._bloom = whole_frames(bloom_ms, self._sample_rate)
+        if rise:
+            self._delay = self._loop_frames(bloom_ms)
+            if recut or self._rise is None:
+                self._fd.play(self._wet_tap)
+            self._hand(self._fd, "fd.", delay_frames=self._delay,
+                       feedback=self._feedback, mix=shimmer,
+                       damping_hz=self._loop_damping(),
+                       loop_semitones=float(semitones))
+        else:
+            self._delay = float(self._stagger_frames(bloom_ms))
+            if recut or self._rise is None:
+                self._fd.play(self._shift)
+            self._hand(self._shift, "ps.",
+                       semitones=step_centre_semitones(
+                           interval_step(semitones)),
+                       mix=shimmer * 0.5)
+            self._hand(self._fd, "fd.", delay_frames=self._delay,
+                       feedback=self._feedback, mix=2.0,
+                       damping_hz=self._loop_damping(), loop_semitones=0.0)
+        self._rise = rise
+        for ours, theirs in _HALL_MACROS:
+            position = self._macros[ours]
+            tag = "hall.%d" % theirs
+            if self._handed.get(tag) != position:
+                self._handed[tag] = position
+                self._hall.set_macro(theirs, 127.0 * position)
+        if recut:
+            # The wet chain is re-cut: it renders as a fresh instance's.
+            # The dry carries on.
+            self._clear_nodes(only=(self._shift, self._fd, self._hall))
+        self._route()
+
+    def _levels(self):
+        mix = self._mix()
+        voices = self._mixer.voice
+        voices[0].level = min(1.0, 2.0 - mix)
+        voices[1].level = min(1.0, mix)
+
+    def _route(self):
+        """Point the output at the source's reader at Mix 0, or at the
+        mixer, emptying the wet chain when it comes back."""
+        if self._mix() <= 0.0:
+            self._route_around(self._head)
+            return
+        if not self._wired:
+            self._wire()
+        else:
+            self._levels()
+            self._rejoin()
+        self._output = self._tail
+
+    def _wire(self):
+        """Play the voices, the first time the output reaches the mixer.
+
+        A voice's `play()`, like the shifter's, primes a block from its
+        source. With the Splitter on `_hush` that block is zeros, and one
+        pull of the mixer hands it out, so wiring takes nothing from the
+        borrowed source and leaves no voice holding a block: a reset or a
+        return from Mix 0 never meets a block a voice is still waiting to
+        play. The level gates are opened first, as
+        `_component.open_level_gates` opens them."""
+        voices = self._mixer.voice
+        self._levels()
+        for voice in voices:
+            voice.play(self._silence, loop=True)
+        self._pull()
+        voices[0].play(self._dry_source())
+        voices[1].play(self._hall.output)
+        self._pull()
+        self._in.play(self._head)
+        self._clear_nodes(only=(self._shift, self._fd, self._hall))
+        self._wired = True
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it. `_tail` forwards no
+        reset, so pulling through it rewinds nothing behind it."""
+        self._drain(self._tail)
+
+    def _drain(self, node):
+        """Pull one block from `node` and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `node` and stops: its `play()` primes one block, which pulls
+        `node` once."""
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(node)
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # smallest that hold a frame.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, buffer_size=16,
+                channel_count=self._channel_count, bits_per_sample=16,
+                samples_signed=True, sample_rate=self._sample_rate),
+                reset=False)
+        voice = self._puller.voice[0]
+        voice.play(node)
+        voice.stop()
+
+    def _clear_line(self):
+        """Empty the line. A shifted loop goes back to its single-tap read
+        and starts its splice from where a new node does."""
+        self._fd.clear()
+
+    # -- the contract's reads ------------------------------------------
+
+    @property
+    def tail_samples(self):
+        """Frames until the output is exactly zero once the input stops, as
+        an upper bound."""
+        self._check_live()
+        return self._tail_bound()
+
+    def _tail_bound(self):
+        """`tail_samples` without the liveness check: a plain method, so a
+        subclass can reach it on MicroPython, whose `property` has no
+        `fget`.
+
+        Bloom: the stagger, then the shifter's window and crossfade (what
+        it holds once its input stops), then the hall's own tail. Rise: the
+        line goes round `laps_to_zero` laps at Rise (the node's stall rule
+        ends it), each at most Bloom plus the loop window, the read between
+        two frames and the low-pass's memory, and one more for what the line
+        holds at Rise 0; then the hall's tail. 0 at Mix 0."""
+        if self._mix() <= 0.0:
+            return 0
+        rate = self._sample_rate
+        hall = self._hall.tail_samples
+        if not self._rise:
+            reach = self._bloom + whole_frames(WINDOW_MS, rate) \
+                + whole_frames(OVERLAP_MS, rate) + 1
+            return int(reach + hall)
+        memory, excess = tone_excess(self._handed.get("fd.damping_hz", 0.0),
+                                     rate)
+        lap = self._bloom + int(math.ceil(LOOP_WINDOW_MS * rate / 1000.0)) \
+            + 2 + memory
+        laps = laps_to_zero(self._feedback, excess) + 1
+        return int(laps * lap + hall)
+
+    class _Hall(_reverb.Reverb):
+        """The rack's hall: `Reverb` whose only patch is the hall at the
+        rack's patch-0 settings, and whose constructor defaults are that
+        patch, so its own `reset()` lands there. Nested, so the module holds
+        one provider; last, so the rack's `_build` is the first in this
+        source."""
+
+        PATCHES = {0: ("Hall", HALL_PATCH)}
+
+        def _build(self, patch=None, **options):
+            settings = _hall_options()
+            settings.update(options)
+            _reverb.Reverb._build(self, patch=patch, **settings)
+
+        def _clear(self):
+            """Empty the tank and keep every macro: a reset without its
+            patch 0."""
+            self._clear_nodes()
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
new file mode 100644
index 0000000..fdd9da7
--- /dev/null
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -0,0 +1,1198 @@
+"""`ShimmerHall`'s trait and planted-fault tests.
+
+Six traits: T1 the Bloom stagger, T2 the interval, T3 the octaves climbing
+one Bloom apart in Rise, T4 Rise's return strength, T5 Damping stopping
+the climb, T6 the untouched dry. Each has its measurement, run over the
+cells listed with it, and the same measurement shown red on a planted
+fault of the same kind. `KIT_PLANTS` hands the plants to the kit, which
+shows each one differs from the clean class and that no knob stop or patch
+reproduces it.
+
+Every law a measurement checks against is written out here, never taken
+from the class.
+
+The material is the card's: a 100 ms tone burst at f0 with 5 ms ramps and
+a 2000 LSB peak, after an offset of 0 to 255 frames. A seed set draws f0
+(165 to 330 Hz) and the offset from this module's own integer generator,
+so every interpreter makes the same bytes. Bands are Goertzel sums over
+Hann frames, 1024 frames at 48 kHz and 512 at 22.05 kHz.
+
+The unit tests run a share of each trait's cells; `figures()` runs every
+cell the card names, eight seed sets each, and prints the evidence pack's
+numbers. The module is numpy-free and imports on MicroPython and
+CircuitPython, where `unittest` is absent: the kit reads `KIT_PLANTS`
+there, and running the file with `--figures` prints the figures on
+whichever interpreter runs it:
+
+    MICROPYPATH=lib:tests/support micropython \\
+        tests/test_cpython_effects_shimmerhall.py --figures T6
+"""
+
+import math
+import sys
+from array import array
+
+try:
+    import unittest
+    TestCase = unittest.TestCase
+except ImportError:                     # a native interpreter
+    unittest = None
+    TestCase = object
+
+try:
+    import os
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, os.path.join(_HERE, "support"))
+    sys.path.insert(0, os.path.join(_HERE, "..", "lib"))
+except (ImportError, AttributeError, NameError):   # no os.path natively
+    pass
+
+import kit_common as kc                                     # noqa: E402
+from audioeffects import _component                         # noqa: E402
+from audioeffects import rebuilt                            # noqa: E402
+
+VENDOR = "PyDevices"
+
+RATES = (48000, 22050)
+BLOCK = 256
+SEEDS = tuple(range(8))
+(CHARACTER_I, SHIMMER_I, RISE_I, BLOOM_I, INTERVAL_I, DECAY_I, SIZE_I,
+ DAMPING_I, MIX_I) = range(9)
+INTERVALS = (-12, -5, 7, 12, 24)
+
+ShimmerHall = rebuilt.module_class("ShimmerHall")
+_module = sys.modules[ShimmerHall.__module__]
+
+
+# --------------------------------------------------------------------------
+# The card's laws, written out independently of the class
+
+
+def law_frames(ms, rate):
+    """A time in whole frames."""
+    return int(math.floor(ms * rate / 1000.0 + 0.5))
+
+
+def law_bloom(ms):
+    """Bloom on its 0-127 grid: 20 to 800 ms, log."""
+    step = int(math.log(ms / 20.0) / math.log(40.0) * 127.0 + 0.5)
+    return 20.0 * 40.0 ** (step / 127.0)
+
+
+def law_rise(rise):
+    """Rise on its 0-127 grid, 0.9 at the top."""
+    return 0.9 * int(rise * 127.0 / 0.9 + 0.5) / 127.0
+
+
+# --------------------------------------------------------------------------
+# Material and rendering: the same bytes on every interpreter
+
+
+class Lcg:
+    def __init__(self, seed):
+        self.state = (seed * 2654435761 + 1) & 0x7FFFFFFF
+
+    def next(self):
+        self.state = (self.state * 1103515245 + 12345) & 0x7FFFFFFF
+        return self.state >> 7
+
+    def uniform(self, low, high):
+        return low + (high - low) * (self.next() % 1000001) / 1000000.0
+
+
+def seed_set(seed):
+    """(f0, offset) for one seed: f0 uniform in 165..330 Hz, the offset in
+    0..255 frames."""
+    rng = Lcg(seed)
+    return rng.uniform(165.0, 330.0), rng.next() % 256
+
+
+def rint(x):
+    """Round half away from zero."""
+    if x >= 0:
+        return int(x + 0.5)
+    return -int(-x + 0.5)
+
+
+def burst(rate, channels, f0, offset, frames):
+    """The card's burst in `frames` frames: 100 ms at f0, 5 ms ramps, 2000
+    LSB peak, after `offset` frames of silence."""
+    out = array("h", bytes(2 * frames * channels))
+    length = law_frames(100.0, rate)
+    ramp = law_frames(5.0, rate)
+    w = 2.0 * math.pi * f0 / rate
+    for n in range(length):
+        g = 1.0
+        if n < ramp:
+            g = 0.5 - 0.5 * math.cos(math.pi * n / ramp)
+        elif n >= length - ramp:
+            g = 0.5 - 0.5 * math.cos(math.pi * (length - 1 - n) / ramp)
+        v = rint(2000.0 * g * math.sin(w * n))
+        for c in range(channels):
+            out[(offset + n) * channels + c] = v
+    return out
+
+
+def render(cls, values, rate, channels, frames, moves=None, **options):
+    """`frames` frames of a fresh instance fed `values` in 256-frame blocks
+    and then silence; `moves` maps a pull index to a callable."""
+    feed = kc.feed(values, rate, channels)
+    e = cls(feed.port, **options)
+    try:
+        return kc.samples(kc.render(e, frames, moves))
+    finally:
+        e.deinit()
+
+
+def left(out, channels):
+    """The left channel (the only one, in mono)."""
+    if channels == 1:
+        return out
+    return out[0::2]
+
+
+def hann_size(rate):
+    return 1024 if rate >= 44100 else 512
+
+
+_HANN = {}
+
+
+def hann(size):
+    if size not in _HANN:
+        _HANN[size] = [0.5 - 0.5 * math.cos(2.0 * math.pi * n / (size - 1))
+                       for n in range(size)]
+    return _HANN[size]
+
+
+def goertzel(values, start, size, hz, rate, window):
+    """Power at `hz` over values[start:start + size], Hann-windowed."""
+    coeff = 2.0 * math.cos(2.0 * math.pi * hz / rate)
+    s1 = s2 = 0.0
+    for n in range(size):
+        x = values[start + n] * window[n]
+        s0 = x + coeff * s1 - s2
+        s2 = s1
+        s1 = s0
+    return s1 * s1 + s2 * s2 - coeff * s1 * s2
+
+
+def band_track(values, hz, rate, hop):
+    """Band power at `hz` per Hann frame, every `hop` frames."""
+    size = hann_size(rate)
+    window = hann(size)
+    track = []
+    for start in range(0, len(values) - size + 1, hop):
+        track.append(goertzel(values, start, size, hz, rate, window))
+    return track
+
+
+def db(power):
+    if power <= 0.0:
+        return -400.0
+    return 10.0 * math.log(power) / math.log(10.0)
+
+
+def wet(cls, rate, channels, f0, offset, frames, **options):
+    """Left channel of a Mix 2 render of the burst."""
+    options.setdefault("mix", 2.0)
+    return left(render(cls, burst(rate, channels, f0, offset, frames), rate,
+                       channels, frames, **options), channels)
+
+
+# --------------------------------------------------------------------------
+# Planted faults
+
+
+class PinnedStagger(ShimmerHall):
+    """T1: Bloom's stagger pinned at 275 ms."""
+
+    def _stagger_frames(self, bloom_ms):
+        return law_frames(275.0, self._sample_rate)
+
+
+class AlwaysOctave(ShimmerHall):
+    """T2: the shifters always handed +12."""
+
+    def _semitones(self):
+        return 12
+
+
+class PinnedLoop(ShimmerHall):
+    """T3: Rise's loop pinned at 300 ms."""
+
+    def _loop_frames(self, bloom_ms):
+        return ShimmerHall._loop_frames(self, 300.0)
+
+
+class HeldFeedback(ShimmerHall):
+    """T4: the loop's feedback held at 0.6 in Rise."""
+
+    def _loop_feedback(self):
+        if self._is_rise():
+            return 0.6
+        return 0.0
+
+
+class RiseInBloom(ShimmerHall):
+    """T4: Rise handed to the line in Bloom too."""
+
+    def _loop_feedback(self):
+        return self._value(RISE_I)
+
+
+class UndampedLoop(ShimmerHall):
+    """T5: the loop's low-pass left out; the hall still gets Damping."""
+
+    def _loop_damping(self):
+        return 0.0
+
+
+class LateDry(ShimmerHall):
+    """T6: the dry voice fed through a stagger of its own, as the old class
+    had the stagger on the wrong side of the sum."""
+
+    def _dry_source(self):
+        rate = self._sample_rate
+        line = self._own(_module.audioecho.FeedbackDelay(
+            sample_rate=rate, channel_count=self._channel_count,
+            max_delay_ms=_module.LINE_MS,
+            delay_frames=law_frames(self._value(BLOOM_I), rate),
+            feedback=0.0, mix=2.0, damping_hz=0.0, cut_hz=0.0))
+        line.play(self._dry_tap)
+        return line
+
+
+#: The kit's plant table. A Rise plant is judged at a Rise patch, a Bloom
+#: plant at the Bloom patch its fault shows plainest at.
+KIT_PLANTS = {
+    "T1": (PinnedStagger, 1),
+    "T2": (AlwaysOctave, 2),
+    "T3": (PinnedLoop, 3),
+    "T4": (HeldFeedback, 4),
+    "T4b": RiseInBloom,
+    "T5": (UndampedLoop, 4),
+    "T6": LateDry,
+}
+
+
+# --------------------------------------------------------------------------
+# T1: in Bloom the octave lands Bloom after you play
+
+
+T1_BLOOMS = (20.0, 200.0, 800.0)
+
+
+def t1_onset(cls, rate, f0, offset, bloom):
+    frames = law_frames(bloom + 400.0, rate) + offset
+    s1 = wet(cls, rate, 1, f0, offset, frames, bloom_ms=bloom, shimmer=1.0)
+    s0 = wet(cls, rate, 1, f0, offset, frames, bloom_ms=bloom, shimmer=0.0)
+    hz = 2.0 * f0
+    size = hann_size(rate)
+    window = hann(size)
+    for start in range(0, frames - size + 1, 64):
+        p1 = goertzel(s1, start, size, hz, rate, window)
+        if p1 <= 0.0:
+            continue
+        p0 = goertzel(s0, start, size, hz, rate, window)
+        if p1 > 10.0 * p0:
+            return start - offset
+    return None
+
+
+def t1_read(cls, rate, seed):
+    """(errors in frames of each onset difference against the Bloom
+    difference, the onsets)."""
+    f0, offset = seed_set(seed)
+    onsets = [t1_onset(cls, rate, f0, offset, b) for b in T1_BLOOMS]
+    if None in onsets:
+        return None, onsets
+    errors = []
+    for i in range(len(T1_BLOOMS)):
+        for j in range(i + 1, len(T1_BLOOMS)):
+            want = law_frames(law_bloom(T1_BLOOMS[j]), rate) \
+                - law_frames(law_bloom(T1_BLOOMS[i]), rate)
+            errors.append(onsets[j] - onsets[i] - want)
+    return errors, onsets
+
+
+T1_BAR = 2 * BLOCK
+
+
+# --------------------------------------------------------------------------
+# T2: the shifted copy is at the Interval you chose
+
+
+#: Each Interval's bar in semitones, by character.
+T2_BARS = {
+    "bloom": {-12: 2.5, -5: 2.5, 7: 2.5, 12: 2.5, 24: 2.5},
+    "rise": {-12: 6.0, -5: 2.5, 7: 2.5, 12: 3.5, 24: 6.0},
+}
+
+
+def t2_read(cls, rate, character, interval, seed):
+    """The energy-weighted mean shift of d = (Shimmer 1) - (Shimmer 0), in
+    semitones, over the 500 ms from Bloom."""
+    f0, offset = seed_set(seed)
+    bloom = law_bloom(275.0)
+    start = law_frames(bloom, rate) + offset
+    span = law_frames(500.0, rate)
+    frames = start + span
+    options = dict(character=character, interval=interval, rise=0.0)
+    s1 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, **options)
+    s0 = wet(cls, rate, 1, f0, offset, frames, shimmer=0.0, **options)
+    d = [s1[n] - s0[n] for n in range(frames)]
+    size = 2048 if rate >= 44100 else 1024
+    window = hann(size)
+    total = weighted = 0.0
+    for q in range(-72, 121):
+        semis = q * 0.25
+        hz = f0 * 2.0 ** (semis / 12.0)
+        if hz >= 0.5 * rate:
+            continue
+        energy = 0.0
+        for at in range(start, frames - size + 1, size):
+            energy += goertzel(d, at, size, hz, rate, window)
+        total += energy
+        weighted += energy * semis
+    if total <= 0.0:
+        return None
+    return weighted / total
+
+
+# --------------------------------------------------------------------------
+# T3: in Rise each octave arrives about one Bloom after the one below
+
+
+def t3_onset(track, base, hop):
+    """First frame where `track` is 10 dB over `base` and within 20 dB of
+    its own peak."""
+    peak = max(track)
+    if peak <= 0.0:
+        return None
+    for k in range(len(track)):
+        p = track[k]
+        if p > 10.0 * base[k] and p >= peak * 0.01:
+            return k * hop
+    return None
+
+
+def t3_read(cls, rate, bloom, seed):
+    """(onsets of generations 1.., mean spacing over Bloom - 1)."""
+    f0, offset = seed_set(seed)
+    frames = law_frames(100.0 + 6 * bloom + 600.0, rate) + offset
+    options = dict(character="rise", bloom_ms=bloom, damping_hz=16000.0,
+                   decay=4.0, interval=12)
+    s0 = wet(cls, rate, 1, f0, offset, frames, shimmer=0.0, **options)
+    r0 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, rise=0.0,
+             **options)
+    r9 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, rise=0.9,
+             **options)
+    hop = 256
+    onsets = [t3_onset(band_track(r0, 2.0 * f0, rate, hop),
+                       band_track(s0, 2.0 * f0, rate, hop), hop)]
+    for k in range(2, 6):
+        hz = f0 * 2.0 ** k
+        if hz >= 0.4 * rate:
+            break
+        onsets.append(t3_onset(band_track(r9, hz, rate, hop),
+                               band_track(r0, hz, rate, hop), hop))
+    if None in onsets or len(onsets) < 2:
+        return onsets, None
+    spacing = (onsets[-1] - onsets[0]) / float(len(onsets) - 1)
+    return onsets, spacing / law_frames(law_bloom(bloom), rate) - 1.0
+
+
+def t3_verdict(onsets, error):
+    if error is None:
+        return "an onset was not found: %r" % (onsets,)
+    for a, b in zip(onsets, onsets[1:]):
+        if b <= a:
+            return "onsets do not increase: %r" % (onsets,)
+    if abs(error) > 0.20:
+        return "spacing %.1f %% off Bloom" % (100.0 * error)
+    return None
+
+
+# --------------------------------------------------------------------------
+# T4 and T5: how strongly each pass returns, and Damping
+
+
+def band_peak(values, hz, rate):
+    """The peak band power at `hz` over the render, hop of half a frame."""
+    return max(band_track(values, hz, rate, hann_size(rate) // 2))
+
+
+def t45_render(cls, rate, f0, offset, character, rise, damping):
+    frames = law_frames(100.0 + 200.0 * 6 + 400.0, rate) + offset
+    return wet(cls, rate, 1, f0, offset, frames, character=character,
+               shimmer=1.0, rise=rise, damping_hz=damping, bloom_ms=200.0,
+               interval=12)
+
+
+def t4_cells(full=False):
+    cells = []
+    for rate in RATES:
+        sets = [seed_set(s) for s in (SEEDS if full else SEEDS[:2])]
+        if full:
+            sets += [(165.0, seed_set(0)[1]), (330.0, seed_set(1)[1])]
+        cells += [(rate, f0, offset) for f0, offset in sets]
+    return cells
+
+
+def t4_read(cls, rate, f0, offset):
+    """(Rise: generation 3's gain from Rise 0.3 to 0.9 relative to
+    generation 1, in dB; Bloom: whether 0.3 and 0.9 render the same; Bloom
+    2 f0 peak against Rise 0.9's, in dB)."""
+    levels = []
+    renders = {}
+    for rise in (0.3, 0.9):
+        r = t45_render(cls, rate, f0, offset, "rise", rise, 16000.0)
+        renders[rise] = r
+        levels.append(db(band_peak(r, 8.0 * f0, rate))
+                      - db(band_peak(r, 2.0 * f0, rate)))
+    gain = levels[1] - levels[0]
+    b3 = t45_render(cls, rate, f0, offset, "bloom", 0.3, 16000.0)
+    b9 = t45_render(cls, rate, f0, offset, "bloom", 0.9, 16000.0)
+    alive = db(band_peak(b9, 2.0 * f0, rate)) \
+        - db(band_peak(renders[0.9], 2.0 * f0, rate))
+    return gain, list(b3) == list(b9), alive
+
+
+def t5_read(cls, rate, f0, offset):
+    """Generation 4 relative to generation 1 at Damping 16 kHz less the
+    same at 800 Hz, in dB."""
+    rel = []
+    for damping in (800.0, 16000.0):
+        r = t45_render(cls, rate, f0, offset, "rise", 0.9, damping)
+        rel.append(db(band_peak(r, 16.0 * f0, rate))
+                   - db(band_peak(r, 2.0 * f0, rate)))
+    return rel[1] - rel[0]
+
+
+def t5_cells(full=False):
+    cells = []
+    for rate in RATES:
+        for f0 in (165.0, 330.0):
+            for seed in (SEEDS if full else SEEDS[:1]):
+                cells.append((rate, f0, seed_set(seed)[1]))
+    return cells
+
+
+# --------------------------------------------------------------------------
+# T6: the dry never carries the shimmer
+
+
+def t6_material(rate, channels, seed):
+    """0.5 s of uniform noise at -18 dBFS RMS, then 1 s of silence."""
+    amp = rint(32768.0 * 10.0 ** (-18.0 / 20.0) * math.sqrt(3.0))
+    rng = Lcg(100 + seed)
+    frames = law_frames(500.0, rate)
+    out = array("h", bytes(2 * (frames + rate) * channels))
+    for i in range(frames * channels):
+        out[i] = rng.next() % (2 * amp + 1) - amp
+    return out
+
+
+def patch_options(cls, patch, **over):
+    """Constructor options that build patch `patch`'s settings, with
+    `over` on top: Mix set at construction opens the voices' level gates
+    at that Mix, where a move after it waits for a zero crossing."""
+    names = ("character", "shimmer", "rise", "bloom_ms", "interval",
+             "decay", "size", "damping_hz", "mix")
+    steps = cls.PATCHES[patch][1]
+    options = {}
+    for index, name in enumerate(names):
+        position = _component.position_of_midi("UNIPOLAR", steps[index])
+        if index == CHARACTER_I:
+            options[name] = "rise" if position >= 0.5 else "bloom"
+        elif index == INTERVAL_I:
+            options[name] = INTERVALS[min(4, int(5.0 * position))]
+        else:
+            options[name] = _component.macro_value(
+                cls._MACRO_RANGES[index], position)
+    options.update(over)
+    return options
+
+
+def t6_read(cls, rate, channels, patch, seed):
+    """(the largest |(Mix 1) - (Mix 2) - source|, the largest |output|)."""
+    values = t6_material(rate, channels, seed)
+    frames = len(values) // channels
+    outs = []
+    for mix in (1.0, 2.0):
+        feed = kc.feed(values, rate, channels)
+        e = cls(feed.port, **patch_options(cls, patch, mix=mix))
+        try:
+            outs.append(kc.samples(kc.render(e, frames)))
+        finally:
+            e.deinit()
+    worst = loud = 0
+    for i in range(len(values)):
+        worst = max(worst, abs(outs[0][i] - outs[1][i] - values[i]))
+        loud = max(loud, abs(outs[0][i]), abs(outs[1][i]))
+    return worst, loud
+
+
+T6_PATCHES = (0, 4)
+
+
+# --------------------------------------------------------------------------
+# Running without `audiocore.get_buffer`
+
+
+def without_get_buffer(build, moves, frames=4096, seed=3, rate=48000,
+                       channels=2, hide=True):
+    """Render with `audiocore.get_buffer` hidden from the class, as on a
+    CircuitPython board build, while it builds and while it moves; with
+    `hide` false, the same render with it in place."""
+    import types
+    real = _module.audiocore
+    fake = types.ModuleType("audiocore")
+    for name in dir(real):
+        if name != "get_buffer" or not hide:
+            setattr(fake, name, getattr(real, name))
+
+    def hidden(action):
+        def run(e):
+            _module.audiocore = _component.audiocore = fake
+            try:
+                action(e)
+            finally:
+                _module.audiocore = _component.audiocore = real
+        return run
+
+    rng = Lcg(seed)
+    values = array("h", [rng.next() % 40001 - 20000
+                         for _ in range(frames * channels)])
+    feed = kc.feed(values, rate, channels)
+    _module.audiocore = _component.audiocore = fake
+    try:
+        e = build(feed.port)
+    finally:
+        _module.audiocore = _component.audiocore = real
+    try:
+        out = kc.samples(kc.render(
+            e, frames, dict((k, hidden(f)) for k, f in moves.items())))
+    finally:
+        e.deinit()
+    return values, out
+
+
+GET_BUFFER_CASES = (
+    ("built at the defaults", ShimmerHall, {}),
+    ("built in Rise", lambda src: ShimmerHall(src, character="rise"), {}),
+    ("reset before the first pull", ShimmerHall, {0: lambda e: e.reset()}),
+    ("reset twice before the first pull", ShimmerHall,
+     {0: lambda e: (e.reset(), e.reset())}),
+    ("built at Mix 0, then patch 0", lambda src: ShimmerHall(src, mix=0.0),
+     {3: lambda e: e.program_change(0)}),
+    ("built at Mix 0, reset", lambda src: ShimmerHall(src, mix=0.0),
+     {3: lambda e: e.reset()}),
+    ("Mix 0 before the first block, back", ShimmerHall,
+     {0: lambda e: e.set_macro(MIX_I, 0), 4: lambda e: e.set_macro(MIX_I, 32)}),
+    ("Mix 0 after playing, reset twice", ShimmerHall,
+     {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: (e.reset(), e.reset())}),
+    ("a Character move and a reset in one block", ShimmerHall,
+     {2: lambda e: (e.program_change(4), e.reset())}),
+)
+
+
+# --------------------------------------------------------------------------
+# The tests
+
+
+def _port(rate=48000, channels=2):
+    return kc.feed(array("h", bytes(4 * channels)), rate, channels).port
+
+
+class TheSurface(TestCase):
+    def test_macros_patches_tier_latency(self):
+        self.assertEqual(ShimmerHall.MACRO_LABELS,
+                         ("Character", "Shimmer", "Rise", "Bloom",
+                          "Interval", "Decay", "Size", "Damping", "Mix"))
+        self.assertEqual(ShimmerHall.MACRO_MODES[0], "TOGGLE")
+        self.assertEqual(ShimmerHall.TIER, _component.AUDIODSP)
+        self.assertEqual(ShimmerHall.REQUIRES,
+                         ("audioroute", "audioecho", "audioverb"))
+        self.assertEqual(ShimmerHall.CAPABILITIES, ())
+        self.assertEqual(ShimmerHall.LATENCY_SAMPLES, 0)
+        self.assertEqual([ShimmerHall.PATCHES[i][0] for i in range(6)],
+                         ["Octave Bloom", "Short Stagger", "Fifth Halo",
+                          "Slow Rise", "Rise Damped", "Falling Octaves"])
+
+    def test_the_spans(self):
+        e = ShimmerHall(_port())
+        try:
+            ends = []
+            for index in range(1, 9):
+                if index == INTERVAL_I:
+                    continue
+                row = []
+                for midi in (0, 127):
+                    e.set_macro(index, midi)
+                    row.append(round(e.macro(index), 9))
+                ends.append(row)
+            self.assertEqual(ends, [[0.0, 1.0], [0.0, 0.9], [20.0, 800.0],
+                                    [0.3, 10.0], [0.5, 1.5],
+                                    [500.0, 16000.0], [0.0, 2.0]])
+        finally:
+            e.deinit()
+
+    def test_interval_has_five_zones(self):
+        e = ShimmerHall(_port())
+        try:
+            for midi, semis in zip((0, 32, 64, 96, 127), INTERVALS):
+                e.set_macro(INTERVAL_I, midi)
+                self.assertEqual(e.macro(INTERVAL_I), float(semis))
+            heard = set()
+            for midi in range(128):
+                e.set_macro(INTERVAL_I, midi)
+                heard.add(e.macro(INTERVAL_I))
+            self.assertEqual(heard, set(float(i) for i in INTERVALS))
+        finally:
+            e.deinit()
+
+    def test_the_constructor(self):
+        for bad in (0, 5, 13, 12.5, True, float("nan")):
+            with self.assertRaises(ValueError):
+                ShimmerHall(_port(), interval=bad)
+        with self.assertRaises(ValueError):
+            ShimmerHall(_port(), character="plate")
+        e = ShimmerHall(_port(), bloom_ms=5000.0, rise=2.0, decay=-1.0,
+                        shimmer=float("nan"), character="rise", interval=-5)
+        try:
+            self.assertEqual(e.get_macro(BLOOM_I), 127.0)
+            self.assertEqual(e.get_macro(RISE_I), 127.0)
+            self.assertEqual(e.get_macro(DECAY_I), 0.0)
+            self.assertEqual(e.get_macro(SHIMMER_I), 89.0)
+            self.assertEqual(e.get_macro(CHARACTER_I), 127.0)
+            self.assertEqual(e.macro(INTERVAL_I), -5.0)
+        finally:
+            e.deinit()
+
+    def test_patches_are_the_card_settings_on_the_grid(self):
+        card = {
+            0: ("bloom", 0.7, 0.6, 275, 12, 4.0, 1.0, 6000, 0.5),
+            1: ("bloom", 0.6, 0.6, 60, 12, 2.5, 0.8, 8000, 0.4),
+            2: ("bloom", 0.8, 0.6, 400, 7, 6.0, 1.2, 5000, 0.6),
+            3: ("rise", 0.7, 0.6, 400, 12, 6.0, 1.2, 8000, 0.6),
+            4: ("rise", 0.8, 0.8, 250, 12, 4.0, 1.0, 2000, 0.5),
+            5: ("rise", 0.7, 0.6, 300, -12, 5.0, 1.0, 4000, 0.5),
+        }
+        zones = dict(zip(INTERVALS, (0, 32, 64, 96, 127)))
+        for index, row in card.items():
+            want = [0 if row[0] == "bloom" else 127]
+            for i in range(1, 9):
+                if i == INTERVAL_I:
+                    want.append(zones[row[i]])
+                else:
+                    want.append(_component.macro_of(
+                        ShimmerHall._MACRO_RANGES[i], row[i]))
+            self.assertEqual(ShimmerHall.PATCHES[index][1], tuple(want),
+                             index)
+
+    def test_a_fresh_instance_reads_patch_0(self):
+        e = ShimmerHall(_port())
+        try:
+            self.assertEqual(tuple(e.get_macro(i) for i in range(9)),
+                             ShimmerHall.PATCHES[0][1])
+            self.assertEqual(e.patch_index, 0)
+            values = [e.macro(i) for i in range(9)]
+            want = [0.0, 0.7008, 0.6024, 273.1, 12.0, 4.0206, 1.00394,
+                    5990.5, 0.5039]
+            for got, card in zip(values, want):
+                self.assertAlmostEqual(got, card, delta=abs(card) * 1e-4)
+        finally:
+            e.deinit()
+
+    def test_patches_play_the_same_whatever_the_constructor_said(self):
+        # No constructor value is kept beside the grid, so a patch is the
+        # same on every instance.
+        values = burst(48000, 2, 247.0, 31, 9600)
+        for patch in sorted(ShimmerHall.PATCHES):
+            renders = []
+            # Mix stays at the default: a level a patch moves waits for
+            # the voice's next zero crossing, so the burst's first
+            # half-cycle would play at the constructor's Mix.
+            for options in ({}, dict(shimmer=0.37, rise=0.71, bloom_ms=33.3,
+                                     interval=-5, decay=7.7, size=0.61,
+                                     damping_hz=777.0, character="rise")):
+                feed = kc.feed(values, 48000, 2)
+                e = ShimmerHall(feed.port, **options)
+                e.program_change(patch)
+                try:
+                    renders.append(kc.render(e, 9600))
+                finally:
+                    e.deinit()
+            self.assertEqual(renders[0], renders[1], patch)
+
+    def test_the_hall_is_its_own_patch_0(self):
+        hall_cls = ShimmerHall._Hall
+        self.assertEqual(sorted(hall_cls.PATCHES), [0])
+        concert = None
+        for name, row in ShimmerHall._Hall.__bases__[0].PATCHES.values():
+            if name == "Concert Hall":
+                concert = row
+        want = (127, 94, 64, 0, concert[4], 91, concert[6], concert[7],
+                concert[8], concert[9], concert[10], concert[11], 127)
+        self.assertEqual(hall_cls.PATCHES[0][1], want)
+        h = hall_cls(_port())
+        try:
+            for i in range(13):
+                self.assertAlmostEqual(h.get_macro(i), want[i], places=6)
+        finally:
+            h.deinit()
+
+    def test_only_one_provider(self):
+        self.assertEqual(list(rebuilt.known()).count("ShimmerHall"), 1)
+        self.assertNotIn("_Hall", rebuilt.known())
+
+    def test_mix_0_is_the_input(self):
+        values = t6_material(48000, 2, 1)
+        for character in ("bloom", "rise"):
+            out = render(ShimmerHall, values, 48000, 2, 24000, mix=0.0,
+                         character=character)
+            self.assertEqual(list(out), list(values[:48000]))
+
+    def test_no_latency(self):
+        values = array("h", bytes(2 * 2 * 4096))
+        values[2000] = values[2001] = 12000
+        out = render(ShimmerHall, values, 48000, 2, 4096, mix=1.0)
+        self.assertEqual(out[2000], 12000)
+        self.assertEqual(list(out[:2000]), [0] * 2000)
+
+    def test_a_mono_source_gets_a_mono_rack(self):
+        e = ShimmerHall(_port(48000, 1))
+        try:
+            self.assertEqual(e.channel_count, 1)
+            self.assertEqual(e.output.channel_count, 1)
+        finally:
+            e.deinit()
+
+    def test_tail_samples(self):
+        # The output reaches exact zero inside the bound, at every patch.
+        for rate in RATES:
+            for patch in sorted(ShimmerHall.PATCHES):
+                values = burst(rate, 1, 247.0, 0, law_frames(150.0, rate))
+                feed = kc.feed(values, rate, 1)
+                e = ShimmerHall(feed.port, patch=patch)
+                try:
+                    tail = e.tail_samples
+                    stream = kc.Stream(e)
+                    end = len(values) + tail + 2 * BLOCK
+                    while stream.frames < end:
+                        stream.step()
+                    self.assertLessEqual(stream.last,
+                                         len(values) + tail + BLOCK,
+                                         (rate, patch))
+                finally:
+                    e.deinit()
+
+    def test_tail_is_zero_at_mix_0(self):
+        e = ShimmerHall(_port(), mix=0.0)
+        try:
+            self.assertEqual(e.tail_samples, 0)
+        finally:
+            e.deinit()
+
+    def test_reset_empties_the_graph_and_returns_to_patch_0(self):
+        values = burst(48000, 2, 247.0, 0, 48000)
+        clean = render(ShimmerHall, values[2 * 9728:], 48000, 2, 24000)
+
+        def moves(e):
+            e.program_change(5)
+        feed = kc.feed(values, 48000, 2)
+        e = ShimmerHall(feed.port, patch=3)
+        try:
+            kc.render(e, 9728, {10: moves})
+            e.reset()
+            self.assertEqual(e.patch_index, 0)
+            self.assertEqual(tuple(e.get_macro(i) for i in range(9)),
+                             ShimmerHall.PATCHES[0][1])
+            out = kc.samples(kc.render(e, 24000))
+        finally:
+            e.deinit()
+        self.assertEqual(list(out), list(clean))
+
+    def test_a_character_move_recuts_the_wet_chain(self):
+        # After a Character move, the wet path renders as a fresh
+        # instance's in that character, and the dry carries on.
+        values = t6_material(48000, 2, 2)
+        for start, end in (("bloom", 3), ("rise", 0)):
+            fresh_wet = render(ShimmerHall, values[2 * 9728:], 48000, 2,
+                               19200, patch=end)
+            feed = kc.feed(values, 48000, 2)
+            e = ShimmerHall(feed.port, character=start)
+            try:
+                kc.render(e, 9728)
+                e.program_change(end)
+                out = kc.samples(kc.render(e, 19200))
+            finally:
+                e.deinit()
+            self.assertEqual(list(out), list(fresh_wet), start)
+
+    def test_the_hall_follows_decay_size_and_damping(self):
+        e = ShimmerHall(_port())
+        try:
+            hall = e._hall
+            for ours, theirs in ((DECAY_I, 1), (SIZE_I, 2), (DAMPING_I, 5)):
+                for midi in (0, 37, 127):
+                    e.set_macro(ours, midi)
+                    self.assertAlmostEqual(hall.macro(theirs), e.macro(ours),
+                                           delta=abs(e.macro(ours)) * 1e-12)
+            self.assertEqual(hall.macro(0), 4.0)
+            self.assertEqual(hall.macro(12), 2.0)
+        finally:
+            e.deinit()
+
+    def test_a_size_move_empties_the_hall(self):
+        for character in ("bloom", "rise"):
+            values = burst(48000, 1, 247.0, 0, 48000)
+            feed = kc.feed(values, 48000, 1)
+            e = ShimmerHall(feed.port, character=character, rise=0.0,
+                            mix=2.0)
+            try:
+                kc.render(e, 256 * 188)
+                ringing = kc.samples(kc.render(e, 1024))
+                e.set_macro(SIZE_I, 0)
+                after = kc.samples(kc.render(e, 8192))
+            finally:
+                e.deinit()
+            self.assertGreater(max(abs(x) for x in ringing), 20, character)
+            self.assertEqual(max(abs(x) for x in after), 0, character)
+
+    def test_the_input_ceiling(self):
+        # Every level at the top, a steady 100 Hz square: clean at -24
+        # dBFS, on the rail at -12.
+        import kit_ceiling
+        self.assertEqual(ShimmerHall.INPUT_CEILING_DBFS, -24.0)
+        full = dict(shimmer=1.0, mix=1.0, decay=10.0, size=1.5,
+                    damping_hz=16000.0, bloom_ms=20.0, interval=12)
+        for options in (dict(full, character="bloom"),
+                        dict(full, character="rise", rise=0.9)):
+            verdict, _digest = kit_ceiling.measure(
+                ShimmerHall, 48000, 2, "square", None, None, options)
+            self.assertEqual(verdict, "ok", options)
+        try:
+            ShimmerHall.INPUT_CEILING_DBFS = -12.0
+            verdict, _digest = kit_ceiling.measure(
+                ShimmerHall, 48000, 2, "square", None, None,
+                dict(full, character="bloom"))
+        finally:
+            del ShimmerHall.INPUT_CEILING_DBFS
+        self.assertIn("rail", verdict)
+
+    def test_the_tempo_is_never_read(self):
+        def transport():
+            raise AssertionError("read the transport")
+        feed = kc.feed(array("h", bytes(16)), 48000, 2)
+        e = ShimmerHall(feed.port, transport=transport)
+        try:
+            for i in range(9):
+                e.set_macro(i, 127)
+            e.transport_changed()
+        finally:
+            e.deinit()
+
+    def test_without_get_buffer_plays_what_it_plays_with_it(self):
+        for name, build, moves in GET_BUFFER_CASES:
+            _values, out = without_get_buffer(build, moves)
+            _values, want = without_get_buffer(build, moves, hide=False)
+            self.assertEqual(list(out), list(want), name)
+
+
+class T1TheStagger(TestCase):
+    def test_the_octave_lands_bloom_after_you_play(self):
+        for rate in RATES:
+            for seed in SEEDS[:2]:
+                errors, onsets = t1_read(ShimmerHall, rate, seed)
+                self.assertIsNotNone(errors, (rate, seed, onsets))
+                for error in errors:
+                    self.assertLessEqual(abs(error), T1_BAR,
+                                         (rate, seed, onsets))
+
+    def test_pinned_stagger_is_red(self):
+        errors, onsets = t1_read(PinnedStagger, 48000, 0)
+        self.assertGreater(max(abs(x) for x in errors), T1_BAR, onsets)
+
+
+class T2TheInterval(TestCase):
+    def test_the_shift_is_the_interval(self):
+        for character in ("bloom", "rise"):
+            for interval in INTERVALS:
+                rate = 48000 if interval > 0 else 22050
+                mean = t2_read(ShimmerHall, rate, character, interval, 1)
+                self.assertLessEqual(abs(mean - interval),
+                                     T2_BARS[character][interval],
+                                     (character, interval, mean))
+
+    def test_always_octave_is_red(self):
+        for character in ("bloom", "rise"):
+            for interval in (-12, -5, 7, 24):
+                mean = t2_read(AlwaysOctave, 48000, character, interval, 1)
+                self.assertGreater(abs(mean - interval),
+                                   T2_BARS[character][interval],
+                                   (character, interval, mean))
+
+
+class T3TheClimb(TestCase):
+    def test_each_octave_arrives_one_bloom_later(self):
+        for rate, bloom, seed in ((48000, 200.0, 0), (22050, 400.0, 1)):
+            onsets, error = t3_read(ShimmerHall, rate, bloom, seed)
+            self.assertIsNone(t3_verdict(onsets, error),
+                              (rate, bloom, seed))
+
+    def test_pinned_loop_is_red(self):
+        for bloom in (200.0, 400.0):
+            onsets, error = t3_read(PinnedLoop, 48000, bloom, 0)
+            self.assertIsNotNone(t3_verdict(onsets, error), (bloom, onsets))
+
+
+class T4TheReturn(TestCase):
+    def test_rise_sets_how_strongly_each_pass_returns(self):
+        for rate, f0, offset in t4_cells():
+            gain, same, alive = t4_read(ShimmerHall, rate, f0, offset)
+            self.assertLessEqual(abs(gain - 19.0), 3.0, (rate, f0, gain))
+            self.assertTrue(same, (rate, f0))
+            self.assertGreater(alive, -20.0, (rate, f0, alive))
+
+    def test_held_feedback_is_red(self):
+        gain, _same, _alive = t4_read(HeldFeedback, 48000, 247.0, 13)
+        self.assertGreater(abs(gain - 19.0), 3.0, gain)
+
+    def test_rise_in_bloom_is_red(self):
+        _gain, same, _alive = t4_read(RiseInBloom, 48000, 247.0, 13)
+        self.assertFalse(same)
+
+
+class T5TheDamping(TestCase):
+    def test_damping_stops_the_climb(self):
+        for rate, f0, offset in t5_cells():
+            drop = t5_read(ShimmerHall, rate, f0, offset)
+            self.assertGreaterEqual(drop, 12.0, (rate, f0, drop))
+
+    def test_undamped_loop_is_red(self):
+        for f0 in (165.0, 330.0):
+            drop = t5_read(UndampedLoop, 48000, f0, 13)
+            self.assertLess(drop, 12.0, (f0, drop))
+
+
+class T6TheDry(TestCase):
+    def test_the_dry_never_carries_the_shimmer(self):
+        for rate in RATES:
+            for channels in (2, 1):
+                for patch in T6_PATCHES:
+                    worst, loud = t6_read(ShimmerHall, rate, channels, patch,
+                                          rate % 7 + patch)
+                    self.assertEqual(worst, 0, (rate, channels, patch))
+                    self.assertLess(loud, 32767, (rate, channels, patch))
+
+    def test_late_dry_is_red(self):
+        worst, _loud = t6_read(LateDry, 48000, 2, 0, 1)
+        self.assertGreater(worst, 1000)
+
+
+#: Every claim sentence of the class docstring and the test that holds it.
+CLAIMS = (
+    ("`ShimmerHall` - a hall that rings an octave above what you play.",
+     ("test_a_fresh_instance_reads_patch_0",
+      "test_the_shift_is_the_interval")),
+    ("In Bloom the shifted copy goes into the hall once, Bloom after you "
+     "play, and the whole hall waits for it.",
+     ("test_the_octave_lands_bloom_after_you_play",
+      "test_pinned_stagger_is_red", "test_rise_sets_how_strongly_each_pass_"
+      "returns", "test_rise_in_bloom_is_red")),
+    ("In Rise the shifter sits in a feedback loop: the hall starts at once, "
+     "and each pass comes back shifted again, so the tail climbs while "
+     "Damping darkens every pass until it fades.",
+     ("test_each_octave_arrives_one_bloom_later", "test_pinned_loop_is_red",
+      "test_damping_stops_the_climb", "test_undamped_loop_is_red")),
+    ("Shimmer (0 to 1) is how loud the shifted copy goes into the hall.",
+     ("test_the_spans", "test_the_shift_is_the_interval")),
+    ("Bloom (20 to 800 ms) is the wait in Bloom and the time between passes "
+     "in Rise.",
+     ("test_the_spans", "test_the_octave_lands_bloom_after_you_play",
+      "test_each_octave_arrives_one_bloom_later")),
+    ("Rise (0 to 0.9) is how strongly each pass returns, in Rise only.",
+     ("test_the_spans", "test_rise_sets_how_strongly_each_pass_returns",
+      "test_held_feedback_is_red", "test_rise_in_bloom_is_red")),
+    ("Interval picks one of five shifts: -12, -5, +7, +12 or +24 semitones.",
+     ("test_interval_has_five_zones", "test_the_shift_is_the_interval",
+      "test_always_octave_is_red")),
+    ("Decay (0.3 to 10 s), Size (0.5 to 1.5) and Damping (500 Hz to 16 kHz) "
+     "set the hall, and Damping also darkens each pass of the loop.",
+     ("test_the_spans", "test_the_hall_follows_decay_size_and_damping",
+      "test_damping_stops_the_climb", "test_undamped_loop_is_red")),
+    ("Mix (0 to 2) is `audiodelays.Echo`'s: your dry signal at unity up to "
+     "1, the hall alone at 2.",
+     ("test_the_spans", "test_the_dry_never_carries_the_shimmer")),
+    ("In Bloom, move Bloom and the shifted copy moves by the same time, "
+     "within 512 frames.",
+     ("test_the_octave_lands_bloom_after_you_play",
+      "test_pinned_stagger_is_red")),
+    ("Its energy centres within 2.5 semitones of the Interval.",
+     ("test_the_shift_is_the_interval", "test_always_octave_is_red")),
+    ("In Rise the loop's short window spreads the first pass wider: within "
+     "2.5 semitones at -5 and +7, 3.5 at +12 and 6 at -12 and +24.",
+     ("test_the_shift_is_the_interval", "test_always_octave_is_red")),
+    ("In Rise at +12 each octave arrives one Bloom after the one below, "
+     "within 20 %.",
+     ("test_each_octave_arrives_one_bloom_later", "test_pinned_loop_is_red")),
+    ("Moving Rise from 0.3 to 0.9 brings the third pass back 16 to 22 dB "
+     "stronger against the first, and in Bloom Rise changes nothing.",
+     ("test_rise_sets_how_strongly_each_pass_returns",
+      "test_held_feedback_is_red", "test_rise_in_bloom_is_red")),
+    ("With Damping at 800 Hz the fourth pass is at least 12 dB weaker "
+     "against the first than at 16 kHz.",
+     ("test_damping_stops_the_climb", "test_undamped_loop_is_red")),
+    ("Up to Mix 1 your dry signal passes untouched, sample for sample: the "
+     "shimmer is only ever in the hall.",
+     ("test_the_dry_never_carries_the_shimmer", "test_late_dry_is_red")),
+    ("At Mix 0 the output is your input, byte for byte.",
+     "test_mix_0_is_the_input"),
+    ("Latency is zero.", "test_no_latency"),
+    ("Keep your input at or under -24 dBFS: with Decay, Size, Shimmer and "
+     "Rise at the top, a steady loud input fills the hall to the rail.",
+     "test_the_input_ceiling"),
+    ("`tail_samples` bounds how long the output takes to reach exact zero "
+     "once your input stops.",
+     ("test_tail_samples", "test_tail_is_zero_at_mix_0")),
+    ("`reset()` empties the hall, the line and the shifter, and restores "
+     "patch 0.", "test_reset_empties_the_graph_and_returns_to_patch_0"),
+    ("Moving Character or Size empties the hall: the tail drops and the dry "
+     "carries on.",
+     ("test_a_character_move_recuts_the_wet_chain",
+      "test_a_size_move_empties_the_hall")),
+    ("Interval is a fixed shift in semitones, with no key awareness.",
+     "test_interval_has_five_zones"),
+    ("A value outside a macro's span clamps to the nearer stop, and NaN "
+     "takes the default; an `interval` other than the five raises "
+     "`ValueError`.", "test_the_constructor"),
+)
+
+
+# --------------------------------------------------------------------------
+# The figures on whichever interpreter runs this file
+
+
+def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
+    """Print each trait's numbers over every cell the card names, eight
+    seed sets each: the evidence pack's rows."""
+    name = sys.implementation.name
+    if "T1" in which:
+        for rate in RATES:
+            worst = 0
+            spread = []
+            for seed in SEEDS:
+                errors, onsets = t1_read(ShimmerHall, rate, seed)
+                if errors is None:
+                    print("%s|T1|%d|seed %d|no onset %r" % (name, rate, seed,
+                                                           onsets))
+                    continue
+                spread += errors
+                worst = max(worst, max(abs(x) for x in errors))
+            print("%s|T1|%d|errors %d..%d frames|worst %d|bar %d" % (
+                name, rate, min(spread), max(spread), worst, T1_BAR))
+        errors, _onsets = t1_read(PinnedStagger, 48000, 0)
+        print("%s|T1|plant 48000|errors %r" % (name, errors))
+    if "T2" in which:
+        for character in ("bloom", "rise"):
+            for interval in INTERVALS:
+                got = []
+                for rate in RATES:
+                    for seed in SEEDS:
+                        got.append(t2_read(ShimmerHall, rate, character,
+                                           interval, seed) - interval)
+                print("%s|T2|%s|%+d|error %.2f..%.2f st|bar %.1f" % (
+                    name, character, interval, min(got), max(got),
+                    T2_BARS[character][interval]))
+            plant = [t2_read(AlwaysOctave, 48000, character, i, 1) - i
+                     for i in (-12, -5, 7, 24)]
+            print("%s|T2|%s|plant errors %s" % (
+                name, character, " ".join("%.1f" % x for x in plant)))
+    if "T3" in which:
+        for bloom in (200.0, 400.0):
+            errors = []
+            fails = 0
+            for rate in RATES:
+                for seed in SEEDS:
+                    onsets, error = t3_read(ShimmerHall, rate, bloom, seed)
+                    bad = t3_verdict(onsets, error)
+                    if bad:
+                        fails += 1
+                        print("%s|T3|RED|%d|%g|%d|%s" % (name, rate, bloom,
+                                                         seed, bad))
+                    if error is not None:
+                        errors.append(100.0 * error)
+            plant = t3_read(PinnedLoop, 48000, bloom, 0)[1]
+            print("%s|T3|Bloom %g|runs 16|red %d|spacing %.1f..%.1f %%|"
+                  "plant %.1f %%" % (name, bloom, fails, min(errors),
+                                     max(errors), 100.0 * plant))
+    if "T4" in which:
+        gains = []
+        alive = []
+        same = True
+        for rate, f0, offset in t4_cells(True):
+            g, s, a = t4_read(ShimmerHall, rate, f0, offset)
+            gains.append(g)
+            alive.append(a)
+            same = same and s
+        held = t4_read(HeldFeedback, 48000, 247.0, 13)[0]
+        bloom = t4_read(RiseInBloom, 48000, 247.0, 13)[1]
+        print("%s|T4|runs %d|gain %.1f..%.1f dB|Bloom identical %r|Bloom "
+              "2f0 against Rise 0.9 %.1f..%.1f dB|plant held %.1f dB|plant "
+              "Rise in Bloom identical %r" % (
+                  name, len(gains), min(gains), max(gains), same,
+                  min(alive), max(alive), held, bloom))
+    if "T5" in which:
+        for f0 in (165.0, 330.0):
+            drops = [t5_read(ShimmerHall, rate, f, offset)
+                     for rate, f, offset in t5_cells(True) if f == f0]
+            plant = t5_read(UndampedLoop, 48000, f0, 13)
+            print("%s|T5|f0 %g|runs %d|drop %.1f..%.1f dB|plant %.1f dB" % (
+                name, f0, len(drops), min(drops), max(drops), plant))
+    if "T6" in which:
+        worst = loud = runs = 0
+        for rate in RATES:
+            for channels in (2, 1):
+                for patch in T6_PATCHES:
+                    for seed in SEEDS:
+                        w, lo = t6_read(ShimmerHall, rate, channels, patch,
+                                        seed)
+                        worst = max(worst, w)
+                        loud = max(loud, lo)
+                        runs += 1
+        plant = t6_read(LateDry, 48000, 2, 0, 1)[0]
+        print("%s|T6|runs %d|worst %d LSB|loudest %d|plant %d LSB" % (
+            name, runs, worst, loud, plant))
+    if "L" in which:
+        for rate in (48000, 44100):
+            for channels in (2, 1):
+                values = array("h", bytes(2 * channels * 4096))
+                for c in range(channels):
+                    values[1000 * channels + c] = 12000
+                out = render(ShimmerHall, values, rate, channels, 4096,
+                             mix=1.0)
+                first = None
+                for n in range(4096):
+                    if out[n * channels]:
+                        first = n
+                        break
+                e = ShimmerHall(kc.feed(values, rate, channels).port)
+                stated = e.latency_samples
+                e.deinit()
+                print("%s|L|%d|%d|latency_samples %d|click at +%d" % (
+                    name, rate, channels, stated, first - 1000))
+
+
+if __name__ == "__main__":
+    if unittest is not None and "--figures" not in sys.argv:
+        unittest.main()
+    else:
+        # By name, not as __main__: a plant reads VENDOR from the module
+        # that defines it, and natively __main__ is not one it can find.
+        import test_cpython_effects_shimmerhall as module
+        picked = [a for a in sys.argv[1:] if a[:1] in ("T", "L")]
+        module.figures(tuple(picked)
+                       or ("T1", "T2", "T3", "T4", "T5", "T6", "L"))

From 49d9dfad07a914c4c582f86855915ac9c32e7bcb Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 01:47:40 -0500
Subject: [PATCH 35/76] Node matrix: CircuitPython's upstream Echo, pitch
 shifters and Mixer keep the behaviour audiodsp v0.6.6rc1 fixed elsewhere
 (KNOWN_P6)

---
 tests/test_node_matrix.py | 51 +++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/tests/test_node_matrix.py b/tests/test_node_matrix.py
index 08019f3..e41b86f 100644
--- a/tests/test_node_matrix.py
+++ b/tests/test_node_matrix.py
@@ -25,14 +25,42 @@
 import lifecycle                                          # noqa: E402
 import node_matrix                                        # noqa: E402
 from tests.test_lifecycle_matrix import (FULL, check_known,  # noqa: E402
-                                   native_binaries, parse, red_cells,
-                                   skipped)
+                                   digest, native_binaries, parse,
+                                   red_cells, skipped)
 
 VENDOR = "PyDevices"
 
 #: What is red today, in the same shape as test_lifecycle_matrix.KNOWN_RED.
 KNOWN_RED = {}
 
+#: P6 differences today, in the same shape as test_lifecycle_matrix.KNOWN_P6:
+#: node -> (cells whose line differs between CPython and a native
+#: interpreter in the quick matrix, their digest, the same for the full
+#: matrix, reason). MicroPython prints CPython's lines for every node; these
+#: are CircuitPython's. Each is a fix in audiodsp v0.6.6rc1 that CPython and
+#: MicroPython take and CircuitPython does not, because there these nodes
+#: are upstream's own and keep upstream's behaviour (audiodsp's
+#: docs/upstream-diff.md records each).
+KNOWN_P6 = {
+    "NodeEcho": (
+        30, "206fe02a", None, None,
+        "a Time move or a patch change shortens the line under the write "
+        "head: upstream's Echo plays one stray sample when it grows back "
+        "(audiodsp#241)"),
+    "NodePitchShift": (
+        12, "1e08a674", None, None,
+        "upstream's reset keeps the read and write positions, so after a "
+        "reset at the fifth the splice falls elsewhere (audiodsp#240)"),
+    "NodeGranularPitchShift": (
+        4, "91e67a25", None, None,
+        "upstream's reset_buffer keeps the jitter sequence, so the grains "
+        "after it start at other offsets (audiodsp#240)"),
+    "NodeSplitMix": (
+        32, "4f7dcebd", None, None,
+        "a host reset of upstream's Mixer re-primes its voices and drops the "
+        "source frames they held (audiodsp#229)"),
+}
+
 
 def names():
     wanted = os.environ.get("LIFECYCLE_CLASSES")
@@ -99,12 +127,19 @@ def _p6(self, family):
         for name in self.names:
             ours = parse(self.cpython[name])
             theirs = parse([l for l in got if l.startswith(name + "|")])
-            for key in sorted(set(ours) | set(theirs)):
-                if ours.get(key) != theirs.get(key) \
-                        and not skipped(theirs.get(key)):
-                    problems.append("%s: %s cpython %s, %s %s" % (
-                        family, "|".join(map(str, key)), ours.get(key),
-                        family, theirs.get(key)))
+            keys = [key for key in sorted(set(ours) | set(theirs))
+                    if ours.get(key) != theirs.get(key)
+                    and not skipped(theirs.get(key))]
+            entry = KNOWN_P6.get(name)
+            if entry is not None:
+                count, dig = (entry[2], entry[3]) if FULL else entry[:2]
+                if count is None or (len(keys), digest(keys)) == (count,
+                                                                  dig):
+                    continue
+            for key in keys:
+                problems.append("%s: %s cpython %s, %s %s" % (
+                    family, "|".join(map(str, key)), ours.get(key),
+                    family, theirs.get(key)))
         self.assertEqual(problems, [], "\n".join(problems[:60]))
 
     def test_p6_micropython(self):

From 0a69a2fb1129e5dd90b2ebeaeadbbc48e4a05ee2 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:08:40 -0500
Subject: [PATCH 36/76] Octaver: Octave 2 on its own flip-flop; voices armed
 quietly

Octave 2 divided Octave 1's own waveform, so once the comparator's switch
drifted off the zero crossing on a decaying note it also counted the
near-zero junctions where the multiplied humps meet, and turned into a
fourth below (G3 and B3 with the Tones open). It is now the pedal's second
flip-flop: a SubOctave(order=2) on the same comparator, whose square
multiplies the all-passed signal, then Tone 1 and Tone 2. The decay test
compares f/4 with 3f/4 as well as f/2, at E2 to B3, Sensitivity 0 and 64,
both rates, Tones open and at patch 0; the old graph is the ToneClocked
plant.

The voices are armed once behind a Port playing a sourceless MidSide, and
that block is dropped (get_buffer, or a one-voice puller mixer where it is
compiled out, through a width-1 MidSide tail after the Mixer). No move
into or out of the wire skips a block any more; the disclosed sentence and
the wide P1 lifecycle row are gone, with P1 rows kept only where Octave 1
at 0 is not the wire. Lifecycle keys may name patches.
---
 lib/audioeffects/rebuilt/octaver.py   | 200 ++++++++++++++++----------
 tests/support/lifecycle.py            |  67 ++++-----
 tests/test_cpython_effects_octaver.py | 189 +++++++++++++++---------
 3 files changed, 281 insertions(+), 175 deletions(-)

diff --git a/lib/audioeffects/rebuilt/octaver.py b/lib/audioeffects/rebuilt/octaver.py
index 6b32df0..de515c5 100644
--- a/lib/audioeffects/rebuilt/octaver.py
+++ b/lib/audioeffects/rebuilt/octaver.py
@@ -126,7 +126,7 @@ class Octaver(_component.Component):
     A stereo source is clocked on its mid: with the right channel 45
     degrees ahead of the left, the fifth sits 3.2 dB under the octave
     instead of 4.4, on both channels.
-    The output can peak at about 4.2 times the input (a square, all three
+    The output can peak at about 3.8 times the input (a square, all three
     levels at full with the Tones open), so keep the input under -13 dBFS.
     A control that jumps makes the output step: move it in small steps
     from the host if you need it smooth.
@@ -134,8 +134,6 @@ class Octaver(_component.Component):
     **Wire, latency, tail.** With both octaves at 0 and Direct at 1 the
     output is the input, byte for byte, however the host's buffers are
     cut.
-    Reaching that setting before the first block after an octave comes in
-    skips that one block of 256 frames.
     There is no latency.
     `tail_samples` covers the all-pass and the two Tone filters ringing
     down.
@@ -156,7 +154,7 @@ class Octaver(_component.Component):
     TAIL_SAMPLES = None
 
     #: The worst peak gain over the kit's material, every patch and every
-    #: stop, is 4.24 (a square, all three levels at full with the Tones
+    #: stop, is 3.75 (a square, all three levels at full with the Tones
     #: open): -13 dBFS keeps it inside full scale.
     INPUT_CEILING_DBFS = -13.0
 
@@ -213,43 +211,65 @@ def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
             reset=False)
         self._adapter.play(self._source)
 
-        # One Splitter, three legs: the dry voice, the signal the octave is
-        # made of, and the clock that says when to turn it over. The clock
-        # and the signal are kept apart because `SubOctave` clocks on what
-        # it divides, so a tracking filter in front of it would darken the
-        # octave too (12 dB from E2 to G3, measured on the card's probes).
-        split = self._own(audioroute.Splitter(self._adapter, taps=3),
+        # The graph reads the adapter through a Port. While the voices are
+        # armed it plays a MidSide with no source instead, one block of
+        # zeros per pull, which the arming pull drops (`_arm`): arming
+        # takes nothing from the source, so no voice ever holds a block the
+        # wire would skip.
+        self._hush = self._own(audioroute.MidSide(
+            width=1.0, sample_rate=rate, channel_count=channels),
+            reset=False)
+        self._in = self._own(audioroute.Port(self._hush), reset=False)
+
+        # One Splitter, three legs: the dry voice, the signal the octaves
+        # are made of, and the clock that says when to turn it over. The
+        # clock and the signal are kept apart because `SubOctave` clocks on
+        # what it divides, so a tracking filter in front of it would darken
+        # the octave too (12 dB from E2 to G3, measured on the card's
+        # probes).
+        split = self._own(audioroute.Splitter(self._in, taps=3),
                           reset=False)
         self._dry = split.tap(0)
         self._allpass = None
         self._clock = []
-        signal = self._signal_leg(split.tap(1))
-        square = self._clock_leg(split.tap(2))
-        self._product = self._octave(signal, square)
-        self._tone1 = self._own(audiobiquad.Biquad(
-            mode=audiobiquad.LOW_PASS, frequency=324.0, Q=TONE_Q, mix=1.0,
-            sample_rate=rate, channel_count=channels))
-        self._tone1.play(self._product)
-
-        # Octave 2 divides Octave 1's filtered output, on that signal's own
-        # crossings, as the pedal's second stage does.
-        split2 = self._own(audioroute.Splitter(self._tone1, taps=2),
-                           reset=False)
-        self._octave1 = split2.tap(0)
-        self._divider2 = self._second(split2.tap(1))
-        self._tone2 = self._own(audiobiquad.Biquad(
-            mode=audiobiquad.LOW_PASS, frequency=70.3, Q=TONE_Q, mix=1.0,
-            sample_rate=rate, channel_count=channels))
-        self._tone2.play(self._divider2)
-
-        # Not reset: the voices keep the source frames they have taken, and
+        signal = self._own(audioroute.Splitter(
+            self._signal_leg(split.tap(1)), taps=2), reset=False)
+        ticks = self._own(audioroute.Splitter(
+            self._clock_leg(split.tap(2)), taps=2), reset=False)
+        self._divider = self._first(ticks.tap(0))
+        self._product = self._octave(signal.tap(0), self._divider)
+        self._tone1 = self._tone(self._product, 324.0)
+        self._octave1 = self._tone1
+
+        # Octave 2 is the pedal's second flip-flop, clocked by the first:
+        # the signal times a square at a quarter of the note, made from the
+        # same comparator, so it turns over on the crossings Octave 1 does.
+        # Divided on Octave 1's own waveform instead, the divider also
+        # counted the near-zero junctions where the multiplication's humps
+        # meet, and on a decaying note it turned into a fourth below.
+        self._product2 = self._second(signal.tap(1), ticks.tap(1))
+        self._tone1b = self._tone(self._product2, 324.0)
+        self._tone2 = self._tone(self._tone1b, 70.3)
+
+        # Not reset: no voice holds a block between two pulls (`_arm`), and
         # a Mixer reset is no reset of anything this class holds. A Mixer
         # renders half its buffer per pull, so BLOCK frames take four bytes
         # a sample: with half that, every other pull left a voice holding
         # half a block, which a move into the wire then skipped.
         self._mixer = self._own(audiomixer.Mixer(
             voice_count=3, **self._pcm(BLOCK * channels * 4)), reset=False)
-        self._output = self._mixer
+        # The mixer's output: a width-1 MidSide, byte for byte, whose reset
+        # forwards nothing. A host's reset of the output (a mixer voice's
+        # `play()` does one) would otherwise reach the Mixer, and
+        # CircuitPython's own Mixer drops its voices' blocks on one.
+        self._tail = self._own(audioroute.MidSide(
+            self._mixer, width=1.0, sample_rate=rate,
+            channel_count=channels), reset=False)
+        #: Where `audiocore.get_buffer` is compiled out, the one-voice
+        #: mixer `_pull` primes from `_tail`; built the first time it is
+        #: needed.
+        self._puller = None
+        self._output = self._tail
 
         self._init_macros(tuple(
             _component.macro_value(self._MACRO_RANGES[i], grid[i] / 127.0)
@@ -305,9 +325,9 @@ def _mid(self, tap):
         return mid
 
     def _clock_leg(self, tap):
-        """Low-pass at Tracking, a comparator with a dead band, and a
-        divider that hands out a +-1 square at half the note (zero while the
-        comparator reads zero)."""
+        """Low-pass at Tracking and a comparator with a dead band: a
+        +-rail square at the note, zero while the clock is under
+        Sensitivity."""
         clock = self._mid(tap)
         for _ in range(2):
             section = self._own(audiobiquad.Biquad(
@@ -323,11 +343,20 @@ def _clock_leg(self, tap):
             oversample=1, mix=1.0, pre_gain=self._pre_gain(DEFAULTS[SENS_I]),
             post_gain=1.0))
         self._comparator.play(clock)
-        self._divider = self._own(audiomath.SubOctave(
-            self._comparator, order=1, mix=1.0, threshold=CLOCK_THRESHOLD,
+        return self._comparator
+
+    def _divide(self, tap, order):
+        """A divider on the comparator: a +-1 square at a half (order 1)
+        or a quarter (order 2) of the note, zero while the comparator
+        reads zero. Both orders count the same crossings, so the quarter
+        turns over only where the half does."""
+        return self._own(audiomath.SubOctave(
+            tap, order=order, mix=1.0, threshold=CLOCK_THRESHOLD,
             hold_ms=CLOCK_HOLD_MS, sample_rate=self._sample_rate,
             channel_count=self._channel_count))
-        return self._divider
+
+    def _first(self, tap):
+        return self._divide(tap, 1)
 
     def _curve(self):
         return comparator_curve()
@@ -337,24 +366,26 @@ def _pre_gain(self, sensitivity_db):
 
     def _octave(self, signal, square):
         """The signal times the square: every other cycle turned over."""
+        return self._multiply(signal, square)
+
+    def _multiply(self, signal, square):
         return self._own(audiomath.Multiply(
             signal, square, mix=1.0, sample_rate=self._sample_rate,
             channel_count=self._channel_count))
 
-    def _second(self, tap):
-        """Octave 1's output divided again, counting down to Sensitivity:
-        at `SubOctave`'s own threshold (0.01, -40 dBFS) it would stop
-        counting on every decaying tail and pass Octave 1's f/2."""
-        return self._own(audiomath.SubOctave(
-            tap, order=1, mix=1.0,
-            threshold=self._threshold2(DEFAULTS[SENS_I]),
+    def _second(self, signal, tick):
+        """Octave 2: the signal times the quarter-note square, which is
+        Octave 1 with every other cycle turned over."""
+        return self._multiply(signal, self._divide(tick, 2))
+
+    def _tone(self, source, hz):
+        """A Tone low-pass on `source`."""
+        node = self._own(audiobiquad.Biquad(
+            mode=audiobiquad.LOW_PASS, frequency=hz, Q=TONE_Q, mix=1.0,
             sample_rate=self._sample_rate,
             channel_count=self._channel_count))
-
-    def _threshold2(self, sensitivity_db):
-        """The second divider's threshold: Sensitivity's own level, so it
-        counts as far down as the clock leg does."""
-        return 10.0 ** (sensitivity_db / 20.0)
+        node.play(source)
+        return node
 
     def _set_tracking(self, hz):
         if self._allpass is not None:
@@ -376,13 +407,14 @@ def _apply_macro(self, index, position):
         if index == TRACKING_I:
             self._set_tracking(self._hz(self._value(TRACKING_I)))
         elif index == TONE1_I:
-            self._tone1.frequency = self._tone1_hz()
+            hz = self._tone1_hz()
+            self._tone1.frequency = hz
+            self._tone1b.frequency = hz
         elif index == TONE2_I:
             self._tone2.frequency = self._hz(self._value(TONE2_I))
         elif index == SENS_I:
             sensitivity = self._value(SENS_I)
             self._comparator.set(pre_gain=self._pre_gain(sensitivity))
-            self._divider2.set(threshold=self._threshold2(sensitivity))
         else:
             self._route()
 
@@ -399,41 +431,65 @@ def _levels(self):
 
     def _route(self):
         """Direct at 1 with both octaves at 0 hands out the input adapter,
-        the source byte for byte; anything else plays the mixer, re-armed
-        if the graph was left."""
+        the source byte for byte; anything else plays the mixer, armed the
+        first time it is reached."""
         if self._is_wire():
             self._route_around(self._adapter)
             return
         if not self._ready:
             self._levels()
             return
-        if self._rejoin() or not self._armed:
+        self._rejoin()
+        if not self._armed:
             self._arm()
             self._armed = True
-        self._output = self._mixer
+        self._output = self._tail
         self._levels()
 
     def _arm(self):
-        """Levels, gates, then the voices, as the graph is first built and
-        whenever it comes back from the wire (its nodes are clear by then).
-
-        A voice's `play()` primes one block from its source, which the next
-        pull plays on time. Between two pulls after that no voice holds a
-        block and every tap is caught up, because the adapter hands
-        256-frame blocks and the Mixer pulls 256 frames: a move into the
-        wire hands out the adapter with nothing left behind. Only a move
-        into the wire before the first pull after arming skips the primed
-        block. Re-arming on the way back, rather than letting the voices
-        carry on, is what keeps that block from playing late, after a
-        stretch of the wire; `audiocore.get_buffer`, which could hand it
-        out at once, is compiled out of CircuitPython's board builds."""
-        self._levels()
-        _component.open_level_gates(self._mixer, self._mixer.voice,
-                                    self._silence)
+        """Play the voices, the first time the output reaches the mixer.
+
+        Each voice first plays silence for one pull, which opens its level
+        gate (as `_component.open_level_gates` does). A voice's `play()`
+        then primes one block from its source: with the Port on `_hush`
+        that block is zeros, and a second pull hands it out, so arming
+        takes nothing from the source. Between two pulls after that no
+        voice holds a block and every tap is caught up, because the adapter
+        hands 256-frame blocks and the Mixer pulls 256 frames: a move into
+        the wire hands out the adapter with nothing left behind, and the
+        way back carries on from where the wire stopped."""
         voices = self._mixer.voice
+        self._levels()
+        for voice in voices:
+            voice.play(self._silence, loop=True)
+        self._pull()
+        self._in.play(self._hush)
         voices[0].play(self._dry, loop=True)
         voices[1].play(self._octave1, loop=True)
         voices[2].play(self._tone2, loop=True)
+        self._pull()
+        self._in.play(self._adapter)
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `_tail` and stops: its `play()` primes one block, which pulls
+        the mixer once. `_tail` forwards no reset, so the play rewinds
+        nothing behind it."""
+        pull = getattr(audiocore, "get_buffer", None)
+        if pull is not None:
+            pull(self._mixer)
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # small: two stereo frames.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, **self._pcm(16)), reset=False)
+        voice = self._puller.voice[0]
+        voice.play(self._tail)
+        voice.stop()
 
     @property
     def tail_samples(self):
@@ -447,7 +503,7 @@ def _tail_bound(self):
         ring = 0
         if self._allpass is not None:
             ring = _allpass_ring(self._allpass.coefficient)
-        tones = _component.cascade_ring((self._tone1, self._tone2))
+        tones = _component.cascade_ring((self._tone1b, self._tone2))
         if ring is None or tones is None:
             return None
         return ring + tones
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 15b8ed0..5ef2f29 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -72,21 +72,16 @@
 }
 
 #: Where a class cannot satisfy a property by design, it says so HERE, one
-#: row per (class NAME, event name prefix, property): reason. A matching
-#: cell prints `decl` instead of RED and is counted as a declared exception.
-#: Nothing else skips a cell.
+#: row per (class NAME, event name prefix, property): reason. A key may add
+#: a fourth element, the patches the row covers (None for the default), when
+#: the reason holds only at those. A matching cell prints `decl` instead of
+#: RED and is counted as a declared exception. Nothing else skips a cell.
 DECLARED = {
     ("Octaver", "E1-", "P4"):
         "a flip-flop divider keeps its count: a reset starts it in"
         " pass-through polarity part-way through the material, so the"
         " octave stays inverted against an instance that was never reset"
         " (it matches a fresh one; the OC-2's flip-flops do the same)",
-    ("Octaver", "E2-", "P4"):
-        "CircuitPython only: its own audiomixer.Mixer resets the voices on"
-        " a host reset, so Tone 2's voice loses the frames it held and"
-        " Octave 2 runs late against the others (audiodsp#229's upstream"
-        " half, ruled to be declared in Phase 6); CPython and MicroPython"
-        " are ok",
     ("Octaver", "E4-", "P4"):
         "a flip-flop divider keeps its count: a move that adds or drops a"
         " crossing (Tracking, Tone 1, Sensitivity) or the clear on the way"
@@ -104,26 +99,31 @@
     ("Octaver", "E9-", "P4"):
         "a flip-flop divider keeps its count: the clear on the way back"
         " from the wire (Octave 1 at 0) leaves the octave inverted for good",
-    ("Octaver", "E9-", "P1"):
-        "E9's P1 holds the wire from before the first pull: a voice's play()"
-        " primed one block from the source when the graph was armed, so the"
-        " wire starts one block in (disclosed; no audiocore.get_buffer on a"
-        " board build to hand the primed block out)",
-    ("Octaver", "E10-mix0", "P4"):
-        "the wire and back before the first pull: the way back re-arms the"
-        " voices, which skips the block they primed when the graph was"
-        " built, so the run is one block early against the control for good"
-        " (disclosed; no audiocore.get_buffer on a board build to hand the"
-        " primed block out; the same on the class before the wire fix)",
-    ("Octaver", "E", "P1"):
-        "Octave 1 at 0 is the wire only while Octave 2 is at 0 and Direct"
-        " at 1 (the defaults, patches 0, 3 and 4); at patches 1, 2 and 5,"
-        " and through an event that moves Direct or Octave 2 or changes to"
-        " one of those patches, it is a level move, and the output is not"
-        " the source by design. Where it is the wire, P1 holds it from"
-        " before the first pull, and the block the voices primed when the"
-        " graph was built is skipped (disclosed, as E9's row says); E5's"
-        " P1, a move into the wire mid-stream, is ok",
+    ("Octaver", "E", "P1", (1, 2, 5)):
+        "at patches 1, 2 and 5 Octave 2 is up or Direct is under 1, so"
+        " Octave 1 at 0 is a level move, not the wire, and the output is"
+        " not the source by design",
+    ("Octaver", "E4-m0=", "P1"):
+        "the event moves Direct off 1, so Octave 1 at 0 stops being the"
+        " wire and the output is not the source by design",
+    ("Octaver", "E4-m2=", "P1"):
+        "the event moves Octave 2 up, so Octave 1 at 0 stops being the"
+        " wire and the output is not the source by design",
+    ("Octaver", "E6-p1", "P1"):
+        "the event changes to patch 1, where Octave 1 at 0 is a level move,"
+        " not the wire, so the output is not the source by design",
+    ("Octaver", "E6-p2", "P1"):
+        "the event changes to patch 2, where Octave 1 at 0 is a level move,"
+        " not the wire, so the output is not the source by design",
+    ("Octaver", "E6-p5", "P1"):
+        "the event changes to patch 5, where Octave 1 at 0 is a level move,"
+        " not the wire, so the output is not the source by design",
+    ("Octaver", "E11-mix+patch", "P1"):
+        "the event ends on patch 5, where Octave 1 at 0 is a level move,"
+        " not the wire, so the output is not the source by design",
+    ("Octaver", "E11-3moves", "P1"):
+        "the event ends on patch 5, where Octave 1 at 0 is a level move,"
+        " not the wire, so the output is not the source by design",
     ("Octaver", "E5-", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step (the octave leaves and comes back)",
@@ -836,8 +836,11 @@ def _diagnose(out, expect, frame, fsize, hi):
     return ", not the source near there"
 
 
-def _decl(cls, ev, prop):
-    for (name, prefix, p), reason in DECLARED.items():
+def _decl(cls, ev, prop, patch=None):
+    for key in DECLARED:
+        name, prefix, p = key[:3]
+        if len(key) > 3 and patch not in key[3]:
+            continue
         if name == cls.NAME and p == prop and ev.name.startswith(prefix):
             return True
     return False
@@ -1166,7 +1169,7 @@ def run_cell(cls, ev, rate, channels, patch, options, controls):
                            controls))
     res["P5"] = p5(cls, ev, rate, channels, patch, options, controls)
     for prop in PROPS:
-        if res[prop].startswith("RED") and _decl(cls, ev, prop):
+        if res[prop].startswith("RED") and _decl(cls, ev, prop, patch):
             res[prop] = "decl"
     return res
 
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
index 79daeb1..506c0bb 100644
--- a/tests/test_cpython_effects_octaver.py
+++ b/tests/test_cpython_effects_octaver.py
@@ -367,24 +367,30 @@ def t4_split(cls, rate, channels, name, tones_open):
     return level_db(y, f / 4.0, rate) - level_db(y, 0.75 * f, rate)
 
 
-def t4_decay(cls, rate, name, tones_open):
-    """Octave 2's f/4 over its f/2, per 16/f window, on a sine decaying
-    -6 to -86 dBFS over 4 s at Sensitivity -90 dBFS, over every window
-    that ends before Octave 1's last sound (after the first two)."""
+def t4_decay(cls, rate, name, tones_open, sens=0):
+    """Octave 2's f/4 over the larger of its f/2 and its 3f/4, per 16/f
+    window, on a sine decaying -6 to -86 dBFS over 4 s at the Sensitivity
+    step `sens`, over every window that ends before Octave 1's last sound
+    (after the first two). Under f/2 it is passing Octave 1 on; under 3f/4
+    it has turned into a fourth below the note."""
     f = NOTES[name]
     n = 4 * rate
     x = [16384.0 * 10.0 ** (-80.0 * i / n / 20.0)
          * math.sin(2.0 * math.pi * f * i / rate) for i in range(n)]
     values = pcm(x)
     tones = OPEN if tones_open else ()
-    sens = ((SENS, 0),)
-    oct1 = render(cls, values, rate, 1, macros=ONLY1 + tones + sens)
-    oct2 = render(cls, values, rate, 1, macros=ONLY2 + tones + sens)
+    knob = ((SENS, sens),)
+    oct1 = render(cls, values, rate, 1, macros=ONLY1 + tones + knob)
+    oct2 = render(cls, values, rate, 1, macros=ONLY2 + tones + knob)
     last = max(i for i in range(len(oct1)) if oct1[i])
     width = int(round(16.0 * rate / f))
-    return [level_db(oct2[k * width:(k + 1) * width], f / 4.0, rate)
-            - level_db(oct2[k * width:(k + 1) * width], f / 2.0, rate)
-            for k in range(2, last // width)]
+    splits = []
+    for k in range(2, last // width):
+        part = oct2[k * width:(k + 1) * width]
+        under = level_db(part, f / 4.0, rate)
+        splits.append(under - max(level_db(part, f / 2.0, rate),
+                                  level_db(part, 0.75 * f, rate)))
+    return splits
 
 
 def t5_margin(y, f, rate):
@@ -526,26 +532,29 @@ def _pre_gain(self, sensitivity_db):
 class FourthBelow(Octaver):
     """T4: Octave 2 as `SubOctave(order=2)` on the all-passed dry."""
 
-    def _signal_leg(self, tap):
-        node = Octaver._signal_leg(self, tap)
-        fan = self._own(audioroute.Splitter(node, taps=2), reset=False)
-        self._fan = fan
-        return fan.tap(0)
-
-    def _second(self, tap):
+    def _second(self, signal, tick):
+        self._spare = tick
         return self._own(audiomath.SubOctave(
-            self._fan.tap(1), order=2, mix=1.0,
-            sample_rate=self._sample_rate,
+            signal, order=2, mix=1.0, sample_rate=self._sample_rate,
             channel_count=self._channel_count))
 
 
-class DefaultThreshold(Octaver):
-    """T4: Octave 2's divider at `SubOctave`'s default threshold, 0.01
-    (-40 dBFS), whatever Sensitivity says: under it the divider stops
-    counting and passes Octave 1's f/2."""
+class ToneClocked(Octaver):
+    """T4: Octave 2 as a divider on Octave 1's output after Tone 1,
+    counting down to Sensitivity, as the class was first built (then
+    through Tone 1 again, which the clean graph has there): on a
+    decaying note it also counts the near-zero junctions where the
+    multiplication's humps meet, and turns into a fourth below."""
 
-    def _threshold2(self, sensitivity_db):
-        return 0.01
+    def _second(self, signal, tick):
+        self._spare = (signal, tick)
+        fan = self._own(audioroute.Splitter(self._tone1, taps=2),
+                        reset=False)
+        self._octave1 = fan.tap(0)
+        return self._own(audiomath.SubOctave(
+            fan.tap(1), order=1, mix=1.0, threshold=10.0 ** (-80.0 / 20.0),
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
 
 
 class ClockWire(Octaver):
@@ -589,7 +598,7 @@ def _levels(self):
     "T3-wire": WireOctave,
     "T3-bin": OneBinCurve,
     "T4": (FourthBelow, 1),
-    "T4-thresh": (DefaultThreshold, 1),
+    "T4-tone1": (ToneClocked, 1),
     "T5": ClockWire,
     "T6": DoubleTone,
 }
@@ -743,18 +752,21 @@ def test_a_fourth_below_is_red(self):
         self.assertLess(t4_split(FourthBelow, 48000, 1, "E2", True), 6.0)
 
     def test_two_octaves_down_as_the_note_dies(self):
-        """A decaying sine: f/4 stays 6 dB over f/2 until Octave 1 stops."""
+        """A decaying sine: f/4 stays 6 dB over f/2 and over 3f/4 until
+        Octave 1 stops, at Sensitivity -90 and -65 dBFS."""
         for rate in RATES:
-            for name in ("E2", "A2"):
+            for name in self.NAMES:
                 for tones_open in (True, False):
-                    splits = t4_decay(Octaver, rate, name, tones_open)
-                    self.assertGreater(len(splits), 4)
-                    self.assertGreaterEqual(min(splits), 6.0,
-                                            (rate, name, tones_open,
-                                             splits))
-
-    def test_the_default_threshold_is_red(self):
-        splits = t4_decay(DefaultThreshold, 48000, "A2", False)
+                    for sens in (0, 64):
+                        splits = t4_decay(Octaver, rate, name, tones_open,
+                                          sens)
+                        self.assertGreater(len(splits), 4)
+                        self.assertGreaterEqual(
+                            min(splits), 6.0,
+                            (rate, name, tones_open, sens, splits))
+
+    def test_a_divider_on_tone_1_is_red(self):
+        splits = t4_decay(ToneClocked, 48000, "B3", True, 64)
         self.assertLess(min(splits), 6.0, splits)
 
 
@@ -928,41 +940,78 @@ def test_the_wire_is_the_input(self):
 
     def test_the_wire_keeps_every_frame(self):
         """Into the wire and back on a source whose buffers are not the
-        class's 256 frames: every source frame comes out once, on time.
-        Into it before the first pull, the voices' primed block is
-        skipped, and nothing else: the rest comes out once, in order, and
-        that block never plays late. The octave voices are held at 0
-        (`DryVoice`), so the output is the source throughout."""
+        class's 256 frames, from the first pull or mid-stream: every
+        source frame comes out once, on time. The octave voices are held at
+        0 (`DryVoice`), so the output is the source throughout."""
         import lifecycle
         rate = 48000
         for channels in (1, 2):
             values = self._material(rate, channels)
-            fsize = 2 * channels
             raw = bytes(values)
             for kind in ("100", "256", "300", "1000", "raw"):
-                feed = lifecycle.Feed(values, rate, channels, kind,
-                                      loop=False)
-                e = DryVoice(feed.port, sample_rate=rate)
-                out = kc.render(e, BLOCK * 20)
-                e.set_macro(OCT1, 0)
-                out += kc.render(e, BLOCK * 10)
-                e.set_macro(OCT1, 89)
-                out += kc.render(e, BLOCK * 30)
-                e.deinit()
-                self.assertEqual(out, raw[:len(out)], (channels, kind))
-                # Into the wire before anything was pulled: one block on.
-                feed = lifecycle.Feed(values, rate, channels, kind,
-                                      loop=False)
-                e = DryVoice(feed.port, sample_rate=rate)
-                e.set_macro(OCT1, 0)
-                out = kc.render(e, BLOCK * 10)
-                e.set_macro(OCT1, 89)
-                out += kc.render(e, BLOCK * 10)
-                e.deinit()
-                skip = BLOCK * fsize
-                self.assertEqual(out, raw[skip:skip + len(out)],
-                                 (channels, kind))
-                self.assertEqual(len(out), BLOCK * 20 * fsize)
+                for steps in (("p20", 0, "p10", 89, "p30"),
+                              (0, "p10", 89, "p10")):
+                    out = self._dry_run(lifecycle, values, rate, channels,
+                                        kind, steps)
+                    self.assertEqual(out, raw[:len(out)],
+                                     (channels, kind, steps))
+
+    #: Moves into the wire and back, resets, before the first pull and in
+    #: one gap between two pulls: "pN" pulls N blocks, a number sets
+    #: Octave 1 (0 is the wire).
+    SKIPS = (
+        (0, "p10"),
+        (0, "reset", 0, "p10"),
+        ("reset", "p10"),
+        ("p4", 0, "p4", 89, 0, 89, 0, "p6"),
+        (0, "p4", 89, 0, 89, 0, 89, 0, "p6"),
+        ("p4", 0, "p4", "reset", 0, "p6"),
+        (0, "p4", 89, 0, "p4", 89, 0, "p4", 89, "p4", 0, "p6"),
+        ("p4", "reset", "reset", "p6"),
+    )
+
+    def test_the_wire_never_skips(self):
+        """Every move in `SKIPS`, with `audiocore.get_buffer` and without
+        it (as on a CircuitPython board build): the output is the source,
+        every frame once and in order."""
+        import lifecycle
+        rate = 48000
+        for channels in (2, 1):
+            values = self._material(rate, channels)
+            raw = bytes(values)
+            for hide in (False, True):
+                for steps in self.SKIPS:
+                    out = self._dry_run(lifecycle, values, rate, channels,
+                                        "256", steps, hide)
+                    self.assertEqual(out, raw[:len(out)],
+                                     (channels, hide, steps))
+
+    def _dry_run(self, lifecycle, values, rate, channels, kind, steps,
+                 hide=False):
+        import types
+        from audioeffects import _component
+        module = sys.modules[Octaver.__module__]
+        real = module.audiocore
+        fake = types.ModuleType("audiocore")
+        for name in dir(real):
+            if name != "get_buffer" or not hide:
+                setattr(fake, name, getattr(real, name))
+        feed = lifecycle.Feed(values, rate, channels, kind, loop=False)
+        out = b""
+        module.audiocore = _component.audiocore = fake
+        try:
+            e = DryVoice(feed.port, sample_rate=rate)
+            for step in steps:
+                if step == "reset":
+                    e.reset()
+                elif isinstance(step, str):
+                    out += kc.render(e, BLOCK * int(step[1:]))
+                else:
+                    e.set_macro(OCT1, step)
+            e.deinit()
+        finally:
+            module.audiocore = _component.audiocore = real
+        return out
 
     def test_no_latency(self):
         for rate in (48000, 44100, 22050):
@@ -1081,7 +1130,7 @@ def test_the_peak_gain(self):
                 y = render(Octaver, values, rate, 1, patch=patch,
                            macros=knobs)
                 worst = max(worst, max(abs(v) for v in y) / float(amp))
-        self.assertTrue(4.1 <= worst <= 4.3, worst)
+        self.assertTrue(3.7 <= worst <= 3.8, worst)
         self.assertLessEqual(worst * 10.0 ** (
             Octaver.INPUT_CEILING_DBFS / 20.0), 1.0)
 
@@ -1154,7 +1203,7 @@ def test_the_peak_gain(self):
      "or stereo: after the clock's low-pass its fundamental is under "
      "Sensitivity.",
      "T5Range.test_a_weak_fundamental_can_drop_out_at_a4"),
-    ("The output can peak at about 4.2 times the input (a square, all "
+    ("The output can peak at about 3.8 times the input (a square, all "
      "three levels at full with the Tones open), so keep the input under "
      "-13 dBFS.",
      "TheSurface.test_the_peak_gain"),
@@ -1164,10 +1213,8 @@ def test_the_peak_gain(self):
     ("With both octaves at 0 and Direct at 1 the output is the input, byte "
      "for byte, however the host's buffers are cut.",
      ("TheSurface.test_the_wire_is_the_input",
-      "TheSurface.test_the_wire_keeps_every_frame")),
-    ("Reaching that setting before the first block after an octave comes "
-     "in skips that one block of 256 frames.",
-     "TheSurface.test_the_wire_keeps_every_frame"),
+      "TheSurface.test_the_wire_keeps_every_frame",
+      "TheSurface.test_the_wire_never_skips")),
     ("There is no latency.", "TheSurface.test_no_latency"),
     ("`tail_samples` covers the all-pass and the two Tone filters ringing "
      "down.",

From 71f1c399ead638009acc51663df72f00a2afd3d2 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:09:33 -0500
Subject: [PATCH 37/76] PitchShifter: the stranded mark clears at the first
 wiring, a cleared graph is re-armed as the constructor arms it, the unity
 claim says when the voice sits still

---
 lib/audioeffects/rebuilt/pitchshifter.py   |  29 +++-
 tests/support/lifecycle.py                 |   7 +-
 tests/test_cpython_effects_pitchshifter.py | 146 ++++++++++++++++++---
 3 files changed, 160 insertions(+), 22 deletions(-)

diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
index 0d4b00e..3ebe4ca 100644
--- a/lib/audioeffects/rebuilt/pitchshifter.py
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -123,7 +123,10 @@ class PitchShifter(_component.Component):
     when it runs out.
     Off unity, each note comes back anywhere from straight away to one
     window and 1.3 ms late, plus Delay, the delay sweeping and jumping at
-    every splice; at unity it sits still, 1.3 ms late.
+    every splice.
+    At unity it sits still, 1.3 ms late, from a fresh start, a reset or a
+    return from Mix 0; after a Pitch move it sits wherever the splice left
+    it, up to one window and 1.3 ms late.
     Shifting down drops slices of what you play; shifting up repeats them.
     The window is 30 ms unless you pass `window_ms`, 15 to 60, when you
     build it: a longer window splices less often and arrives later.
@@ -309,6 +312,19 @@ def _wire(self):
         self._in.play(self._head)
         self._clear_nodes(only=(self._shift, self._line, self._loop))
         self._wired = True
+        # A control touched at Mix 0 before the first wiring marked the
+        # graph stranded; wiring is what that mark waits for.
+        self._stranded = False
+
+    def _rearm(self):
+        """Wire the graph again as the constructor does, once it has been
+        cleared: a voice's new level is picked up at its next zero crossing
+        unless the voice is played again, so a graph that is cleared while
+        a level changes would otherwise carry the old level into the first
+        frames. The input goes back to silence first, so no frame is taken
+        from the borrowed source."""
+        self._in.play(self._hush)
+        self._wire()
 
     def _pull(self):
         """Pull one block from the mixer and drop it.
@@ -438,11 +454,20 @@ def _route(self):
             return
         if not self._wired:
             self._wire()
+        elif self._rejoin():
+            self._rearm()
         else:
             self._levels()
-            self._rejoin()
         self._output = self._tail
 
+    def reset(self):
+        """Empty the shifter and both lines, return to patch 0, and play
+        from there as a new instance does."""
+        wired = self._wired
+        _component.Component.reset(self)
+        if wired:
+            self._rearm()
+
     @property
     def tail_samples(self):
         """Frames until the output is exactly zero once the input stops,
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 8204abb..10da628 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -80,9 +80,10 @@
     # nothing but a fresh start puts two shifters at the same place.
     ("PitchShifter", "E1-", "P4"):
         "reset() starts the shifter and the loop's splicer where new ones"
-        " start (audiodsp#240), so the class then plays what a fresh"
-        " instance plays from that point, not what the uninterrupted"
-        " control plays (N2)",
+        " start (audiodsp#240: the restart is audiodsp's PitchShift;"
+        " CircuitPython's own keeps its positions), so the class then plays"
+        " what a fresh instance plays from that point, not what the"
+        " uninterrupted control plays (N2)",
     ("PitchShifter", "E4-m0=", "P4"):
         "a Pitch move runs the read position at another speed, so the splice"
         " phase lands elsewhere; putting it back would click (N2)",
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
index faf9cea..4cc9c34 100644
--- a/tests/test_cpython_effects_pitchshifter.py
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -851,21 +851,24 @@ def test_reset_empties_the_graph_and_returns_to_patch_0(self):
                 values = array("h", [rng.next() % 40001 - 20000
                                      for _ in range(frames * channels)])
                 at = 12 * BLOCK
-                feed = kc.feed(values, rate, channels)
-                e = PitchShifter(feed.port, patch=5)
-                try:
-                    kc.render(e, at)
-                    e.reset()
-                    self.assertEqual(e.patch_index, 0)
-                    self.assertEqual(
-                        tuple(e.get_macro(i) for i in range(5)),
-                        PitchShifter.PATCHES[0][1])
-                    after = kc.samples(kc.render(e, frames - at))
-                finally:
-                    e.deinit()
-                fresh = render(PitchShifter, values[at * channels:], rate,
-                               channels, frames - at)
-                self.assertEqual(after, fresh, (rate, channels))
+                # Patch 6 moves a Mixer level (the dry goes to nothing), so
+                # its voice must not wait for a zero crossing to come back.
+                for patch in (5, 6):
+                    feed = kc.feed(values, rate, channels)
+                    e = PitchShifter(feed.port, patch=patch)
+                    try:
+                        kc.render(e, at)
+                        e.reset()
+                        self.assertEqual(e.patch_index, 0)
+                        self.assertEqual(
+                            tuple(e.get_macro(i) for i in range(5)),
+                            PitchShifter.PATCHES[0][1])
+                        after = kc.samples(kc.render(e, frames - at))
+                    finally:
+                        e.deinit()
+                    fresh = render(PitchShifter, values[at * channels:],
+                                   rate, channels, frames - at)
+                    self.assertEqual(after, fresh, (rate, channels, patch))
 
     def test_the_tempo_is_never_read(self):
         reads = []
@@ -899,6 +902,107 @@ def test_without_get_buffer_plays_what_it_plays_with_it(self):
                 self.assertEqual(plain, hidden, (what, channels))
 
 
+def played(values, rate, channels, blocks, moves, **options):
+    """`blocks` pulls of an instance built with `options` and fed `values`,
+    `moves` mapping a pull index to a callable."""
+    e = PitchShifter(kc.feed(values, rate, channels).port, **options)
+    try:
+        return kc.samples(kc.render(e, blocks * BLOCK, moves))
+    finally:
+        e.deinit()
+
+
+class TheRestart(TestCase):
+    """What an instance plays after a control stranded its graph, or after
+    a reset, against what a fresh instance plays from that point on."""
+
+    def test_a_control_touched_at_mix_0_leaves_the_graph_playing(self):
+        # Built at Mix 0, a control touched there strands the graph; the
+        # first Mix move that wires it must not leave that mark behind, or
+        # the next ordinary Mix move empties the shifter mid-playback.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(23)
+            values = array("h", [rng.next() % 40001 - 20000
+                                 for _ in range(60 * BLOCK * channels)])
+
+            def touch(e):
+                position = e.get_macro(DELAY_I)
+                e.set_macro(DELAY_I, 30)
+                e.set_macro(DELAY_I, position)
+            moves = {2: lambda e: e.set_macro(MIX_I, 64),
+                     30: lambda e: e.set_macro(MIX_I, 80)}
+            plain = played(values, rate, channels, 60, moves, mix=0.0,
+                           feedback=0.5, delay_ms=20.0)
+            e = PitchShifter(kc.feed(values, rate, channels).port, mix=0.0,
+                             feedback=0.5, delay_ms=20.0)
+            try:
+                touch(e)
+                touched = kc.samples(kc.render(e, 60 * BLOCK, moves))
+            finally:
+                e.deinit()
+            self.assertEqual(touched, plain, (rate, channels))
+
+    def test_a_return_from_mix_0_is_a_fresh_instance_at_that_mix(self):
+        # The voices' new levels hold from the first frame: a dry that
+        # waited for its next zero crossing would play at unity on a DC
+        # input, where a fresh Mix 2 instance plays nothing yet.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(29)
+            noisy = array("h", [rng.next() % 40001 - 20000
+                                for _ in range(40 * BLOCK * channels)])
+            dc = array("h", [6000] * (40 * BLOCK * channels))
+            for name, values in (("noise", noisy), ("dc", dc)):
+                moves = {12: lambda e: e.set_macro(MIX_I, 0),
+                         18: lambda e: e.set_macro(MIX_I, 127)}
+                got = played(values, rate, channels, 40, moves)
+                fresh = render(PitchShifter, values[18 * BLOCK * channels:],
+                               rate, channels, 22 * BLOCK, mix=2.0)
+                self.assertEqual(got[18 * BLOCK * channels:], fresh,
+                                 (rate, channels, name))
+
+    def test_mix_0_and_a_patch_together_is_a_fresh_instance_at_that_patch(
+            self):
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(31)
+            values = array("h", [rng.next() % 40001 - 20000
+                                 for _ in range(40 * BLOCK * channels)])
+
+            def both(e):
+                e.set_macro(MIX_I, 0)
+                e.program_change(6)
+            got = played(values, rate, channels, 40, {12: both})
+            fresh = render(PitchShifter, values[12 * BLOCK * channels:],
+                           rate, channels, 28 * BLOCK, patch=6)
+            self.assertEqual(got[12 * BLOCK * channels:], fresh,
+                             (rate, channels))
+
+    def test_the_voice_at_unity_after_a_pitch_move_sits_where_the_splice_left_it(
+            self):
+        # From a fresh start (test_mix_2_is_the_shifted_voice_alone) or a
+        # reset the unity voice is O frames late. After Pitch has moved
+        # away and back it is wherever the splice left it, up to W + O.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            window = law_window(30.0, rate)
+            overlap = law_overlap(rate)
+            frames = 40 * BLOCK
+            at = 30 * BLOCK
+            seen = []
+            for away, back in ((5, 8), (3, 4), (5, 9), (2, 11)):
+                values = array("h", bytes(2 * frames * channels))
+                for c in range(channels):
+                    values[at * channels + c] = 20000
+                moves = {away: lambda e: e.set_macro(PITCH_I, 101),
+                         back: lambda e: e.set_macro(PITCH_I, 64)}
+                out = played(values, rate, channels, 40, moves, pitch=0.0,
+                             mix=2.0)
+                first = first_nonzero(out, channels, at, frames)
+                self.assertIsNotNone(first)
+                seen.append(first - at)
+            for late in seen:
+                self.assertTrue(0 <= late <= window + overlap, (rate, late))
+            self.assertTrue(any(late != overlap for late in seen), seen)
+
+
 class T1TheInterval(TestCase):
     def test_pitch_moves_by_the_semitones_it_reads(self):
         for rate, channels, window, pitch, fine in t1_cells():
@@ -991,9 +1095,17 @@ def test_dry_through_shifter_is_red(self):
       "test_flat_loop_is_red")),
     ("Off unity, each note comes back anywhere from straight away to one "
      "window and 1.3 ms late, plus Delay, the delay sweeping and jumping at "
-     "every splice; at unity it sits still, 1.3 ms late.",
+     "every splice.",
      ("test_arrivals_drift_between_at_once_and_one_window_late",
-      "test_window_at_48k_is_red", "test_mix_2_is_the_shifted_voice_alone")),
+      "test_window_at_48k_is_red")),
+    ("At unity it sits still, 1.3 ms late, from a fresh start, a reset or a "
+     "return from Mix 0; after a Pitch move it sits wherever the splice "
+     "left it, up to one window and 1.3 ms late.",
+     ("test_mix_2_is_the_shifted_voice_alone",
+      "test_reset_empties_the_graph_and_returns_to_patch_0",
+      "test_a_return_from_mix_0_is_a_fresh_instance_at_that_mix",
+      "test_the_voice_at_unity_after_a_pitch_move_sits_where_the_splice_"
+      "left_it")),
     ("The window is 30 ms unless you pass `window_ms`, 15 to 60, when you "
      "build it: a longer window splices less often and arrives later.",
      ("test_window_ms_is_set_at_construction",

From 7c3fd9287507a4b2a99c2612475ea63e950f8735 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:15:24 -0500
Subject: [PATCH 38/76] PitchShifter lifecycle: E10-reset and E10-mix0 P4
 declared as CircuitPython-only (its PitchShift keeps its positions through a
 clear)

---
 tests/support/lifecycle.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 10da628..3303823 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -104,6 +104,15 @@
     ("PitchShifter", "E11-", "P4"):
         "moves of the interval or of Mix through 0 before a pull move the"
         " splice phase (N2)",
+    ("PitchShifter", "E10-reset", "P4"):
+        "CircuitPython only: its own audiodelays.PitchShift keeps its read"
+        " and write positions across reset_buffer (audiodsp#240 is in"
+        " audiodsp's port only), so the re-arm's priming pulls move its"
+        " splice phase off the uninterrupted control's; CPython and"
+        " MicroPython are ok (ruled a CircuitPython-own difference)",
+    ("PitchShifter", "E10-mix0", "P4"):
+        "CircuitPython only: as E10-reset, the return from Mix 0 empties the"
+        " lines but CircuitPython's PitchShift keeps its positions",
     ("PitchShifter", "E4-m2=", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step (Mix)",

From cad9079521fc09b0f281fe94819103e83b9270aa Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:20:09 -0500
Subject: [PATCH 39/76] Harmonizer: the input ceiling covers every setting
 (-12.1 dBFS), with a test that renders the loudest two

---
 lib/audioeffects/rebuilt/harmonizer.py   |  9 +++++----
 tests/test_cpython_effects_harmonizer.py | 20 ++++++++++++++++++++
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/lib/audioeffects/rebuilt/harmonizer.py b/lib/audioeffects/rebuilt/harmonizer.py
index 3c19ccb..d308038 100644
--- a/lib/audioeffects/rebuilt/harmonizer.py
+++ b/lib/audioeffects/rebuilt/harmonizer.py
@@ -166,10 +166,11 @@ class Harmonizer(_component.Component):
     LATENCY_SAMPLES = 0
     TAIL_SAMPLES = None
 
-    #: The loudest sum over every patch and every stop is the dry at unity
-    #: and Level 3 at 0 dB over patch 0's other two voices: 3.0 times the
-    #: input, so -9.6 dBFS keeps it inside full scale.
-    INPUT_CEILING_DBFS = -9.6
+    #: The loudest sum over every setting is the dry at unity and all three
+    #: Levels at 0 dB at Mix 1: 4.0 times the input (patch 1 with Level 3
+    #: at 0 dB sums 3.44), so -12.1 dBFS keeps it inside full scale
+    #: (4.0 times is 12.04 dB, and -12.0 would leave the sum 0.5 % over).
+    INPUT_CEILING_DBFS = -12.1
 
     MACRO_LABELS = ("Pitch", "Voice 1", "Voice 2", "Voice 3", "Level 1",
                     "Level 2", "Level 3", "Detune", "Spread", "Mix")
diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
index 71ae744..2dfaaaa 100644
--- a/tests/test_cpython_effects_harmonizer.py
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -1265,6 +1265,26 @@ def test_patch_0_headroom(self):
                     y = render(Harmonizer, material, rate, channels)
                     self.assertLess(max(abs(s) for s in y), 32767)
 
+    def test_the_stated_ceiling_covers_every_setting(self):
+        """At `INPUT_CEILING_DBFS` the loudest settings reach no rail, not
+        only the kit's own: all three Levels at 0 dB at Mix 1 sum to 4.0
+        times the input, and patch 1 with Level 3 at 0 dB to 3.44."""
+        peak = int(32767 * 10.0 ** (Harmonizer.INPUT_CEILING_DBFS / 20.0)
+                   + 0.5)
+        cells = (
+            (None, [(LEVEL[k], 127) for k in range(3)] + [(MIX, 64)]),
+            (1, [(LEVEL[2], 127)]),
+        )
+        for rate in RATES:
+            for channels in CHANNELS:
+                values = kc.square(16384, channels, peak, rate // 100)
+                for patch, macros in cells:
+                    y = render(Harmonizer, values, rate, channels,
+                               patch=patch, macros=macros)
+                    on = sum(1 for s in y if s >= 32767 or s <= -32767)
+                    self.assertEqual(
+                        on, 0, (rate, channels, patch, peak, max(y)))
+
 
 CLAIMS = (
     ("Three pitch shifters, each a fixed interval from your note, blended "

From 9d3622bd7016636ef7b4e55623eaa1874c2d6db0 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:26:06 -0500
Subject: [PATCH 40/76] ShimmerHall: declare the hall's lifecycle P4 cells and
 the N1 step, and hold a refused call to the constructor's values

---
 tests/support/lifecycle.py                | 16 ++++++++++++++++
 tests/test_cpython_effects_shimmerhall.py | 21 +++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 047a230..8c68291 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -241,6 +241,22 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (two or three moves before one pull)',
     ("PingPongDelay", 'E4-m2=', 'P5'):
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (Mix)',
+    # ShimmerHall: its hall is the rebuilt Reverb, whose rows above say why
+    # a tank that was emptied, or fed differently for a moment, never meets
+    # an uninterrupted one byte for byte. A reset renders exactly as a fresh
+    # instance does (the class's reset test); it is the control that never
+    # was reset.
+    ("ShimmerHall", "E1-", "P4"): "reset() empties the hall and restarts its modulation, so it never re-converges with the uninterrupted control (Reverb's E1 P4)",
+    ("ShimmerHall", "E4-", "P4"): "a move that reaches the hall, its input or its tank (Character, Bloom, Interval, Size, Mix to 0 and back) leaves the tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E5-", "P4"): "Mix to 0 and back empties the hall and restarts its modulation (as E1)",
+    ("ShimmerHall", "E6-", "P4"): "a patch move reaches the hall's input or its tank and leaves it off the control's for good (Reverb's E6 P4)",
+    ("ShimmerHall", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the hall (as E1)",
+    ("ShimmerHall", "E11-", "P4"): "moves that reach the hall or empty it leave its tank off the control's for good (Reverb's E11 P4)",
+    ("ShimmerHall", "E4-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step",
+    ("ShimmerHall", "E5-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
+    ("ShimmerHall", "E6-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (a patch change)",
+    ("ShimmerHall", "E9-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
+    ("ShimmerHall", "E11-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (two or three moves before one pull)",
 }
 
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index fdd9da7..90a5c14 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -883,6 +883,24 @@ def test_the_input_ceiling(self):
             del ShimmerHall.INPUT_CEILING_DBFS
         self.assertIn("rail", verdict)
 
+    def test_a_refused_call_keeps_the_constructors_values(self):
+        # The kit's `opt` cells cannot build this class (its nudge moves
+        # `interval` off the five), so they run here with every other
+        # numeric option moved: a refused call changes nothing.
+        import kit_args
+        options = dict(shimmer=0.37, rise=0.71, bloom_ms=33.3, decay=7.7,
+                       size=0.61, damping_hz=777.0, mix=1.37)
+        real = kit_args._nudged
+        kit_args._nudged = lambda cls: [options]
+        try:
+            for label, _call, _noop in kit_args.refusals(ShimmerHall):
+                verdict = kit_args.refused_cell(ShimmerHall, label, "opt")
+                if isinstance(verdict, tuple):
+                    verdict = verdict[0]
+                self.assertTrue(verdict.startswith("ok"), (label, verdict))
+        finally:
+            kit_args._nudged = real
+
     def test_the_tempo_is_never_read(self):
         def transport():
             raise AssertionError("read the transport")
@@ -1064,6 +1082,9 @@ def test_late_dry_is_red(self):
      "carries on.",
      ("test_a_character_move_recuts_the_wet_chain",
       "test_a_size_move_empties_the_hall")),
+    ("A control that jumps makes the output step: move it in small steps "
+     "from the host if you need it smooth.",
+     "DECLARED:ShimmerHall,E6-,P5"),
     ("Interval is a fixed shift in semitones, with no key awareness.",
      "test_interval_has_five_zones"),
     ("A value outside a macro's span clamps to the nearer stop, and NaN "

From dcf8ffa6c46f4b4962027c1717fe15221297fa51 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:26:25 -0500
Subject: [PATCH 41/76] ShimmerHall tests: the ceiling test puts the stated
 ceiling back

---
 tests/test_cpython_effects_shimmerhall.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 90a5c14..89c0cec 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -874,13 +874,14 @@ def test_the_input_ceiling(self):
             verdict, _digest = kit_ceiling.measure(
                 ShimmerHall, 48000, 2, "square", None, None, options)
             self.assertEqual(verdict, "ok", options)
+        stated = ShimmerHall.INPUT_CEILING_DBFS
         try:
             ShimmerHall.INPUT_CEILING_DBFS = -12.0
             verdict, _digest = kit_ceiling.measure(
                 ShimmerHall, 48000, 2, "square", None, None,
                 dict(full, character="bloom"))
         finally:
-            del ShimmerHall.INPUT_CEILING_DBFS
+            ShimmerHall.INPUT_CEILING_DBFS = stated
         self.assertIn("rail", verdict)
 
     def test_a_refused_call_keeps_the_constructors_values(self):

From cd68fd105b1bf608586bdca15fd0ce46d61ab4d7 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:52:42 -0500
Subject: [PATCH 42/76] Kit round 3: scoped DECLARED rows, pre-pull moves
 against a fresh instance (E12, PF), reset renders as fresh (PR), ceiling
 combinations and low notes, nogb at every patch, the card's surface table

Each new check is red on a planted fault and green on its control.
---
 tests/support/KIT.md           |  41 +++-
 tests/support/LIFECYCLE.md     |  43 +++-
 tests/support/kit_ceiling.py   |  68 ++++--
 tests/support/kit_claims.py    |  48 +++-
 tests/support/kit_nogb.py      |   4 +-
 tests/support/kit_paperwork.py | 104 +++++++-
 tests/support/kit_planted.py   | 160 +++++++++++-
 tests/support/lifecycle.py     | 427 ++++++++++++++++++++++++++++++---
 tests/support/node_matrix.py   |  10 +-
 tests/test_kit.py              | 117 ++++++++-
 tests/test_lifecycle_matrix.py |  94 ++++++++
 11 files changed, 1046 insertions(+), 70 deletions(-)

diff --git a/tests/support/KIT.md b/tests/support/KIT.md
index 477e05b..b72b1ca 100644
--- a/tests/support/KIT.md
+++ b/tests/support/KIT.md
@@ -87,7 +87,9 @@ names a test, which exists and passes. The class's test module holds a
 
 A test is a method name (any TestCase that defines it), `Class.test_name`,
 a tuple of those, or `DECLARED:<NAME>,<event prefix>,<property>`, a row of
-the lifecycle matrix's DECLARED table. "Exists" is an AST lookup in the test
+the lifecycle matrix's DECLARED table. A scoped row is named with its
+scopes after the property: `patches=1/2/d` (`d` the defaults) and each
+interpreter by name, as in `DECLARED:PitchShifter,E10-reset,P4,circuitpython`. "Exists" is an AST lookup in the test
 module; "passes" runs that test alone under unittest (a skip is not a pass).
 The text is the class's module docstring and then its class docstring. A
 sentence is a claim if it holds a digit, a number word, or a bound or
@@ -139,9 +141,13 @@ hands it:
 at, on the worst material, the output does not wrap, sit on a rail, or go
 silent. The class states `INPUT_CEILING_DBFS` (dBFS, 0 or below); with
 none it is held to 0 dBFS. The material, 2 s at the peak: a 100 Hz square,
-a 50 Hz sine, one-sample clicks of alternating sign, noise, and a DC step,
-at the defaults, every patch and each macro alone at each stop, at 48 and
-22.05 kHz, stereo and mono (`--quick`: 48 kHz stereo). The bars:
+a 50 Hz sine, one-sample clicks of alternating sign, noise, a DC step, and
+squares on the low notes 41, 55, 82, 110 and 147 Hz (`sq41` ...). The
+settings: the defaults, every patch, each macro alone at 0, 64 and 127,
+every macro at 127 together (`all=127`), and every level-like macro (a
+label holding Level, Mix, Octave, Direct, Voice or Gain) at 127 with each
+other macro at each of its stops (`lv=127+m<i>=<v>`). At 48 and 22.05 kHz,
+stereo and mono (`--quick`: 48 kHz stereo). The bars:
 
 - `wrap`: neighbouring samples of opposite sign more than 32768 apart,
   where the second, moved by 65536, lands within a quarter of the jump of
@@ -163,6 +169,12 @@ this repository or a parent), never changed; with no checkout, or without
 the pinned commit in it, an audiodsp citation prints `na(...)`. Line
 numbers are all it can know: a citation whose lines moved still resolves.
 
+It also holds `MACRO_LABELS` and `MACRO_MODES` to the surface table in
+section 3 of the class's card (`<NAME>.md` in `KIT_CARDS`, or the cards
+directory found above this repository): one `surface-m<i>` cell per macro,
+a mismatch naming both sides. A class with no card, or a card with no
+table whose header has `#`, `Label` and `Mode`, prints `na(...)`.
+
 **nogb** (`kit_nogb.py`). A class whose primed voice is flushed by
 `audiocore.get_buffer` misbehaves on the board builds that compile it out
 of CircuitPython: the block the voice still holds plays later, source
@@ -180,12 +192,20 @@ run that has it.
 - `bytes-<scenario>/48000/<channels>/<d|pK>`: the whole render, every
   channel, byte for byte: a reset, two resets in a row, a reset before the
   first pull, a patch change and a reset in one block, and resets a block
-  apart. A class whose first block is rightly gated differently without
+  apart, at the defaults and every patch. A class whose first block is rightly gated differently without
   `get_buffer` declares the cell in `DECLARED`.
 
 CPython only. A module that imports `get_buffer` inside a function is not
 reached.
 
+## Known gaps
+
+- **Several levels.** Every render check plays its material at one level
+  (the ceiling at the stated peak, the others where they are set). A class
+  whose behaviour turns on input level, such as a comparator or a dead
+  band, can be wrong a few dB below the level any cell plays. No check
+  sweeps the input level yet.
+
 ## Options
 
 `kit_options.py` holds `KIT_OPTIONS`, the constructor options the kit
@@ -217,11 +237,16 @@ and a loose claim (claims), `ReadbackOff`, `StopRaises`, `NanLevel`,
 `PatchStale` and `CtorNan` (args; `ClearsFirst` and `ClearsMacro` for the
 refused calls: one zeroes the cached level, the other drops the patch or
 moves a macro, before validating), `WrapKit`, `ClipKit` and `DeadStop`
-(ceiling), a missing CHANGELOG line and citations past the end of a file or
-to no file (paperwork), `FlushOnly` and `DoubleReset` (nogb: the first leans
+(ceiling; `MidWrap`, `ComboWrap`, `AllWrap` and `LowWrap` wrap only at
+Level 64, at the level-like macros at 127 with Tone at 0, with every macro
+at 127, and on a square below 60 Hz, against `CondKit` and `KitPlain`), a
+missing CHANGELOG line, citations past the end of a file or to no file, and
+a fixture card whose surface table differs (paperwork), `FlushOnly` and `DoubleReset` (nogb: the first leans
 on `get_buffer` to flush a primed voice, the second drops a block on a
 second reset in a row without it; `FlushKit`, which primes a voice of its own
-and plays it again where it cannot flush, is the control), and `Silent`, which does nothing. Its native half
+and plays it again where it cannot flush, is the control; `MidPatchReset`
+does it at a middle patch only, against `FlushKit3`), and `Silent`, which
+does nothing. Its native half
 holds the render checks to the same lines on all three interpreters, and
 shows that agreement can fail with `ImplKit`, whose level differs off
 CPython.
\ No newline at end of file
diff --git a/tests/support/LIFECYCLE.md b/tests/support/LIFECYCLE.md
index 0d01f41..fe20bd5 100644
--- a/tests/support/LIFECYCLE.md
+++ b/tests/support/LIFECYCLE.md
@@ -16,7 +16,8 @@ To run it on one class (CPython, or a native binary with
 
 It prints one line per cell, `class|event|rate|channels|patch|P1:..|...|h:..`,
 and a `SUMMARY` line per class: cells run, cells with any red property,
-declared exceptions. `tests/test_lifecycle_matrix.py` runs it on every Phase 5
+and cells with any declared property (a cell with two declared properties
+counts once). `tests/test_lifecycle_matrix.py` runs it on every Phase 5
 class on the branch, on CPython and both native interpreters, and holds the
 red cells to its `KNOWN_RED` table.
 
@@ -58,6 +59,11 @@ later (6 for Mix).
   change and back, all before the first pull.
 - **E11** two macro moves; a Mix move and a patch change; two patch changes;
   three moves; all before one pull, back later.
+- **E12** a move before the first pull that stays: each patch, and Mix to
+  0, 64 and 127. At the defaults only. Its control is not the
+  uninterrupted instance but a fresh one built at the move's setting
+  (`patch=`, or the Mix keyword, `mix` unless `MIX_KEYWORD` names another);
+  a constructor that takes no such keyword prints `na(no fresh build)`.
 
 "Back" is `program_change(patch)` at a patch, and `set_macro` with the
 values `get_macro` read at the defaults (landed exactly where that
@@ -86,6 +92,16 @@ at patch 0.
   of the triangle's own largest step and the control's. Control moves only
   (E4, E5, E6, E9, E11): a reset, a deinit and a source fault are cuts by
   definition, and E10 has nothing before it.
+- **PF** (E12) The first block equals the fresh instance's, byte for
+  byte: a level that waits for a zero crossing or a block before it moves
+  plays its first block at the old setting, which P4's bound forgives.
+- **PR** (E1-reset@block, E10-reset, E5-mix0, E10-mix0) From the move that
+  lands the class on a state it can be built at (a reset: patch 0; a
+  return from Mix 0: the cell's own configuration) on, 4096 frames are
+  byte-identical to a fresh instance built there and fed the source from
+  the same frame. Where the source stands is read off a dry run to the
+  move. No tail is forgiven: a child left at its own patch 0, a line kept
+  across a reset or a block primed twice is red here.
 - **P6** The three interpreters print identical lines for every cell. Each
   line carries `h:`, a CRC-32 of the event instance's whole render, so P6
   compares bytes, not only verdicts.
@@ -105,7 +121,26 @@ free-running LFO) adds a row to `DECLARED` in `lifecycle.py`:
     }
 
 The key is (class `NAME`, event name prefix, property); the cell then prints
-`decl` and counts as a declared exception.
+`decl` and counts as a declared exception. The prefix names at least one
+whole event and its dash (`E4-`, `E10-reset`); a bare `E` or `E1` is
+refused at import, because it also matches cells its reason does not
+describe.
+
+A row can be narrowed by scopes after the property, each kind at most
+once: a tuple of patches (None for the defaults), and a string naming the
+interpreters (`sys.implementation.name`, comma-separated):
+
+    ("PitchShifter", "E10-reset", "P4", "circuitpython"): "...",
+    ("Octaver", "E5-", "P1", (1, 2, 5)): "...",
+
+A row whose reason holds on one interpreter only names it, so the cell
+stays a live check on the other two. A row written with a patch tuple as
+its fourth element keeps working as it is; one with a bare `E` prefix is
+split into one row per event its reason covers.
+
+PR is excused only by `FREE_PHASE`, class `NAME` -> the free-running
+phase (an LFO, a wow table) that keeps a reset or a rejoin from matching a
+fresh instance, named.
 
 A cell that cannot finish on one interpreter, such as a node there that
 never returns from a pull, is skipped there instead: a row in `SKIP`, keyed
@@ -125,5 +160,7 @@ and `LIFECYCLE_CLASSES=DigitalDelay,TapeDelay` limits it to some classes.
 The helper ships a control and a planted fault for every property, and
 `TestPlants` holds each plant red on its cell with its control green there:
 `DropOnReset` (P1), `HoldDC` (P2), `StaleMix` against `Routed` (P3),
-`LateMove` (P4), `HardSwitch` (P5), `BusyDeinit` (PD) and `ImplPlant`
+`LateMove` (P4), `HardSwitch` (P5), `BusyDeinit` (PD), `LatePatch` (PF, a
+pre-pull patch that lands a block late), `ResetLeak` against `Routed` (PR,
+a reset that keeps its echo line; P4 reads both as ok) and `ImplPlant`
 (P6, a level a hair different off CPython).
diff --git a/tests/support/kit_ceiling.py b/tests/support/kit_ceiling.py
index d917d67..808f15a 100644
--- a/tests/support/kit_ceiling.py
+++ b/tests/support/kit_ceiling.py
@@ -7,11 +7,18 @@
 full scale. The material's peak is round(32767 x 10^(dBFS/20)).
 
 **The material**, 2 s at the rate: a 100 Hz square, a 50 Hz sine, one
--sample clicks of alternating sign every 97 frames, LCG noise, and a DC
-step (silence for the first eighth, then the peak held). Each at the
-defaults, at every patch, and with each macro alone at each stop (0 and
-127, and 64 for a bipolar macro); at 48 and 22.05 kHz, stereo and mono
-(`--quick`: 48 kHz stereo).
+-sample clicks of alternating sign every 97 frames, LCG noise, a DC step
+(silence for the first eighth, then the peak held), and squares on the low
+notes 41, 55, 82, 110 and 147 Hz (`sq41` ...), where a filter or a level
+that rings on a long half-cycle shows.
+
+**The settings**: the defaults, every patch, each macro alone at 0, 64 and
+127, and two kinds of combination. `all=127` is every macro at 127
+together. A macro whose label holds Level, Mix, Octave, Direct, Voice or
+Gain is level-like; `lv=127+m<i>=<v>` holds every level-like macro at 127
+and one other macro at each of its stops (0 and 127), the others where the
+defaults put them. A docstring's own worst setting is usually one of these.
+At 48 and 22.05 kHz, stereo and mono (`--quick`: 48 kHz stereo).
 
 **The bars**, each its own clause in a RED verdict:
 
@@ -42,7 +49,12 @@
 
 CHECK = "ceiling"
 SECONDS = 2
-MATERIALS = ("square", "sine", "clicks", "noise", "dc")
+#: The low notes a square is played on besides 100 Hz: E1, A1, E2, A2, D3.
+LOW_NOTES = (41, 55, 82, 110, 147)
+MATERIALS = ("square", "sine", "clicks", "noise", "dc") + tuple(
+    "sq%d" % hz for hz in LOW_NOTES)
+#: A macro label holding one of these is level-like.
+LEVEL_WORDS = ("Level", "Mix", "Octave", "Direct", "Voice", "Gain")
 WRAP_JUMP = 32768
 
 _MAT = {}
@@ -69,6 +81,8 @@ def material(which, rate, channels, amp):
             values = kc.noise(frames, channels, amp)
         elif which == "dc":
             values = kc.dc(frames, channels, amp, start=frames // 8)
+        elif which.startswith("sq"):
+            values = kc.square(frames, channels, amp, rate // int(which[2:]))
         else:
             raise ValueError(which)
         _MAT.clear()
@@ -132,24 +146,50 @@ def judge(data, values, channels, rate, lat, which):
     return reds
 
 
+def level_like(cls):
+    """The indexes of the macros whose label makes them level-like."""
+    out = []
+    for i in range(len(cls.MACRO_LABELS)):
+        label = cls.MACRO_LABELS[i]
+        for word in LEVEL_WORDS:
+            if word in label:
+                out.append(i)
+                break
+    return out
+
+
 def configs(cls):
-    """(key, patch, knob) for the defaults, every patch and every stop."""
+    """(key, patch, knobs) for the defaults, every patch, each macro at 0,
+    64 and 127, every macro at 127, and the level-like macros at 127 with
+    each other macro at each stop."""
     out = [("d", None, None)]
     for patch in sorted(cls.PATCHES):
         out.append(("p%d" % patch, patch, None))
-    for knob in kc.knob_positions(cls):
-        out.append(("m%d=%d" % knob, None, knob))
+    n = len(cls.MACRO_LABELS)
+    for i in range(n):
+        for v in (0, 64, 127):
+            out.append(("m%d=%d" % (i, v), None, [(i, v)]))
+    if n > 1:
+        out.append(("all=127", None, [(i, 127) for i in range(n)]))
+    levels = level_like(cls)
+    if levels:
+        for i in range(n):
+            if i in levels:
+                continue
+            for v in (0, 127):
+                knobs = [(j, 127) for j in levels] + [(i, v)]
+                out.append(("lv=127+m%d=%d" % (i, v), None, knobs))
     return out
 
 
-def measure(cls, rate, channels, which, patch, knob, options=None):
+def measure(cls, rate, channels, which, patch, knobs, options=None):
     amp = peak(cls)
     values = material(which, rate, channels, amp)
     feed = kc.feed(values, rate, channels)
     e = kc.build(cls, feed.port, rate, patch, options)
     try:
-        if knob is not None:
-            e.set_macro(knob[0], knob[1])
+        for index, value in knobs or ():
+            e.set_macro(index, value)
         data = kc.render(e, SECONDS * rate)
         reds = judge(data, values, channels, rate, e.latency_samples, which)
     finally:
@@ -170,13 +210,13 @@ def run(cls, emit=print, quick=False, rates=None, channels=None,
     for rate in rates:
         for ch in channels:
             for which in materials:
-                for key, patch, knob in configs(cls):
+                for key, patch, knobs in configs(cls):
                     if only is not None and key not in only:
                         continue
                     ckey = "%s/%d/%d/%s" % (which, rate, ch, key)
                     try:
                         verdict, digest = measure(cls, rate, ch, which,
-                                                  patch, knob, options)
+                                                  patch, knobs, options)
                     except Exception as exc:              # noqa: BLE001
                         verdict, digest = "RED(raised %s: %s)" % (
                             type(exc).__name__, exc), None
diff --git a/tests/support/kit_claims.py b/tests/support/kit_claims.py
index 64de191..44be6ee 100644
--- a/tests/support/kit_claims.py
+++ b/tests/support/kit_claims.py
@@ -7,8 +7,10 @@
 word (whitespace aside), and the test that asserts it. `test` is a test
 method's name (`"test_x"`, any TestCase in the module that defines it), a
 `"Class.test_x"`, a tuple of those, or `"DECLARED:<NAME>,<event
-prefix>,<property>"`, naming a row of the lifecycle matrix's DECLARED
-table (a disclosure the matrix holds).
+prefix>,<property>[,<scope>...]"`, naming a row of the lifecycle matrix's
+DECLARED table (a disclosure the matrix holds). A scoped row is named with
+its scopes: `patches=1/2/d` for a patch tuple (`d` the defaults), and each
+interpreter by name (`DECLARED:PitchShifter,E10-reset,P4,circuitpython`).
 
 **The text.** What a player reads: the class's module docstring, then the
 class docstring (a rebuilt module holds one class, and either may carry
@@ -123,10 +125,48 @@ def resolve(target, index):
     return ["%s.%s" % (owner, target) for owner in owners]
 
 
+def _canonical(name, prefix, prop, patches, impls):
+    if patches is not None:
+        patches = tuple(sorted(patches, key=lambda p: -1 if p is None
+                               else p))
+    if impls is not None:
+        impls = tuple(sorted(impls))
+    return (name, prefix, prop, patches, impls)
+
+
+def parse_declared(target):
+    """The canonical row a `DECLARED:` target names, or None. After NAME,
+    prefix and property, a `patches=1/2/d` part scopes it to patches (`d`
+    the defaults), and any other part names an interpreter."""
+    parts = target.split(":", 1)[1].split(",")
+    if len(parts) < 3:
+        return None
+    patches = impls = None
+    for part in parts[3:]:
+        if part.startswith("patches="):
+            patches = []
+            for p in part[8:].split("/"):
+                if p == "d":
+                    patches.append(None)
+                elif p.isdigit():
+                    patches.append(int(p))
+                else:
+                    return None
+        else:
+            impls = (impls or []) + [part]
+    return _canonical(parts[0], parts[1], parts[2], patches, impls)
+
+
 def declared_exists(target):
     import lifecycle
-    parts = target.split(":", 1)[1].split(",")
-    return len(parts) == 3 and tuple(parts) in lifecycle.DECLARED
+    want = parse_declared(target)
+    if want is None:
+        return False
+    for key in lifecycle.DECLARED:
+        patches, impls = lifecycle.declared_scope(key)
+        if _canonical(key[0], key[1], key[2], patches, impls) == want:
+            return True
+    return False
 
 
 def run_tests(module, ids):
diff --git a/tests/support/kit_nogb.py b/tests/support/kit_nogb.py
index f562c04..4de8783 100644
--- a/tests/support/kit_nogb.py
+++ b/tests/support/kit_nogb.py
@@ -18,7 +18,7 @@
 `bytes-<scenario>` cells hold the whole render, every channel, to equal
 the one with `get_buffer` present: a reset, two resets in a row, a reset
 before the first pull, a patch change and a reset in one block, at the
-defaults and at the last patch, stereo and mono.
+defaults and at every patch, stereo and mono.
 
 CPython only: it patches the `audiocore` name those modules read, with a
 stand-in that has everything but `get_buffer`, and puts it back afterwards.
@@ -187,7 +187,7 @@ def run(cls, emit=print, quick=False, name=None, options=None):
     except Exception as exc:                              # noqa: BLE001
         cells.cell("run", "RED(raised %s: %s)" % (type(exc).__name__, exc))
         return cells.summary()
-    for patch in (None, max(cls.PATCHES) or None):
+    for patch in [None] + sorted(cls.PATCHES):
         for ch in (2, 1):
             for label, actions in SCENARIOS:
                 key = "bytes-%s/48000/%d/%s" % (
diff --git a/tests/support/kit_paperwork.py b/tests/support/kit_paperwork.py
index eef7f69..2170edd 100644
--- a/tests/support/kit_paperwork.py
+++ b/tests/support/kit_paperwork.py
@@ -15,6 +15,16 @@
 file are all this can know: a citation whose lines moved under it still
 resolves.
 
+**The surface.** The class's `MACRO_LABELS` and `MACRO_MODES` against the
+surface table of its class card: `<NAME>.md` in the cards directory
+(`KIT_CARDS`, or a `docs/effects-internal/dossiers` directory in a parent
+of this repository), read as text. The table is the first in section 3
+whose header has `#`, `Label` and `Mode` columns; a label is compared
+without its backticks and a mode by its first word (`UNIPOLAR, log` is
+UNIPOLAR; a macro `MACRO_MODES` leaves out is UNIPOLAR). One
+`surface-m<i>` cell per macro either side has; a mismatch names both. With
+no card, or no such table on it, the `surface` cell prints `na(...)`.
+
 The pinned audiodsp is read from a checkout, never changed: `KIT_AUDIODSP`
 or an `audiodsp` directory beside this repository (or beside a parent of
 it). Without one, or without the pinned commit in it, each audiodsp
@@ -171,6 +181,87 @@ def cite_verdict(path, first, last, pin, root=ROOT):
     return "RED(no %s at the pin or in this repository)" % path
 
 
+def find_cards(root=ROOT):
+    env = os.environ.get("KIT_CARDS")
+    if env:
+        return env if os.path.isdir(env) else None
+    here = root
+    for _up in range(6):
+        here = os.path.dirname(here)
+        candidate = os.path.join(here, "docs", "effects-internal",
+                                 "dossiers")
+        if os.path.isdir(candidate):
+            return candidate
+    return None
+
+
+def _row(line):
+    line = line.strip().replace("\\|", "/")
+    return [c.strip() for c in line.strip("|").split("|")]
+
+
+def card_surface(text):
+    """[(index, label, mode)] from the card's surface table, or None."""
+    inside = False
+    header = None
+    rows = []
+    for line in text.splitlines():
+        if line.startswith("## "):
+            if inside:
+                break
+            inside = line[3:].lstrip().startswith("3")
+            continue
+        if not inside:
+            continue
+        if not line.lstrip().startswith("|"):
+            if header is not None and rows:
+                break
+            continue
+        cells = _row(line)
+        if header is None:
+            if "#" in cells and "Label" in cells and "Mode" in cells:
+                header = cells
+            continue
+        if not "".join(cells).strip("-: "):
+            continue
+        try:
+            index = int(cells[header.index("#")])
+        except (ValueError, IndexError):
+            continue
+        label = cells[header.index("Label")].strip("`").strip()
+        words = cells[header.index("Mode")].replace(",", " ").split()
+        rows.append((index, label, words[0].upper() if words else ""))
+    return rows if header is not None else None
+
+
+def surface_cells(cells, cls, cards):
+    """The surface cells for `cls` against its card in `cards`."""
+    if cards is None:
+        cells.cell("surface", "na(no class cards)")
+        return
+    path = os.path.join(cards, "%s.md" % cls.NAME)
+    if not os.path.isfile(path):
+        cells.cell("surface", "na(no card for %s)" % cls.NAME)
+        return
+    with open(path, encoding="utf-8") as f:
+        rows = card_surface(f.read())
+    if rows is None:
+        cells.cell("surface", "na(no surface table in section 3)")
+        return
+    card = dict((index, (label, mode)) for index, label, mode in rows)
+    labels = cls.MACRO_LABELS
+    ours = dict((i, (labels[i], cls.MACRO_MODES.get(i, "UNIPOLAR")))
+                for i in range(len(labels)))
+    for i in sorted(set(card) | set(ours)):
+        a = ours.get(i)
+        b = card.get(i)
+        if a == b:
+            cells.cell("surface-m%d" % i, "ok")
+            continue
+        cells.cell("surface-m%d" % i, "RED(class %s, card %s)" % (
+            "%r %s" % a if a else "none", "%r %s" % b if b else "none"))
+
+
 def has_changelog_line(name, changelog_text):
     head = "- **`%s`" % name
     for line in changelog_text.splitlines():
@@ -179,10 +270,14 @@ def has_changelog_line(name, changelog_text):
     return False
 
 
-def check(name, text, changelog_text, pin, emit=print, root=ROOT):
-    """The paperwork cells for class `name` whose module source is `text`.
-    Returns the red count."""
+def check(name, text, changelog_text, pin, emit=print, root=ROOT, cls=None,
+          cards=None):
+    """The paperwork cells for class `name` whose module source is `text`
+    (and, given `cls`, its surface against its card in `cards`). Returns
+    the red count."""
     cells = kc.Cells(name, CHECK, emit)
+    if cls is not None:
+        surface_cells(cells, cls, cards)
     cells.cell("changelog", "ok" if has_changelog_line(name, changelog_text)
                else "RED(no CHANGELOG line starts - **`%s`)" % name)
     seen = {}
@@ -204,7 +299,8 @@ def run(cls, emit=print, name=None, **_):
     with open(os.path.join(ROOT, "CHANGELOG.md"), encoding="utf-8") as f:
         changelog = f.read()
     pin = Pin(find_checkout(), pin_commit())
-    return check(name or cls.NAME, text, changelog, pin, emit)
+    return check(name or cls.NAME, text, changelog, pin, emit, cls=cls,
+                 cards=find_cards())
 
 
 if __name__ == "__main__":
diff --git a/tests/support/kit_planted.py b/tests/support/kit_planted.py
index 0fa4c8e..a3bb03a 100644
--- a/tests/support/kit_planted.py
+++ b/tests/support/kit_planted.py
@@ -135,6 +135,140 @@ def _level(self):
         return KitPlain._level(self)
 
 
+class CondKit(KitPlain):
+    """The control for the ceiling's mid-stop, combined and low-note
+    cells: three macros (Mix, Level, Tone), no setting of which wraps. Its
+    plants swap in a wrapping table, at unity, at one setting only."""
+    NAME = "CondKit"
+    MACRO_LABELS = ("Mix", "Level", "Tone")
+    MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR"}
+    _MACRO_RANGES = ((0.0, 1.0), (0.25, 1.0), (0.0, 1.0))
+    PATCHES = {0: ("Default", (127, 64, 64)), 1: ("Soft", (127, 32, 64))}
+    _TABLES = {}
+
+    def _build(self, mix=1.0, level=0.25 + 0.75 * 64 / 127, tone=64 / 127,
+               patch=None):
+        import audioshaper
+        self._shaper = self._own(audioshaper.Waveshaper(
+            curve=self._table(_same), oversample=1,
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count))
+        self._arm()
+        self._macros = [0.0, 0.0, 0.0]
+        self._init_macros((mix, level, tone), patch)
+
+    def _table(self, fn):
+        if fn not in CondKit._TABLES:
+            CondKit._TABLES[fn] = _curve(fn)
+        return CondKit._TABLES[fn]
+
+    def _at(self, index, midi):
+        return abs(self._macros[index] - midi / 127.0) < 1e-6
+
+    def _bad(self):
+        return False
+
+    def _apply_macro(self, index, position):
+        if self._bad():
+            self._shaper.set(curve=self._table(_wrap2), post_gain=1.0)
+        else:
+            mix = self.macro(0)
+            self._shaper.set(curve=self._table(_same),
+                             post_gain=1.0 - mix + mix * self.macro(1))
+
+
+class MidWrap(CondKit):
+    """Ceiling: wraps with Level at 64 alone, a position between the
+    stops."""
+    NAME = "MidWrap"
+    PATCHES = {0: ("Default", (127, 96, 64)), 1: ("Soft", (127, 32, 64))}
+
+    def __init__(self, source, *a, **kw):
+        kw.setdefault("level", 0.25 + 0.75 * 96 / 127)
+        CondKit.__init__(self, source, *a, **kw)
+
+    def _bad(self):
+        return self._at(1, 64)
+
+
+class ComboWrap(CondKit):
+    """Ceiling: wraps only with Mix and Level at 127 and Tone at 0
+    together, the combination a docstring calls the worst."""
+    NAME = "ComboWrap"
+
+    def _bad(self):
+        return self._at(0, 127) and self._at(1, 127) and self._at(2, 0)
+
+
+class AllWrap(CondKit):
+    """Ceiling: wraps only with every macro at 127 together."""
+    NAME = "AllWrap"
+
+    def _bad(self):
+        return self._at(0, 127) and self._at(1, 127) and self._at(2, 127)
+
+
+class _LowNote:
+    """A Python-level node (CPython only): half the input, until the input
+    has sat past 0.885 of full scale for 250 frames on one side after
+    crossing from the other; from there it ramps up by 128 a frame and
+    wraps round int16, as a sum that overflowed on a long half-cycle
+    would."""
+
+    def __init__(self, inner):
+        self.inner = inner
+        self.sample_rate = inner.sample_rate
+        self.channel_count = inner.channel_count
+        self.bits_per_sample = 16
+        self.samples_signed = True
+        self._clear()
+
+    def _clear(self):
+        ch = self.channel_count
+        self.run = [0] * ch
+        self.side = [0] * ch
+        self.flipped = [False] * ch
+
+    def _reset_buffer(self, single_channel_output=False, audio_channel=0):
+        self._clear()
+        audiocore.reset_buffer(self.inner)
+
+    def _get_buffer(self, single_channel_output=False, audio_channel=0):
+        more, data = audiocore.get_buffer(self.inner)
+        x = array("h", bytes(data))
+        ch = self.channel_count
+        for i in range(len(x)):
+            c = i % ch
+            v = x[i]
+            side = 1 if v >= 29000 else (-1 if v <= -29000 else 0)
+            if side and side == self.side[c]:
+                self.run[c] += 1
+            elif side:
+                if self.side[c]:
+                    self.flipped[c] = True
+                self.side[c] = side
+                self.run[c] = 1
+            else:
+                self.run[c] = 0
+            y = v // 2
+            if self.flipped[c] and self.run[c] > 250:
+                y += side * 128 * (self.run[c] - 250)
+                y = (y + 32768) % 65536 - 32768
+            x[i] = y
+        return more, memoryview(bytes(x))
+
+
+class LowWrap(KitPlain):
+    """Ceiling: wraps on a square below about 60 Hz at 48 kHz, and on no
+    material the 100 Hz square, the 50 Hz sine, the clicks or the DC step
+    reach (CPython only: its output is a Python-level node)."""
+    NAME = "LowWrap"
+
+    def _arm(self):
+        self._shaper.play(self._source)
+        self._output = _LowNote(self._shaper)
+
+
 class ImplKit(KitPlain):
     """P6: the level is a hair different off CPython, so every render
     check prints other bytes natively."""
@@ -392,9 +526,31 @@ def set_macro(self, *args, **kw):
         FlushKit.set_macro(self, *args, **kw)
 
 
+class FlushKit3(FlushKit):
+    """The control for nogb's every-patch cells: FlushKit with a patch
+    between the first and the last."""
+    NAME = "FlushKit3"
+    PATCHES = {0: ("Unity", (127, 127)), 1: ("Mid", (127, 112)),
+               2: ("Soft", (127, 96))}
+
+
+class MidPatchReset(FlushKit3):
+    """Nogb: at the middle patch only, with no `get_buffer`, a reset plays
+    the voices again, which drops the block they held: a fault neither the
+    defaults nor the last patch reach."""
+    NAME = "MidPatchReset"
+
+    def reset(self):
+        mid = self._patch_index == 1
+        FlushKit3.reset(self)
+        if mid and getattr(audiocore, "get_buffer", None) is None:
+            lifecycle.Routed._arm(self)
+
+
 PLANTS = {}
 for _cls in (KitPlain, Silent, WrapKit, WrapKitQuiet, ClipKit, DeadStop,
-             ImplKit, EchoTail, ShortTail, EventTail, NoneSilent, NoneDC,
+             CondKit, MidWrap, ComboWrap, AllWrap, LowWrap, ImplKit, EchoTail, ShortTail, EventTail, NoneSilent, NoneDC,
              ReadbackOff, StopRaises, NanLevel, PatchStale, CtorNan,
-             ClearsFirst, ClearsMacro, FlushKit, FlushOnly, DoubleReset):
+             ClearsFirst, ClearsMacro, FlushKit, FlushOnly, DoubleReset,
+             FlushKit3, MidPatchReset):
     PLANTS[_cls.NAME] = _cls
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 129c4d1..b7c9999 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -70,14 +70,29 @@
     "SlapbackDelay": 1,        # "Level": the slap's level; 0 is the dry
 }
 
+#: The interpreters a DECLARED or SKIP row can name.
+IMPLS = ("cpython", "micropython", "circuitpython")
+#: The events that move a control (P5 judges only these).
+CONTROL_EVENTS = ("E4-", "E5-", "E6-", "E9-", "E11-")
+
 #: Where a class cannot satisfy a property by design, it says so HERE, one
-#: row per (class NAME, event name prefix, property): reason. A matching
-#: cell prints `decl` instead of RED and is counted as a declared exception.
-#: Nothing else skips a cell.
+#: row per (class NAME, event name prefix, property[, scope...]): reason. A
+#: matching cell prints `decl` instead of RED and is counted as a declared
+#: exception. Nothing else skips a cell.
+#:
+#: The event prefix names at least one whole event number and its dash
+#: ("E1-", "E10-reset", "E4-m2="): a bare "E" or "E1" is refused at import,
+#: since it would also match events its reason does not describe.
+#:
+#: A scope narrows a row; give each kind at most once, in either order:
+#:
+#: - a tuple of patches, the configurations the row covers (None for the
+#:   constructor defaults): ("Octaver", "E5-", "P1", (1, 2, 5));
+#: - a string naming the interpreters it holds on, `sys.implementation.name`,
+#:   comma-separated: ("PitchShifter", "E10-reset", "P4", "circuitpython").
+#:
+#: A row without a scope matches every patch on every interpreter.
 DECLARED = {
-    ("AnalogDelay", "E", "P5"):
-        "a control that jumps steps the output (family, audiocomponents#117);"
-        " a Time move bends the pitch while the line walks, by design",
     ("AnalogDelay", "E2-", "P4"):
         "reset_buffer restarts the modulation triangle (the node's"
         " state_init), so a modulated patch then matches a fresh instance,"
@@ -154,9 +169,6 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (a patch change)',
     ("DigitalDelay", 'E11-3moves', 'P5'):
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (the patch change; the Time moves glide)',
-    ("SlapbackDelay", "E", "P5"):
-        "a control that jumps steps the output (family, audiocomponents#117):"
-        " Level, Tone and patch moves have no ramp",
     ("SlapbackDelay", "E1-", "P4"):
         "a reset restarts the Wow wobble where a fresh instance's starts;"
         " the control never stopped, so its wobble is further along and"
@@ -165,10 +177,6 @@
         "reset_buffer restarts the Wow wobble where a fresh instance's"
         " starts; the control never stopped, so its wobble is further along"
         " and with Wow above 0 the two never line up again (ok at Wow 0)",
-    ("MultiTapDelay", "E", "P5"):
-        "family limit, disclosed (audiocomponents#117): a control that jumps"
-        " makes the output step (Time and Heads move every head to a new"
-        " grid, Mix, Tilt and a patch change jump a level)",
     ("MultiTapDelay", "E1-", "P4"):
         "reset() empties both lines where the control's hold older laps; they"
         " die to 1 LSB inside tail_samples, and a 1-LSB rounding difference"
@@ -243,6 +251,23 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (Mix)',
 }
 
+#: A control that jumps steps the output (the family's ruled disclosure,
+#: audiocomponents#117): P5 at every event that moves a control.
+for _name, _why in (
+    ("AnalogDelay",
+     "a control that jumps steps the output (family, audiocomponents#117);"
+     " a Time move bends the pitch while the line walks, by design"),
+    ("SlapbackDelay",
+     "a control that jumps steps the output (family, audiocomponents#117):"
+     " Level, Tone and patch moves have no ramp"),
+    ("MultiTapDelay",
+     "family limit, disclosed (audiocomponents#117): a control that jumps"
+     " makes the output step (Time and Heads move every head to a new"
+     " grid, Mix, Tilt and a patch change jump a level)"),
+):
+    for _event in CONTROL_EVENTS:
+        DECLARED[(_name, _event, "P5")] = _why
+
 #: Cells that are not run at all on one interpreter, one row per (class or
 #: adapter NAME, event name prefix, `sys.implementation.name`): reason. A
 #: skipped cell prints `na(skip: <reason>)` on every property and builds
@@ -262,8 +287,91 @@
         " MicroPython",
 }
 
+#: PR (a reset or a return from Mix 0 renders as a fresh instance) is
+#: excused only here, never in DECLARED: a class NAME -> the free-running
+#: phase that keeps it from matching a fresh instance, named (an LFO, a
+#: wow table). A red PR cell of a class named here prints `decl`.
+FREE_PHASE = {}
+
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
 
+#: Every property a cell can print.
+ALL_PROPS = ("P1", "P2", "P3", "P4", "P5", "PD", "PF", "PR")
+
+
+def _whole_event(prefix):
+    """True when `prefix` names at least one whole event number and its
+    dash: "E4-" and "E10-reset" do, "E" and "E1" do not."""
+    if len(prefix) < 3 or prefix[0] != "E":
+        return False
+    i = 1
+    while i < len(prefix) and "0" <= prefix[i] <= "9":
+        i += 1
+    return i > 1 and i < len(prefix) and prefix[i] == "-"
+
+
+def declared_scope(key):
+    """(patches or None, interpreters or None) of a DECLARED key."""
+    patches = impls = None
+    for scope in key[3:]:
+        if isinstance(scope, tuple):
+            patches = scope
+        else:
+            impls = tuple(scope.split(","))
+    return patches, impls
+
+
+def check_declared(table=None, free=None):
+    """Refuse a malformed DECLARED row with a ValueError that says which.
+    Run at import, and again by `run_class` for rows added since."""
+    table = DECLARED if table is None else table
+    free = FREE_PHASE if free is None else free
+    for key in table:
+        what = "lifecycle DECLARED row %r: " % (key,)
+        if not isinstance(key, tuple) or len(key) < 3:
+            raise ValueError(what + "a row is (NAME, event prefix, property"
+                             "[, scope...])")
+        name, prefix, prop = key[:3]
+        if not _whole_event(prefix):
+            raise ValueError(
+                what + "the event prefix %r is shorter than one whole event"
+                " name, so it would match events its reason does not"
+                " describe; name each event (\"E4-\", \"E10-reset\")"
+                % (prefix,))
+        if prop not in ALL_PROPS:
+            raise ValueError(what + "no property %r" % (prop,))
+        if prop == "PR":
+            raise ValueError(what + "PR is excused only by FREE_PHASE, "
+                             "which names the free-running phase")
+        kinds = []
+        for scope in key[3:]:
+            if isinstance(scope, tuple):
+                kinds.append("patches")
+                for patch in scope:
+                    if patch is not None and not isinstance(patch, int):
+                        raise ValueError(what + "a patch scope holds patch"
+                                         " numbers or None, not %r"
+                                         % (patch,))
+            elif isinstance(scope, str):
+                kinds.append("interpreters")
+                for impl in scope.split(","):
+                    if impl not in IMPLS:
+                        raise ValueError(what + "no interpreter %r (%s)"
+                                         % (impl, ", ".join(IMPLS)))
+            else:
+                raise ValueError(what + "a scope is a tuple of patches or"
+                                 " a string of interpreters, not %r"
+                                 % (scope,))
+        if len(kinds) != len(set(kinds)):
+            raise ValueError(what + "each kind of scope at most once")
+    for name, phase in free.items():
+        if not isinstance(phase, str) or not phase.strip():
+            raise ValueError("lifecycle FREE_PHASE[%r] must name the "
+                             "free-running phase" % (name,))
+
+
+check_declared()
+
 
 # --------------------------------------------------------------------------
 # Material
@@ -498,6 +606,15 @@ def act(e, feed, ctx, actions):
             e.set_macro(a[1], a[2])
         elif op == "patch":
             e.program_change(a[1])
+        elif op == "mixto":
+            # Land exactly where a constructor given the same value lands,
+            # so the fresh instance E12 compares with stands at the same
+            # position, not one float step away.
+            e.set_macro(a[1], a[2])
+            want = fresh_position(type(e), a[1], a[2])
+            if e._macros[a[1]] != want:
+                e._macros[a[1]] = want
+                e._apply_macro(a[1], want)
         elif op == "restore":
             restore(e, ctx)
         elif op == "end":
@@ -511,8 +628,16 @@ class Event:
     `back` GAP pulls later (in the same gap when `first`)."""
 
     def __init__(self, name, away, back=None, kind="256", moves_mix=False,
-                 control_move=True, post0=False, first=False, gap=GAP):
+                 control_move=True, post0=False, first=False, gap=GAP,
+                 fresh=None, landing=False):
         self.name = name
+        #: E12: the constructor keywords of the fresh instance the cell is
+        #: judged against, in place of the uninterrupted control.
+        self.fresh = fresh
+        #: PR: True when the cell's last action lands the class on a state
+        #: a fresh instance can be built at ("reset": patch 0; "config": the
+        #: configuration the cell runs at).
+        self.landing = landing
         self.away = away
         self.back = back or []
         self.kind = kind
@@ -531,7 +656,7 @@ def events(cls, patch, quick=False):
     full = (not quick) or patch is None
     out = [
         Event("E1-reset@block", [("reset",)], kind="256",
-              control_move=False, post0=True),
+              control_move=False, post0=True, landing="reset"),
         Event("E1-reset@part", [("reset",)], kind="100",
               control_move=False, post0=True),
         Event("E2-reset_buffer", [("rb",)], control_move=False),
@@ -543,7 +668,7 @@ def events(cls, patch, quick=False):
                                  [("restore",)], moves_mix=(i == mix)))
     if mix is not None:
         out.append(Event("E5-mix0", [("macro", mix, 0)], [("restore",)],
-                         moves_mix=True, gap=6))
+                         moves_mix=True, gap=6, landing="config"))
     targets = range(npatch) if full else (0, npatch - 1)
     for q in targets:
         if q == patch:
@@ -557,14 +682,14 @@ def events(cls, patch, quick=False):
                              [("restore",)], kind=kind, moves_mix=True,
                              gap=6))
     out.append(Event("E10-reset", [("reset",)], control_move=False,
-                     post0=True, first=True))
+                     post0=True, first=True, landing="reset"))
     if full:
         out.append(Event("E10-macros",
                          [("macro", i, 127) for i in range(len(labels))],
                          [("restore",)], moves_mix=True, first=True))
     if mix is not None:
         out.append(Event("E10-mix0", [("macro", mix, 0)], [("restore",)],
-                         moves_mix=True, first=True))
+                         moves_mix=True, first=True, landing="config"))
     out.append(Event("E10-patch", [("patch", npatch - 1 if patch != npatch - 1
                                     else 0)], [("restore",)],
                      moves_mix=True, first=True))
@@ -581,6 +706,17 @@ def events(cls, patch, quick=False):
                          [("macro", 0, 0), ("macro", 0, 127),
                           ("patch", npatch - 1)],
                          [("restore",)], moves_mix=True))
+    if patch is None:
+        # A move before the first pull that stays, against an instance
+        # built there: each patch, and Mix to 0, 64 and 127.
+        for q in sorted(cls.PATCHES):
+            out.append(Event("E12-p%d" % q, [("patch", q)], moves_mix=True,
+                             first=True, fresh={"patch": q}))
+        if mix is not None:
+            for v in (0, 64, 127):
+                out.append(Event("E12-mix%d" % v, [("mixto", mix, v)],
+                                 moves_mix=True, first=True,
+                                 fresh={"mix": v}))
     return out
 
 
@@ -588,6 +724,47 @@ def events(cls, patch, quick=False):
 # Rendering
 
 
+def fresh_position(cls, index, midi):
+    """The 0..1 position a constructor lands macro `index` on when handed
+    the value MIDI `midi` stands for."""
+    span = cls._MACRO_RANGES[index]
+    value = _component.macro_value(span, _component.position_of_midi(
+        cls.MACRO_MODES.get(index, "UNIPOLAR"), midi))
+    return _component.macro_position(span, value)
+
+
+#: The constructor keyword of a class's wet/dry control, where it is not
+#: `mix`.
+MIX_KEYWORD = {
+    "SlapbackDelay": "level",
+}
+
+
+def build_fresh(cls, feed, rate, options, fresh):
+    """A fresh instance built at `fresh`: {"patch": q} is the constructor's
+    `patch=q`, {"mix": v} its Mix keyword at the value MIDI v stands for,
+    and {} the defaults. Raises TypeError when the constructor takes no
+    such keyword."""
+    keywords = dict(options)
+    if "patch" in fresh and fresh["patch"] is not None:
+        keywords["patch"] = fresh["patch"]
+    if "mix" in fresh:
+        index = mix_index(cls)
+        span = cls._MACRO_RANGES[index]
+        keywords[MIX_KEYWORD.get(cls.NAME, "mix")] = _component.macro_value(
+            span, _component.position_of_midi(
+                cls.MACRO_MODES.get(index, "UNIPOLAR"), fresh["mix"]))
+    e = cls(feed.port, sample_rate=rate, **keywords)
+    if "mix" in fresh:
+        index = mix_index(cls)
+        if e._macros[index] != fresh_position(cls, index, fresh["mix"]):
+            e.deinit()
+            raise TypeError("the constructor's %s did not land on Mix %d"
+                            % (MIX_KEYWORD.get(cls.NAME, "mix"),
+                               fresh["mix"]))
+    return e
+
+
 def _build(cls, feed, rate, patch, options, post0=False):
     e = cls(feed.port, sample_rate=rate, **options)
     if patch is not None:
@@ -717,7 +894,7 @@ def p1(cls, ev, rate, channels, patch, options):
         return "na"
     if ev.name.startswith("E4-m%d=" % mix) and not ev.name.endswith("=0"):
         return "na"
-    if ev.name.startswith("E10-mix"):
+    if _starts(ev.name, ("E10-mix", "E12-mix")):
         return "na"
     values = material_for("once", rate, channels)
     feed = Feed(values, rate, channels, ev.kind, loop=False)
@@ -791,10 +968,21 @@ def _diagnose(out, expect, frame, fsize, hi):
     return ", not the source near there"
 
 
-def _decl(cls, ev, prop):
-    for (name, prefix, p), reason in DECLARED.items():
-        if name == cls.NAME and p == prop and ev.name.startswith(prefix):
-            return True
+def _decl(cls, ev, prop, patch=None, impl=None):
+    """True when a DECLARED row covers this cell: its class, property and
+    event prefix, and its scopes, if it has any, hold `patch` (None: the
+    defaults) and this interpreter."""
+    impl = impl or sys.implementation.name
+    for key in DECLARED:
+        name, prefix, p = key[:3]
+        if name != cls.NAME or p != prop or not ev.name.startswith(prefix):
+            continue
+        patches, impls = declared_scope(key)
+        if patches is not None and patch not in patches:
+            continue
+        if impls is not None and impl not in impls:
+            continue
+        return True
     return False
 
 
@@ -811,7 +999,16 @@ def main_render(cls, ev, rate, channels, patch, options, controls):
     # The control is rendered in step with the instance, pull for pull,
     # and compared as it goes: nothing tail-long is kept.
     cfeed = Feed(values, rate, channels, ev.kind, loop=True)
-    c = _build(cls, cfeed, rate, patch, options, ev.post0)
+    c = None
+    if ev.fresh is not None:
+        # E12: judged against an instance built at the move's setting.
+        try:
+            c = build_fresh(cls, cfeed, rate, options, ev.fresh)
+        except TypeError as err:
+            res["P4"] = res["PF"] = "na(no fresh build: %s)" % (
+                str(err).replace("|", "/")[:60])
+    if c is None:
+        c = _build(cls, cfeed, rate, patch, options, ev.post0)
     try:
         out = bytearray()
         at = _schedule_run(e, feed, ctx, ev, out, fsize,
@@ -823,6 +1020,13 @@ def main_render(cls, ev, rate, channels, patch, options, controls):
                 # ended, and stays silent.
                 cfeed.point(cfeed.sil)
             _pull(c, cout)
+        if ev.fresh is not None and "PF" not in res:
+            # The first block: the move must already have landed in it.
+            n = BLOCK * fsize
+            d = _first_diff(out, cout, 0, min(n, len(out), len(cout)))
+            res["PF"] = "ok" if d < 0 else (
+                "RED(first block differs from a fresh instance's at"
+                " frame %d)" % (d // fsize))
         last = at[-1] if at else 0
         tail = _tail(e)
         lat = e.latency_samples
@@ -1111,6 +1315,110 @@ def e3(cls, rate, channels, patch, options):
     return res
 
 
+#: PR compares this many frames from the landing on.
+PR_FRAMES = 16 * BLOCK
+
+
+def _land_pull(ev):
+    """The pull the cell's last action is taken before."""
+    if ev.first:
+        return 0
+    return K0 + ev.gap if ev.back else K0
+
+
+def _drive(e, feed, ctx, ev, upto, land):
+    """Pull up to pull `upto`, taking `ev`'s actions before the pulls they
+    are due at; with `land` the actions due before pull `upto` are taken
+    too (and that pull is not)."""
+    k0 = 0 if ev.first else K0
+    kb = k0 if ev.first else k0 + ev.gap
+    out = bytearray()
+    for k in range(upto + 1):
+        if k == upto and not land:
+            return
+        if k == k0:
+            act(e, feed, ctx, ev.away)
+        if k == kb and ev.back:
+            act(e, feed, ctx, ev.back)
+        if k == upto:
+            return
+        _pull(e, out)
+
+
+def _locate(material, block, fsize):
+    """The frame `block` starts at in `material`, or -1."""
+    i = material.find(block)
+    while i >= 0 and i % fsize:
+        i = material.find(block, i + 1)
+    return -1 if i < 0 else i // fsize
+
+
+def _diverge(a, b, frames, fsize):
+    """The first frame where `a` and `b` render differently, pulled in
+    step for `frames`, or -1."""
+    abuf = bytearray()
+    bbuf = bytearray()
+    base = 0
+    total = frames * fsize
+    while base < total:
+        if not abuf:
+            abuf = bytearray(_pull_some(a, fsize))
+        if not bbuf:
+            bbuf = bytearray(_pull_some(b, fsize))
+        n = min(len(abuf), len(bbuf), total - base)
+        if abuf[:n] != bbuf[:n]:
+            return (base + _first_diff(abuf, bbuf, 0, n)) // fsize
+        abuf = abuf[n:]
+        bbuf = bbuf[n:]
+        base += n
+    return -1
+
+
+def pr(cls, ev, rate, channels, patch, options):
+    """PR: from the move that lands the class (a reset, a return from Mix
+    0) on, it renders byte for byte what a fresh instance built at the
+    landing state renders, fed the same source from the same frame."""
+    fsize = 2 * channels
+    values = material_for("once", rate, channels)
+    upto = _land_pull(ev)
+    landing = 0 if ev.landing == "reset" else patch
+    fresh = {} if landing is None else {"patch": landing}
+    start = 0
+    if not ev.first:
+        # Where the source stands at the landing: a dry run to it, then
+        # the source's next block, found in the material.
+        feed = Feed(values, rate, channels, "256", loop=False)
+        e = _build(cls, feed, rate, patch, options)
+        try:
+            _drive(e, feed, Ctx(e, patch), ev, upto, False)
+            block = bytes(audiocore.get_buffer(feed.mat)[1])
+        finally:
+            e.deinit()
+        start = _locate(bytes(values), block, fsize)
+        if start < 0:
+            return "na(source position not found)"
+    feed = Feed(values, rate, channels, "256", loop=False)
+    e = _build(cls, feed, rate, patch, options)
+    f = None
+    try:
+        _drive(e, feed, Ctx(e, patch), ev, upto, True)
+        ffeed = Feed(values[start * channels:], rate, channels, "256",
+                     loop=False)
+        try:
+            f = build_fresh(cls, ffeed, rate, options, fresh)
+        except TypeError as err:
+            return "na(no fresh build: %s)" % (
+                str(err).replace("|", "/")[:60])
+        d = _diverge(e, f, PR_FRAMES, fsize)
+    finally:
+        e.deinit()
+        if f is not None:
+            f.deinit()
+    if d < 0:
+        return "ok"
+    return "RED(differs from a fresh instance at +%d)" % d
+
+
 def _skip(cls, ev, impl=None):
     """SKIP's reason for this cell on `impl` (this interpreter by
     default), or None."""
@@ -1130,8 +1438,13 @@ def run_cell(cls, ev, rate, channels, patch, options, controls):
     res.update(main_render(cls, ev, rate, channels, patch, options,
                            controls))
     res["P5"] = p5(cls, ev, rate, channels, patch, options, controls)
-    for prop in PROPS:
-        if res[prop].startswith("RED") and _decl(cls, ev, prop):
+    if ev.landing:
+        res["PR"] = pr(cls, ev, rate, channels, patch, options)
+        if res["PR"].startswith("RED") and cls.NAME in FREE_PHASE:
+            res["PR"] = "decl"
+    for prop in PROPS + ("PF",):
+        if prop in res and res[prop].startswith("RED") and \
+                _decl(cls, ev, prop, patch):
             res[prop] = "decl"
     return res
 
@@ -1150,6 +1463,7 @@ def run_class(cls, options=None, rates=RATES, channels=CHANNELS,
     line last. Returns (cells, red, declared)."""
     options = options or {}
     name = name or cls.NAME
+    check_declared()
     if patches is None:
         patches = [None] + sorted(cls.PATCHES)
     cells = red = decl = 0
@@ -1179,7 +1493,7 @@ def run_class(cls, options=None, rates=RATES, channels=CHANNELS,
                         emit(line)
                         cells += 1
                         red += 1 if "RED" in line else 0
-                        decl += line.count(":decl")
+                        decl += 1 if ":decl" in line else 0
                 finally:
                     for ctl in controls.values():
                         ctl.close()
@@ -1340,8 +1654,65 @@ def tail_samples(self):
         return 0
 
 
+class _FirstPull:
+    """A Python-level output (CPython only) that calls `hook` once, after
+    the first block it hands on."""
+
+    def __init__(self, inner, hook):
+        self.inner = inner
+        self.hook = hook
+        self.sample_rate = inner.sample_rate
+        self.channel_count = inner.channel_count
+        self.bits_per_sample = 16
+        self.samples_signed = True
+
+    def _reset_buffer(self, single_channel_output=False, audio_channel=0):
+        audiocore.reset_buffer(self.inner)
+
+    def _get_buffer(self, single_channel_output=False, audio_channel=0):
+        got = audiocore.get_buffer(self.inner)
+        hook = self.hook
+        if hook is not None:
+            self.hook = None
+            hook()
+        return got
+
+
+class LatePatch(Plain):
+    """PF: a move made before the first pull lands one block late, so the
+    first block plays at the level the class was built at (CPython only:
+    its output is a Python-level node)."""
+    NAME = "LifecycleLatePatch"
+
+    def _build(self, mix=1.0, gain=1.0, patch=None):
+        self._pulled = False
+        Plain._build(self, mix, gain, patch)
+        self._output = _FirstPull(self._mixer, self._first)
+
+    def _first(self):
+        self._pulled = True
+        Plain._apply_macro(self, 0, self._macros[0])
+
+    def _apply_macro(self, index, position):
+        if self._constructing or self._pulled:
+            Plain._apply_macro(self, index, position)
+
+
+class ResetLeak(Routed):
+    """PR: reset() keeps the echo line, so the 5 ms it held plays after the
+    reset where a fresh instance plays silence; inside tail_samples, so P4
+    reads it as ok."""
+    NAME = "LifecycleResetLeak"
+
+    def reset(self):
+        self._check_live()
+        self._clear_nodes(keep=(self._echo,))
+        self._stranded = False
+        self.program_change(0)
+
+
 PLANTS = {"plain": Plain, "routed": Routed, "droponreset": DropOnReset,
-          "holddc": HoldDC,
+          "holddc": HoldDC, "latepatch": LatePatch, "resetleak": ResetLeak,
           "stalemix": StaleMix, "latemove": LateMove,
           "hardswitch": HardSwitch, "busydeinit": BusyDeinit,
           "implplant": ImplPlant}
diff --git a/tests/support/node_matrix.py b/tests/support/node_matrix.py
index 2d8f733..87e45c5 100644
--- a/tests/support/node_matrix.py
+++ b/tests/support/node_matrix.py
@@ -468,10 +468,12 @@ def _apply_macro(self, index, position):
 #: Ruled N1 (2026-10-13): a control that jumps steps the output in every
 #: node (no in-node ramp yet; audiocomponents docs/control-smoothing.md),
 #: so P5 is declared for every node adapter.
+import lifecycle  # noqa: E402
+
 for _name in NODES:
-    DECLARED[(_name, "E", "P5")] = (
-        "a control that jumps steps the output; the in-node 20 ms ramp is"
-        " planned, not built (docs/control-smoothing.md)")
+    for _event in lifecycle.CONTROL_EVENTS:
+        DECLARED[(_name, _event, "P5")] = (
+            "a control that jumps steps the output; the in-node 20 ms ramp"
+            " is planned, not built (docs/control-smoothing.md)")
 
-import lifecycle  # noqa: E402
 lifecycle.DECLARED.update(DECLARED)
diff --git a/tests/test_kit.py b/tests/test_kit.py
index 6f86ad7..85b8200 100644
--- a/tests/test_kit.py
+++ b/tests/test_kit.py
@@ -243,6 +243,17 @@ def test_a_second_reset_in_a_row_is_red(self):
         self.assertEqual(verdict(cells, "DoubleReset", "nogb",
                                  "bytes-reset-once/48000/2/d"), "ok")
 
+    def test_every_patch_is_run(self):
+        cells = nogb_cells(kp.MidPatchReset)
+        key = "bytes-reset-first/48000/2/p1"
+        self.assertTrue(red(verdict(cells, "MidPatchReset", "nogb", key)))
+        for other in ("d", "p0", "p2"):
+            self.assertEqual(verdict(cells, "MidPatchReset", "nogb",
+                                     "bytes-reset-first/48000/2/" + other),
+                             "ok", other)
+        control = nogb_cells(kp.FlushKit3)
+        self.assertEqual(verdict(control, "FlushKit3", "nogb", key), "ok")
+
     def test_get_buffer_is_put_back(self):
         import audiocore
         import audioeffects._component as component
@@ -265,7 +276,8 @@ def test_red_numbers_are_not_compared(self):
 class TestCeiling(unittest.TestCase):
 
     def v(self, cls, which="sine", patch=None, knob=None):
-        return kit_ceiling.measure(cls, 48000, 2, which, patch, knob)[0]
+        knobs = [knob] if isinstance(knob, tuple) else knob
+        return kit_ceiling.measure(cls, 48000, 2, which, patch, knobs)[0]
 
     def test_a_wrap_is_red(self):
         self.assertTrue(self.v(kp.WrapKit).startswith("RED(wrap"))
@@ -298,6 +310,41 @@ def test_silence_at_a_stop_is_red(self):
     def test_a_silent_class_is_red(self):
         self.assertTrue(self.v(kp.Silent).startswith("RED(silent"))
 
+    def sine_cells(self, cls):
+        lines = []
+        kit_ceiling.run(cls, emit=lines.append, quick=True,
+                        materials=("sine",))
+        return dict((k[2], v["V"]) for k, v in kc.parse(lines).items())
+
+    def test_every_macro_is_driven_at_64(self):
+        got = self.sine_cells(kp.MidWrap)
+        self.assertTrue(got["sine/48000/2/m1=64"].startswith("RED(wrap"))
+        self.assertEqual([k for k in got if red(got[k])],
+                         ["sine/48000/2/m1=64"])
+        self.assertEqual(self.sine_cells(kp.CondKit)["sine/48000/2/m1=64"],
+                         "ok")
+
+    def test_the_combined_settings_are_driven(self):
+        self.assertEqual(kit_ceiling.level_like(kp.CondKit), [0, 1])
+        combo = self.sine_cells(kp.ComboWrap)
+        self.assertEqual([k for k in combo if red(combo[k])],
+                         ["sine/48000/2/lv=127+m2=0"])
+        every = self.sine_cells(kp.AllWrap)
+        self.assertEqual(sorted(k for k in every if red(every[k])),
+                         ["sine/48000/2/all=127",
+                          "sine/48000/2/lv=127+m2=127"])
+        control = self.sine_cells(kp.CondKit)
+        self.assertEqual([k for k in control if red(control[k])], [])
+        self.assertIn("sine/48000/2/lv=127+m2=0", control)
+
+    def test_the_low_notes_are_played(self):
+        for which in ("sq41", "sq55"):
+            self.assertTrue(self.v(kp.LowWrap, which).startswith(
+                "RED(wrap"), which)
+            self.assertEqual(self.v(kp.KitPlain, which), "ok", which)
+        for which in ("square", "sine", "clicks", "dc"):
+            self.assertEqual(self.v(kp.LowWrap, which), "ok", which)
+
 
 FIXTURE_TESTS = '''
 import unittest
@@ -371,6 +418,25 @@ def test_a_declared_row_counts(self):
                                 "DECLARED:%s,%s,%s" % key),))
         self.assertEqual(got["row0"], "ok")
 
+    def test_a_scoped_row_is_named_with_its_scope(self):
+        rows = {("Fixture", "E10-reset", "P4", "circuitpython"): "planted",
+                ("Fixture", "E5-", "P1", (1, None)): "planted"}
+        lifecycle.DECLARED.update(rows)
+        try:
+            claim = "The output is the input at Gain 1."
+            for target, want in (
+                    ("DECLARED:Fixture,E10-reset,P4,circuitpython", "ok"),
+                    ("DECLARED:Fixture,E5-,P1,patches=d/1", "ok"),
+                    ("DECLARED:Fixture,E10-reset,P4", "RED"),
+                    ("DECLARED:Fixture,E10-reset,P4,micropython", "RED"),
+                    ("DECLARED:Fixture,E5-,P1,patches=1", "RED")):
+                with self.subTest(target=target):
+                    got = self.run_claims(((claim, target),))["row0"]
+                    self.assertTrue(got.startswith(want), got)
+        finally:
+            for row in rows:
+                del lifecycle.DECLARED[row]
+
     def test_a_claim_with_no_row_is_red(self):
         got = self.run_claims((), self.DOC + " It never clips.")
         self.assertEqual(sorted(got), ["loose0", "loose1", "table"])
@@ -430,6 +496,55 @@ def test_citations_to_this_repository(self):
         self.assertEqual(got["cite:audiodsp_tank.c:1"],
                          "na(no audiodsp checkout)")
 
+    CARD = """# Class card: `CondKit`
+
+## 3. The surface
+
+| # | Label | Mode | Span | Notes |
+|---|---|---|---|---|
+| 0 | `Mix` | UNIPOLAR | 0 … 1 | |
+| 1 | `%s` | UNIPOLAR, log | 0.25 … 1 | a \\| in a cell |
+| 2 | `Tone` | %s | 0 … 1 | |
+
+| Patch | Name | Mix |
+|---|---|---|
+| 0 | Default | 1 |
+
+## 4. Traits
+"""
+
+    def surface(self, card):
+        pin = kit_paperwork.Pin(None, None)
+        with tempfile.TemporaryDirectory() as cards:
+            if card is not None:
+                with open(os.path.join(cards, "CondKit.md"), "w") as f:
+                    f.write(card)
+            lines = []
+            kit_paperwork.check("CondKit", "", "", pin, lines.append,
+                                cls=kp.CondKit, cards=cards)
+        return dict((k[2], v["V"]) for k, v in kc.parse(lines).items()
+                    if k[2].startswith("surface"))
+
+    def test_the_surface_against_the_card(self):
+        self.assertEqual(self.surface(self.CARD % ("Level", "UNIPOLAR")),
+                         {"surface-m0": "ok", "surface-m1": "ok",
+                          "surface-m2": "ok"})
+        got = self.surface(self.CARD % ("Volume", "BIPOLAR"))
+        self.assertEqual(got["surface-m0"], "ok")
+        self.assertEqual(got["surface-m1"],
+                         "RED(class 'Level' UNIPOLAR, card 'Volume' "
+                         "UNIPOLAR)")
+        self.assertEqual(got["surface-m2"],
+                         "RED(class 'Tone' UNIPOLAR, card 'Tone' BIPOLAR)")
+        short = "\n".join(l for l in (self.CARD % ("Level", "UNIPOLAR"))
+                          .splitlines() if not l.startswith("| 2 "))
+        self.assertTrue(red(self.surface(short)["surface-m2"]))
+        self.assertEqual(self.surface(None),
+                         {"surface": "na(no card for CondKit)"})
+        self.assertEqual(self.surface("# Card\n\n## 3. Traits\n\n"
+                                      "| # | Trait |\n|---|---|\n"),
+                         {"surface": "na(no surface table in section 3)"})
+
     def test_the_citation_forms(self):
         found = kit_paperwork.citations(
             "`src/shared/a.c:344`, called at :529 (`b.h:3-5`, `:7`); "
diff --git a/tests/test_lifecycle_matrix.py b/tests/test_lifecycle_matrix.py
index af364b8..737fc4d 100644
--- a/tests/test_lifecycle_matrix.py
+++ b/tests/test_lifecycle_matrix.py
@@ -303,6 +303,9 @@ class TestPlants(unittest.TestCase):
         ("latemove", "plain", "E4-m1=0", "P4"),
         ("hardswitch", "plain", "E4-m0=0", "P5"),
         ("busydeinit", "plain", "E3-deinit", "PD"),
+        ("latepatch", "plain", "E12-p1", "PF"),
+        ("resetleak", "routed", "E1-reset@block", "PR"),
+        ("stalemix", "routed", "E5-mix0", "PR"),
     )
 
     def test_each_plant_is_red_and_its_control_green(self):
@@ -323,6 +326,97 @@ def test_a_declared_exception_prints_decl(self):
                                     "P1")]
         self.assertEqual(got, "decl")
 
+    def test_p4_misses_what_pf_and_pr_catch(self):
+        """P4 forgives a block (and a tail) after the move; PF and PR do
+        not, so these plants are ok on P4 and red only on the new
+        properties."""
+        self.assertEqual(plant_cell("latepatch", "E12-p1", "P4"), "ok")
+        self.assertEqual(plant_cell("resetleak", "E1-reset@block", "P4"),
+                         "ok")
+
+    def test_e12_is_judged_against_a_fresh_instance(self):
+        lines = []
+        lifecycle.run_class(lifecycle.Plain, rates=(48000,), channels=(2,),
+                            patches=[None], only=["E12"], emit=lines.append)
+        got = sorted(k[1] for k in parse(lines))
+        self.assertEqual(got, ["E12-mix0", "E12-mix127", "E12-mix64",
+                               "E12-p0", "E12-p1"])
+        for props in parse(lines).values():
+            self.assertEqual(props["PF"], "ok")
+            self.assertEqual(props["P4"], "ok")
+
+    def test_a_scoped_row_matches_only_its_scope(self):
+        here = sys.implementation.name
+        other = "circuitpython" if here != "circuitpython" else "cpython"
+        cases = (
+            (("LifecyclePlain", "E1-reset@block", "P1", here), None, "decl"),
+            (("LifecyclePlain", "E1-reset@block", "P1", other), None, "RED"),
+            (("LifecyclePlain", "E1-reset@block", "P1", (1,)), None, "RED"),
+            (("LifecyclePlain", "E1-reset@block", "P1", (1,)), 1, "decl"),
+            (("LifecyclePlain", "E1-reset@block", "P1", (None, 1), here),
+             None, "decl"),
+            # The Octaver form, a patch tuple as the fourth element.
+            (("LifecyclePlain", "E1-", "P1", (0, 1)), 1, "decl"),
+        )
+        for row, patch, want in cases:
+            with self.subTest(row=row, patch=patch):
+                lifecycle.DECLARED[row] = "planted"
+                try:
+                    got = plant_cell("droponreset", "E1-reset@block", "P1",
+                                     patch=patch)
+                finally:
+                    del lifecycle.DECLARED[row]
+                self.assertTrue(got.startswith(want), got)
+
+    def test_a_row_shorter_than_an_event_is_refused(self):
+        for prefix in ("E", "E1", "", "X1-"):
+            with self.subTest(prefix=prefix):
+                with self.assertRaises(ValueError) as caught:
+                    lifecycle.check_declared({("X", prefix, "P1"): "r"})
+                self.assertIn("shorter than one whole event name",
+                              str(caught.exception))
+        for bad in (("X", "E1-", "P9"), ("X", "E1-", "P1", "pypy"),
+                    ("X", "E1-", "P1", ("1",)), ("X", "E1-", "PR"),
+                    ("X", "E1-", "P1", (1,), (2,))):
+            with self.subTest(row=bad):
+                with self.assertRaises(ValueError):
+                    lifecycle.check_declared({bad: "r"})
+        lifecycle.check_declared({("X", "E10-reset", "P4", "circuitpython"):
+                                  "r", ("X", "E4-m2=", "P5"): "r"})
+        # run_class checks rows added after import too.
+        lifecycle.DECLARED[("LifecyclePlain", "E", "P1")] = "planted"
+        try:
+            with self.assertRaises(ValueError):
+                plant_cell("plain", "E1-reset@block", "P1")
+        finally:
+            del lifecycle.DECLARED[("LifecyclePlain", "E", "P1")]
+        with self.assertRaises(ValueError):
+            lifecycle.check_declared({}, {"X": ""})
+
+    def test_free_phase_excuses_pr_and_the_summary_counts_cells(self):
+        def e10():
+            lines = []
+            lifecycle.run_class(lifecycle.PLANTS["routed"], rates=(48000,),
+                                channels=(2,), patches=[None], only=["E10"],
+                                emit=lines.append)
+            return lines
+        before = parse(e10())
+        self.assertTrue(before[("LifecycleRouted", "E10-reset", 48000, 2,
+                                "d")]["PR"].startswith("RED"))
+        row = ("LifecycleRouted", "E10-reset", "P1")
+        lifecycle.DECLARED[row] = "planted"
+        lifecycle.FREE_PHASE["LifecycleRouted"] = "a planted phase"
+        try:
+            lines = e10()
+        finally:
+            del lifecycle.DECLARED[row]
+            del lifecycle.FREE_PHASE["LifecycleRouted"]
+        cell = parse(lines)[("LifecycleRouted", "E10-reset", 48000, 2, "d")]
+        self.assertEqual((cell["P1"], cell["PR"]), ("decl", "decl"))
+        # Three declared properties in two cells: the SUMMARY counts cells.
+        self.assertEqual(sum(l.count(":decl") for l in lines), 3)
+        self.assertTrue(lines[-1].endswith("|declared 2"), lines[-1])
+
     def test_a_skipped_cell_prints_na_and_never_runs(self):
         class Raises(lifecycle.Plain):
             NAME = "LifecycleRaises"

From d63bfa77b327de725d2407e2464997538b2caf05 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 02:53:07 -0500
Subject: [PATCH 43/76] AirSpace: pull the mixer through a one-voice mixer
 where get_buffer is compiled out, a -12 dBFS ceiling, the flutter and
 gentle-filter limits, a constructor value kept off a default's step

---
 lib/audioeffects/rebuilt/airspace.py   | 136 +++++++---
 tests/test_cpython_effects_airspace.py | 357 ++++++++++++++++++++++---
 2 files changed, 420 insertions(+), 73 deletions(-)

diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
index b76bf1f..cadefd0 100644
--- a/lib/audioeffects/rebuilt/airspace.py
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -21,9 +21,10 @@
 a move across the whole Time range takes, so it sets how far they bend: 12 %
 at the default of 4 s.
 
-Keep your input at or under -6 dBFS: the dry is at unity and the chamber
-adds to it, so a hotter input can reach the rail. Latency is zero. `reset()` empties the tape and the chamber and restores
-patch 0, whose Time of 111 ms lands at once instead of gliding.
+Keep your input at or under -12 dBFS: at Mix 1 the dry and the chamber are
+both at unity and add, so a hotter input can reach the rail. Latency is
+zero. `reset()` empties the tape and the chamber and restores patch 0, whose
+Time of 111 ms lands at once instead of gliding.
 
 The patches: Chamber Send (the defaults), Short Send, Long Send, Dark Loop,
 Bright Chamber, Driven Tape, Plain Chamber.
@@ -39,10 +40,14 @@
 At the defaults the repeats add only a little length to the tail; the
 stretch comes with Feedback above about 0.6 or a long Time.
 
+At a short Time with high Feedback the repeats are heard as a flutter, not a
+longer chamber.
+
 There is always at least 20 ms between the dry and the chamber.
 
-The loop's filters are gentle, and Drive's level is not compensated. The
-chamber's size is fixed, there is no tempo sync, and a mono source gets a
+The loop's filters are gentle, 6 dB per octave, and the Top Cut's is
+steeper: there is no loop bell, no presence EQ and no wow. Drive's level is
+not compensated. The chamber's size is fixed, there is no tempo sync, and a mono source gets a
 mono rack.
 
 At Mix 0 the output is your input, byte for byte, and the tail that was
@@ -116,9 +121,11 @@
             4000.0, 0.35)
 
 #: Each default's step on the 0-127 grid (`_component.macro_of`): patch 0.
-#: While a macro sits on its default's step, the default itself plays, so
-#: a fresh instance, patch 0 and a host echoing `get_macro` all play
-#: exactly 111 ms, not the step's 112.08.
+#: While a macro that arrived as a whole step (the seed, a patch, a whole
+#: `set_macro`) sits on its default's step, the default itself plays, so a
+#: fresh instance, patch 0 and a host echoing `get_macro` all play exactly
+#: 111 ms, not the step's 112.08. A constructor value that is not the
+#: default is not a step and plays as given, even where it lands on one.
 DEFAULT_STEPS = (68, 56, 76, 25, 82, 52, 74, 64, 65, 76, 22)
 
 #: How close a 0..1 position must come to a default's step to play the
@@ -199,7 +206,7 @@ class _Chamber(_reverb.Reverb):
 
     CAPABILITIES = ()
     LATENCY_SAMPLES = 0
-    INPUT_CEILING_DBFS = -6.0
+    INPUT_CEILING_DBFS = -12.0
     TAIL_SAMPLES = None
 
     MACRO_LABELS = ("Time", "Feedback", "Glide", "Drive", "Loop Top",
@@ -260,6 +267,11 @@ def _build(self, time_ms=111.0, feedback=0.375, glide_ms=4000.0,
             values.append(_between(_option(value, DEFAULTS[index]),
                                    span[0], span[1]))
 
+        #: Per macro, whether its position arrived as a whole grid step and
+        #: so plays the default on the default's step (`_value`). The
+        #: constructor clears it for a value that is not the default.
+        self._snap = [values[index] == DEFAULTS[index]
+                      for index in range(len(values))]
         #: True once every macro has been seeded; before that a macro is
         #: stored and not pushed.
         self._ready = False
@@ -307,6 +319,10 @@ def _build(self, time_ms=111.0, feedback=0.375, glide_ms=4000.0,
         # keeps.
         self._tail = audioroute.MidSide(
             self._mixer, width=1.0, sample_rate=rate, channel_count=channels)
+        #: Where `audiocore.get_buffer` is compiled out, the one-voice
+        #: mixer `_pull` primes from `_tail`; built the first time it is
+        #: needed.
+        self._puller = None
         self._silence = audiocore.RawSample(
             array("h", bytes(2 * 2 * channels)), sample_rate=rate,
             channel_count=channels)
@@ -344,10 +360,11 @@ def _build(self, time_ms=111.0, feedback=0.375, glide_ms=4000.0,
 
     def _value(self, index):
         """Macro `index` in its own units: the default itself on the
-        default's step, the span's law elsewhere."""
+        default's step when the position arrived as a step, the span's law
+        elsewhere."""
         position = self._macros[index]
         step = DEFAULT_STEPS[index] / 127.0
-        if abs(position - step) <= STEP_TOLERANCE:
+        if self._snap[index] and abs(position - step) <= STEP_TOLERANCE:
             return DEFAULTS[index]
         return _component.macro_value(self._MACRO_RANGES[index], position)
 
@@ -357,6 +374,41 @@ def macro(self, index):
         self._check_live()
         return self._value(index)
 
+    def set_macro(self, index, value, channel=0, note_id=-1,
+                  sample_position=0):
+        """Set macro `index` from the 0-127 scale. A whole step is a step
+        and plays the default on the default's step; a fraction is a value
+        of its own. A call that leaves the position where it is (a host
+        echoing `get_macro`) changes neither."""
+        self._check_live()
+        self._macro_index(index)
+        flags = list(self._snap)
+        try:
+            position = _component.position_of_midi("UNIPOLAR", value)
+            if abs(position - self._macros[index]) > STEP_TOLERANCE:
+                self._snap[index] = abs(value - round(value)) <= 127.0 * (
+                    STEP_TOLERANCE)
+            _component.Component.set_macro(
+                self, index, value, channel, note_id, sample_position)
+        except Exception:
+            self._snap = flags
+            raise
+
+    def program_change(self, index, channel=0, note_id=-1,
+                       sample_position=0):
+        """Apply patch `index`: every macro lands on a whole step."""
+        self._check_live()
+        flags = list(self._snap)
+        if (not isinstance(index, bool) and isinstance(index, int)
+                and type(self).PATCHES.get(index) is not None):
+            self._snap = [True] * len(flags)
+        try:
+            _component.Component.program_change(
+                self, index, channel, note_id, sample_position)
+        except Exception:
+            self._snap = flags
+            raise
+
     def _dry_level(self, mix):
         """The dry voice's level, min(1, 2 - Mix). At one channel unity is
         handed as 1 - 2^-15, which every Mixer this class meets passes
@@ -439,46 +491,56 @@ def _route(self):
         self._levels()
         if not self._wired:
             self._wire()
-        elif self._rejoin() and getattr(audiocore, "get_buffer", None) is None:
-            self._replay()
+        else:
+            self._rejoin()
         self._output = self._tail
 
-    def _replay(self):
-        """Play the voices again on a return from Mix 0 where
-        `audiocore.get_buffer` is compiled out (a board's own audiocore).
-
-        There the constructor's wiring primes the source's first block into
-        the voices, and a Mix 0 before the first pull leaves that block
-        held while the bypass plays on; without this, the return would play
-        it stale. Mid-stream no voice holds a block, and a re-play primes
-        the source's next block, which the next pull plays on time. Where
-        `get_buffer` exists the wiring is quiet and nothing is held."""
-        voices = self._mixer.voice
-        voices[0].play(self._split.tap(0))
-        voices[1].play(self._wet_source())
-
     def _wire(self):
         """Play the voices, the first time Mix is above 0.
 
         A voice's `play()` primes a block from its source. With the
         Splitter on `_hush` that block is zeros, and one pull of the mixer
         hands it out, so wiring takes nothing from the borrowed source and
-        leaves no voice holding a block. The graph is then emptied, so the
+        leaves no voice holding a block: whatever the adapter has handed
+        out, the output has played. The graph is then emptied, so the
         chamber's modulation and the tape start where a `reset()` leaves
-        them. Without `audiocore.get_buffer` the voices prime the source's
-        next block, which the next pull plays."""
-        pull = getattr(audiocore, "get_buffer", None)
+        them. The voices first play silence for one pull, which opens
+        their level gates where `audiocore.get_buffer` exists
+        (`_component.open_level_gates`)."""
         voices = self._mixer.voice
-        _component.open_level_gates(self._mixer, voices, self._silence)
-        if pull is None:
-            self._in.play(self._adapter)
+        for voice in voices:
+            voice.play(self._silence, loop=True)
+        self._pull()
         voices[0].play(self._split.tap(0))
         voices[1].play(self._wet_source())
+        self._pull()
+        self._in.play(self._adapter)
+        self._clear_nodes()
+        self._wired = True
+
+    def _pull(self):
+        """Pull one block from the mixer and drop it.
+
+        Where `audiocore.get_buffer` is compiled out (CircuitPython's
+        default board builds), a voice of a one-voice mixer of our own
+        plays `_tail` and stops: its `play()` primes one block, which pulls
+        the mixer once. `_tail` forwards no reset, so the play rewinds
+        nothing behind it."""
+        pull = getattr(audiocore, "get_buffer", None)
         if pull is not None:
             pull(self._mixer)
-            self._in.play(self._adapter)
-            self._clear_nodes()
-        self._wired = True
+            return
+        if self._puller is None:
+            # Nothing ever pulls this mixer, so its own buffers are the
+            # smallest that hold a frame.
+            self._puller = self._own(audiomixer.Mixer(
+                voice_count=1, buffer_size=16,
+                channel_count=self._channel_count, bits_per_sample=16,
+                samples_signed=True, sample_rate=self._sample_rate),
+                reset=False)
+        voice = self._puller.voice[0]
+        voice.play(self._tail)
+        voice.stop()
 
     def _clear_tape(self):
         """Empty the tape. The node then lands its read head on the next
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index 2030560..5b269d2 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -527,6 +527,16 @@ def test_the_cells(self):
                         t4_reading(AirSpace, rate, channels, 1, time_ms,
                                    feedback), 0.6)
 
+    def test_a_short_time_with_high_feedback_is_a_flutter(self):
+        # The card's Limits sentence, the other side of the cells above:
+        # at Time 20 to 60 ms and Feedback 0.85 the repeats keep their
+        # rhythm (the reading stays above 0.6) instead of dissolving into
+        # the chamber.
+        for time_ms in (20.0, 40.0, 60.0):
+            with self.subTest(time_ms=time_ms):
+                self.assertGreater(
+                    t4_reading(AirSpace, 48000, 2, 1, time_ms, 0.85), 0.6)
+
     def test_red_on_bare_repeats(self):
         self.assertGreater(t4_reading(plants.BareRepeats, 48000, 2, 1,
                                       200.0, 0.6), 0.6)
@@ -561,6 +571,113 @@ def test_red_on_a_wire(self):
                         40.0)
 
 
+# --------------------------------------------------------------------------
+# The loop's filter (the Limits sentence on 6 dB per octave)
+
+
+def tape_feed(effect, data, rate, channels):
+    """Re-point the tape at `data`, so the tape alone can be read: the
+    chamber and the dry are out of the picture, and what is read is what
+    the class handed the tape."""
+    effect._fd.play(Feed(data, rate, channels))
+
+
+def tape_render(effect, frames):
+    out = array("h")
+    while len(out) < frames * effect.channel_count:
+        _, data = audiocore.get_buffer(effect._fd)
+        out.extend(array("h", bytes(data)))
+    return out[:frames * effect.channel_count]
+
+
+def loop_gain_db(hz, loop_top=1000.0, rate=48000, channels=2):
+    """What one lap of the loop does to a tone of `hz`, in dB: the third
+    repeat's level over the second's, whole periods, at Time 100 ms,
+    Feedback 0.85 and Loop Bass at its lowest. It is the Feedback and the
+    loop's filter at `hz`."""
+    time_frames = law_frames(100.0, rate)
+    on = law_frames(20.0, rate)
+    data = tone(hz, on, rate, channels, 20000.0) + array(
+        "h", bytes(2 * channels * 4 * time_frames))
+    effect = build(AirSpace, data, rate, channels, time_ms=100.0,
+                   feedback=0.85, drive=0.0, loop_top_hz=loop_top,
+                   loop_bass_hz=20.0)
+    tape_feed(effect, data, rate, channels)
+    x = mono(tape_render(effect, 4 * time_frames), channels)
+    effect.deinit()
+    period = int(round(rate / hz))
+    length = (480 // period) * period
+    levels = []
+    for repeat in (2, 3):
+        start = repeat * time_frames + 240
+        window = x[start:start + length]
+        levels.append(sum(v * v for v in window) / len(window))
+    return db_ratio(levels[1], levels[0])
+
+
+class TheLoopFilter(unittest.TestCase):
+
+    FREQS = (250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0)
+
+    def test_it_falls_6_db_per_octave(self):
+        # Two octaves above the corner a one-pole falls 12.3 dB, three
+        # 18.1: 5.8 dB between them; a two-pole falls 12.
+        gain = {hz: loop_gain_db(hz) for hz in (4000.0, 8000.0)}
+        octave = gain[4000.0] - gain[8000.0]
+        self.assertGreater(octave, 4.5)
+        self.assertLess(octave, 7.5)
+
+    def test_it_has_no_bell_and_no_presence_peak(self):
+        # The feedback alone is 20 log10 0.85 = -1.41 dB a lap; a bell or
+        # a presence boost would read above it, and the response never
+        # rises with frequency.
+        feedback_db = 20.0 * math.log10(0.85)
+        gains = [loop_gain_db(hz) for hz in self.FREQS]
+        for hz, gain in zip(self.FREQS, gains):
+            with self.subTest(hz=hz):
+                self.assertLessEqual(gain, feedback_db + 0.1)
+        for low, high in zip(gains, gains[1:]):
+            self.assertLessEqual(high, low + 0.1)
+
+    def test_the_top_cuts_is_steeper(self):
+        # The Top Cut is a biquad on the send: read alone, it falls faster
+        # per octave than the loop's one-pole does.
+        rate, channels = 48000, 2
+        levels = {}
+        for hz in (4000.0, 8000.0):
+            data = tone(hz, rate, rate, channels, 8000.0)
+            effect = build(AirSpace, data, rate, channels, top_cut_hz=1000.0)
+            effect._lp.play(Feed(data, rate, channels))
+            out = array("h")
+            while len(out) < rate * channels:
+                _, block = audiocore.get_buffer(effect._lp)
+                out.extend(array("h", bytes(block)))
+            x = mono(out, channels)[24000:24000 + 4800]
+            effect.deinit()
+            levels[hz] = sum(v * v for v in x) / len(x)
+        self.assertGreater(db_ratio(levels[4000.0], levels[8000.0]), 9.0)
+
+    def test_a_held_tone_comes_back_at_its_own_pitch(self):
+        # No wow: with Time held, the repeats are the tone, delayed. Their
+        # energy sits in the tone's bin, not in sidebands.
+        rate, channels = 48000, 2
+        data = tone(1000.0, 3 * rate, rate, channels, 8000.0)
+        effect = build(AirSpace, data, rate, channels, feedback=0.5,
+                       drive=0.0)
+        tape_feed(effect, data, rate, channels)
+        x = mono(tape_render(effect, 2 * rate + 4800), channels)
+        effect.deinit()
+        # Late enough that every repeat's onset has died away.
+        window = x[2 * rate:2 * rate + 4800]
+        w = 2.0 * math.pi * 1000.0 / rate
+        re = sum(v * math.cos(w * i) for i, v in enumerate(window))
+        im = sum(v * math.sin(w * i) for i, v in enumerate(window))
+        energy = sum(v * v for v in window)
+        self.assertGreater(energy, 0.0)
+        self.assertGreater(
+            2.0 * (re * re + im * im) / (len(window) * energy), 0.9999)
+
+
 # --------------------------------------------------------------------------
 # The surface
 
@@ -728,6 +845,52 @@ def test_a_fresh_instance_reads_patch_0_and_plays_the_defaults(self):
             self.assertEqual(effect.macro(index), value)
         effect.deinit()
 
+    def test_a_constructor_value_on_a_defaults_step_plays_as_given(self):
+        # 112.08 ms is the grid step 68, which is also the step of the
+        # default 111 ms: it plays 112.08, not 111, until it is moved.
+        value = law_value(TIME_I, 68)
+        self.assertNotEqual(value, CARD_DEFAULTS[TIME_I])
+        effect = fresh(time_ms=value)
+        self.assertAlmostEqual(effect.macro(TIME_I), value, places=9)
+        self.assertEqual(effect._handed["delay_frames"],
+                         law_frames(value, 48000))
+        # A host echoing `get_macro` back does not move it.
+        effect.set_macro(TIME_I, effect.get_macro(TIME_I))
+        self.assertAlmostEqual(effect.macro(TIME_I), value, places=9)
+        # A whole step that arrives plays the default there: set_macro,
+        # a patch, and reset.
+        effect.set_macro(TIME_I, 70)
+        effect.set_macro(TIME_I, 68)
+        self.assertEqual(effect.macro(TIME_I), 111.0)
+        for arrive in (lambda: effect.program_change(0), effect.reset):
+            effect.set_macro(TIME_I, 67.5)
+            effect.set_macro(TIME_I, 68.5)
+            self.assertNotEqual(effect.macro(TIME_I), 111.0)
+            effect.set_macro(TIME_I, 70)
+            arrive()
+            self.assertEqual(effect.macro(TIME_I), 111.0)
+        effect.deinit()
+
+    def test_the_other_defaults_play_as_given_too(self):
+        for index in range(11):
+            if index == MIX_I:
+                continue
+            step = AirSpace.PATCHES[0][1][index]
+            value = law_value(index, step)
+            if value == CARD_DEFAULTS[index]:
+                continue
+            with self.subTest(index=index):
+                options = dict(zip(
+                    ("time_ms", "feedback", "glide_ms", "drive",
+                     "loop_top_hz", "loop_bass_hz", "top_cut_hz",
+                     "low_cut_hz", "decay", "damping_hz", "mix"),
+                    (value if i == index else CARD_DEFAULTS[i]
+                     for i in range(11))))
+                effect = fresh(**options)
+                self.assertAlmostEqual(effect.macro(index), value,
+                                       delta=abs(value) * 1e-12)
+                effect.deinit()
+
     def test_fixed_size_no_sync_and_mono_in_mono_out(self):
         self.assertNotIn("Size", AirSpace.MACRO_LABELS)
         self.assertEqual(AirSpace.CAPABILITIES, ())
@@ -750,13 +913,30 @@ def test_at_least_20_ms_before_the_chamber(self):
         self.assertFalse(any(out))
 
 
-def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0):
-    """The longest run of frames at the rail, on a 50 Hz sine at `dbfs`
-    (the kit's ceiling material that rails first)."""
+def square(hz, frames, rate, channels, peak):
+    """A square at `peak`, its half period `rate / (2 hz)` frames."""
+    half = int(round(rate / (2.0 * hz)))
+    out = array("h", bytes(2 * frames * channels))
+    for n in range(frames):
+        v = int(round(peak)) if (n // half) % 2 == 0 else -int(round(peak))
+        for c in range(channels):
+            out[n * channels + c] = v
+    return out
+
+
+def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0,
+             macros=(), **options):
+    """The longest run of frames at the rail, on a 100 Hz square at `dbfs`
+    (the material the kit's ceiling check rails first on, here at Mix 1,
+    where the dry and the chamber are both at unity). `macros` is a tuple of
+    (index, MIDI) taken after the patch."""
     frames = int(seconds * rate)
     peak = 32767.0 * 10.0 ** (dbfs / 20.0)
-    data = tone(50.0, frames, rate, channels, peak)
-    effect = build(cls, data, rate, channels, patch)
+    data = square(100.0, frames, rate, channels, peak)
+    effect = build(cls, data, rate, channels, patch, **options)
+    effect.set_macro(MIX_I, 64)
+    for index, midi in macros:
+        effect.set_macro(index, midi)
     out = render(effect, frames)
     effect.deinit()
     if not any(out[-rate * channels:]):
@@ -773,15 +953,34 @@ def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0):
 
 class TheInputCeiling(unittest.TestCase):
 
-    def test_minus_6_dbfs_reaches_no_rail(self):
-        self.assertEqual(AirSpace.INPUT_CEILING_DBFS, -6.0)
+    def test_the_ceiling_is_minus_12_dbfs(self):
+        self.assertEqual(AirSpace.INPUT_CEILING_DBFS, -12.0)
+
+    def test_minus_12_dbfs_reaches_no_rail_at_mix_1_on_every_patch(self):
+        ceiling = AirSpace.INPUT_CEILING_DBFS
         for rate, channels in ((48000, 2), (22050, 1)):
             for patch in sorted(AirSpace.PATCHES):
                 with self.subTest(rate=rate, channels=channels, patch=patch):
                     self.assertLessEqual(
-                        rail_run(AirSpace, rate, channels, -6.0, patch), 8)
+                        rail_run(AirSpace, rate, channels, ceiling, patch), 8)
 
-    def test_full_scale_does(self):
+    def test_minus_12_dbfs_reaches_no_rail_with_each_macro_at_its_stops(self):
+        ceiling = AirSpace.INPUT_CEILING_DBFS
+        for index in range(11):
+            if index == MIX_I:
+                continue
+            for midi in (0, 127):
+                with self.subTest(macro=index, midi=midi):
+                    self.assertLessEqual(
+                        rail_run(AirSpace, 48000, 2, ceiling,
+                                 macros=((index, midi),)), 8)
+
+    def test_a_hotter_input_does(self):
+        # The old ceiling: at Mix 1 with Feedback 0.85 a -6 dBFS square
+        # rails, and so does full scale on the defaults.
+        self.assertGreater(
+            rail_run(AirSpace, 48000, 2, -6.0,
+                     macros=((FEEDBACK_I, 127),)), 8)
         self.assertGreater(rail_run(AirSpace, 48000, 2, 0.0), 8)
 
 
@@ -909,23 +1108,83 @@ def moves_render(data, rate, channels, pulls, actions, hidden):
     return out
 
 
+#: The scenarios the two wirings must render alike, by name: a pull index
+#: maps to what the host does before that pull.
+SCENARIOS = {
+    "mix 0 before the first pull, reset at 4": {
+        0: lambda e: e.set_macro(MIX_I, 0), 4: lambda e: e.reset()},
+    "reset before the first pull": {0: lambda e: e.reset()},
+    "reset twice before the first pull": {
+        0: lambda e: (e.reset(), e.reset())},
+    "mix 0 before the first pull, patch 1 at 4": {
+        0: lambda e: e.set_macro(MIX_I, 0),
+        4: lambda e: e.program_change(1)},
+    "mix 0 before the first pull, back at 4": {
+        0: lambda e: e.set_macro(MIX_I, 0),
+        4: lambda e: e.set_macro(MIX_I, 22)},
+    "mix 0 and back mid-stream": {
+        10: lambda e: e.set_macro(MIX_I, 0),
+        14: lambda e: e.set_macro(MIX_I, 22)},
+    "reset twice mid-stream": {10: lambda e: (e.reset(), e.reset())},
+    "untouched": {},
+}
+
+#: sha1 of `moves_render` at 48 kHz stereo, 40 pulls, LCG noise at 4000 rms
+#: seed 11, with `get_buffer` present, per scenario in the order above:
+#: what the class rendered before `_replay` was taken out (07bf68a).
+GET_BUFFER_RENDERS = (
+    "c80ffad8df5fe4a5ae16ec41c51517575377f23c",
+    "2b4ab24f79b4dfd68f815bdff5f0e5b7e152e055",
+    "2b4ab24f79b4dfd68f815bdff5f0e5b7e152e055",
+    "7e03a853d8fddfa0fbc4b9f7efe034611c2fadd9",
+    "c80ffad8df5fe4a5ae16ec41c51517575377f23c",
+    "bc5deee2233815d6a61d8db1db2700ac1f5b5676",
+    "ae7ef874a87e15d9bbc1d6800aaa48015969c45e",
+    "2b4ab24f79b4dfd68f815bdff5f0e5b7e152e055",
+)
+
+
 class WithoutGetBuffer(unittest.TestCase):
-    """A board's own audiocore has no `get_buffer`, so the voices prime
-    the source's first block at construction instead of a block of zeros
-    (the class's `_wire` and `_replay`)."""
+    """A board's own audiocore has no `get_buffer`, and the class then
+    pulls its mixer through a one-voice mixer of its own (`_pull`): wired
+    either way, no voice holds a block, and the renders are the same bytes."""
+
+    def noise(self, rate, channels):
+        return lcg_noise(rate, channels, 4000.0, 11)
 
-    def test_mix_zero_and_back_mid_stream_renders_the_same(self):
+    def test_every_scenario_renders_the_same_bytes(self):
+        rate = 48000
+        for channels in (2, 1):
+            data = self.noise(rate, channels)
+            for name, actions in SCENARIOS.items():
+                with self.subTest(channels=channels, scenario=name):
+                    want = moves_render(data, rate, channels, 40, actions,
+                                        False)
+                    got = moves_render(data, rate, channels, 40, actions,
+                                       True)
+                    self.assertEqual(got, want)
+
+    def test_a_single_block_before_the_first_pull_renders_the_same_bytes(
+            self):
+        rate = 48000
+        for channels in (2, 1):
+            data = burst(BLOCK, rate, channels, 8000.0, 12)
+            for name in list(SCENARIOS)[:5]:
+                with self.subTest(channels=channels, scenario=name):
+                    actions = SCENARIOS[name]
+                    want = moves_render(data, rate, channels, 40, actions,
+                                        False)
+                    got = moves_render(data, rate, channels, 40, actions,
+                                       True)
+                    self.assertEqual(got, want)
+
+    def test_mix_zero_and_back_mid_stream_from_the_first_block(self):
         rate, channels = 48000, 2
-        data = lcg_noise(rate, channels, 4000.0, 11)
-        actions = {10: lambda e: e.set_macro(MIX_I, 0),
-                   14: lambda e: e.set_macro(MIX_I, 22)}
+        data = self.noise(rate, channels)
+        actions = SCENARIOS["mix 0 and back mid-stream"]
         want = moves_render(data, rate, channels, 120, actions, False)
         got = moves_render(data, rate, channels, 120, actions, True)
-        # The first block differs by design: without `get_buffer` the level
-        # gates cannot be opened ahead (`open_level_gates`), so the voices
-        # wait for the first zero crossing, as upstream's do.
-        skip = BLOCK * channels
-        self.assertEqual(got[skip:], want[skip:])
+        self.assertEqual(got, want)
 
     def test_no_stale_block_after_mix_zero_before_the_first_pull(self):
         rate, channels = 48000, 2
@@ -935,18 +1194,30 @@ def test_no_stale_block_after_mix_zero_before_the_first_pull(self):
         out = moves_render(data, rate, channels, 60, actions, True)
         self.assertFalse(any(out[4 * BLOCK * channels:]))
 
-    def test_red_without_the_replay(self):
+    def test_with_get_buffer_the_renders_are_unchanged(self):
+        import hashlib
         rate, channels = 48000, 2
-        data = burst(BLOCK, rate, channels, 8000.0, 12)
-        actions = {0: lambda e: e.set_macro(MIX_I, 0),
-                   4: lambda e: e.set_macro(MIX_I, 22)}
-        replay = AirSpace._replay
-        AirSpace._replay = lambda self: None
-        try:
-            out = moves_render(data, rate, channels, 60, actions, True)
-        finally:
-            AirSpace._replay = replay
-        self.assertTrue(any(out[4 * BLOCK * channels:]))
+        data = self.noise(rate, channels)
+        for (name, actions), want in zip(SCENARIOS.items(),
+                                         GET_BUFFER_RENDERS):
+            with self.subTest(scenario=name):
+                out = moves_render(data, rate, channels, 40, actions, False)
+                self.assertEqual(hashlib.sha1(bytes(out)).hexdigest(), want)
+
+    def test_red_when_the_wiring_pulls_nothing(self):
+        class NoPull(AirSpace):
+            def _pull(self):
+                pass
+
+        rate, channels = 48000, 2
+        data = self.noise(rate, channels)
+        actions = SCENARIOS["mix 0 before the first pull, back at 4"]
+        want = moves_render(data, rate, channels, 40, actions, False)
+        with HiddenGetBuffer():
+            effect = build(NoPull, data, rate, channels)
+            got = render(effect, 40 * BLOCK, actions)
+        effect.deinit()
+        self.assertNotEqual(got, want)
 
 
 # --------------------------------------------------------------------------
@@ -994,10 +1265,15 @@ def test_red_without_the_replay(self):
      "takes, so it sets how far they bend: 12 % at the default of 4 s.",
      ("TheSurface.test_the_glide_law",
       "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide")),
-    ("Keep your input at or under -6 dBFS: the dry is at unity and the "
-     "chamber adds to it, so a hotter input can reach the rail.",
-     ("TheInputCeiling.test_minus_6_dbfs_reaches_no_rail",
-      "TheInputCeiling.test_full_scale_does")),
+    ("Keep your input at or under -12 dBFS: at Mix 1 the dry and the "
+     "chamber are both at unity and add, so a hotter input can reach the "
+     "rail.",
+     ("TheInputCeiling.test_the_ceiling_is_minus_12_dbfs",
+      "TheInputCeiling.test_minus_12_dbfs_reaches_no_rail_at_mix_1_on_every_"
+      "patch",
+      "TheInputCeiling.test_minus_12_dbfs_reaches_no_rail_with_each_macro_at_"
+      "its_stops",
+      "TheInputCeiling.test_a_hotter_input_does")),
     ("Latency is zero.", "TheSurface.test_latency_is_zero"),
     ("`reset()` empties the tape and the chamber and restores patch 0, "
      "whose Time of 111 ms lands at once instead of gliding.",
@@ -1022,6 +1298,15 @@ def test_red_without_the_replay(self):
      "the stretch comes with Feedback above about 0.6 or a long Time.",
      ("T3FeedbackLengthensTheTail.test_the_default_adds_only_a_little",
       "T3FeedbackLengthensTheTail.test_the_bars")),
+    ("At a short Time with high Feedback the repeats are heard as a flutter, "
+     "not a longer chamber.",
+     "T4HeardAsAChamber.test_a_short_time_with_high_feedback_is_a_flutter"),
+    ("The loop's filters are gentle, 6 dB per octave, and the Top Cut's is "
+     "steeper: there is no loop bell, no presence EQ and no wow.",
+     ("TheLoopFilter.test_it_falls_6_db_per_octave",
+      "TheLoopFilter.test_the_top_cuts_is_steeper",
+      "TheLoopFilter.test_it_has_no_bell_and_no_presence_peak",
+      "TheLoopFilter.test_a_held_tone_comes_back_at_its_own_pitch")),
     ("There is always at least 20 ms between the dry and the chamber.",
      ("TheSurface.test_at_least_20_ms_before_the_chamber",
       "T1DryIsUntouched.test_the_times_and_the_hardest_settings")),

From c211db1c6761dd62d279ed561e13e8ca8669ab01 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:07:49 -0500
Subject: [PATCH 44/76] PitchShifter: levels set before the first pull hold
 from frame 0, the CircuitPython splice and the Feedback stacking are in the
 docstring

---
 lib/audioeffects/rebuilt/pitchshifter.py   | 21 ++++++-
 tests/support/kit_common.py                | 13 ++++-
 tests/support/lifecycle.py                 | 11 ++++
 tests/test_cpython_effects_pitchshifter.py | 64 ++++++++++++++++++++++
 4 files changed, 105 insertions(+), 4 deletions(-)

diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
index 3ebe4ca..39a30e0 100644
--- a/lib/audioeffects/rebuilt/pitchshifter.py
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -127,6 +127,8 @@ class PitchShifter(_component.Component):
     At unity it sits still, 1.3 ms late, from a fresh start, a reset or a
     return from Mix 0; after a Pitch move it sits wherever the splice left
     it, up to one window and 1.3 ms late.
+    On CircuitPython's own pitch shifter a reset or a return from Mix 0 does
+    not restart the splice, so there it sits wherever the splice was.
     Shifting down drops slices of what you play; shifting up repeats them.
     The window is 30 ms unless you pass `window_ms`, 15 to 60, when you
     build it: a longer window splices less often and arrives later.
@@ -134,6 +136,8 @@ class PitchShifter(_component.Component):
     **The dry.** Up to Mix 1 your dry signal passes untouched, sample for
     sample, with the shifted voice added on top, so a hot input can reach
     the rail.
+    Feedback stacks level too, far past the input: at Feedback 127, Delay 0
+    and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail.
 
     **Mono, latency, tail.** A one-channel source gets a one-channel
     shifter with the same window.
@@ -210,6 +214,10 @@ def _build(self, pitch=7.0, fine=0.0, mix=1.0, delay_ms=0.0,
         self._overlap = crossfade_frames(rate)
         self._ready = False
         self._wired = False
+        #: Whether the host has asked for the output yet. Until it has,
+        #: nothing has been pulled, and a control that moves a voice's
+        #: level re-arms the graph so the level holds from frame 0.
+        self._taken = False
         #: Whether the loop's splicer has run since its line was last
         #: emptied: it then reads half a window later (`_loop_frames`).
         self._engaged = False
@@ -454,12 +462,23 @@ def _route(self):
             return
         if not self._wired:
             self._wire()
-        elif self._rejoin():
+        elif self._rejoin() or not self._taken:
+            # Not pulled yet: a level moved now would wait for its voice's
+            # next zero crossing, a block of the old level, where an
+            # instance built at this setting plays the new one from frame 0.
             self._rearm()
         else:
             self._levels()
         self._output = self._tail
 
+    @property
+    def output(self):
+        """The node the host plays. Asking for it is the host's first step
+        to pulling, so from here a level that moves is an ordinary move."""
+        self._check_live()
+        self._taken = True
+        return self._output
+
     def reset(self):
         """Empty the shifter and both lines, return to patch 0, and play
         from there as a new instance does."""
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 0e3baf3..b70b861 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -33,15 +33,22 @@
 
 # PitchShifter at Feedback's top: the repeats stack on the dry, up to 21
 # times the input's peak on a DC, so the rail is reachable below any useful
-# ceiling; the docstring says a hot input can reach it. The square, sine and
-# DC cells there, at every rate and channel count.
+# ceiling. The docstring says so ("Feedback stacks level too, far past the
+# input: at Feedback 127, Delay 0 and Mix 2 a noise burst peaking at
+# -10.3 dBFS reaches the rail"), and test_feedback_near_its_top_stacks_
+# level_far_past_the_input holds it. The square, sine and DC cells there, at
+# every rate and channel count.
 for _material in ("square", "sine", "dc"):
     for _rate in RATES:
         for _channels in CHANNELS:
             DECLARED[("PitchShifter", "ceiling", "%s/%d/%d/m4=127" % (
                 _material, _rate, _channels))] = (
                 "Feedback 0.95 stacks repeats on the dry, up to 21 times the"
-                " input's peak: a hot input reaches the rail by design")
+                " input's peak: the class docstring says Feedback stacks"
+                " level far past the input, a -10.3 dBFS noise burst"
+                " reaching the rail at Feedback 127, Delay 0 and Mix 2"
+                " (test_feedback_near_its_top_stacks_level_far_past_the_"
+                "input)")
 
 CPYTHON = sys.implementation.name == "cpython"
 
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 3303823..277d840 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -113,6 +113,17 @@
     ("PitchShifter", "E10-mix0", "P4"):
         "CircuitPython only: as E10-reset, the return from Mix 0 empties the"
         " lines but CircuitPython's PitchShift keeps its positions",
+    ("PitchShifter", "E10-macros", "P4"):
+        "CircuitPython only: a macro moved before the first pull re-arms the"
+        " graph so its voice levels hold from frame 0, and the re-arm's"
+        " priming pulls move CircuitPython's own PitchShift off the"
+        " control's splice phase (it keeps its positions through a clear);"
+        " CPython and MicroPython are ok (ruled a CircuitPython-own"
+        " difference)",
+    ("PitchShifter", "E10-patch", "P4"):
+        "CircuitPython only: as E10-macros, a patch loaded before the first"
+        " pull is re-armed, and CircuitPython's PitchShift keeps its"
+        " positions",
     ("PitchShifter", "E4-m2=", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step (Mix)",
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
index 4cc9c34..eea0b18 100644
--- a/tests/test_cpython_effects_pitchshifter.py
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -771,6 +771,26 @@ def test_a_hot_input_reaches_the_rail_at_mix_1(self):
         self.assertEqual(max(out), 32767)
         self.assertEqual(min(out), -32768)
 
+    def test_feedback_near_its_top_stacks_level_far_past_the_input(self):
+        # A noise burst peaking at -10.3 dBFS (10000 of 32768), through
+        # Feedback 127 with Delay 0 and Mix 2, an octave up: the repeats
+        # pile up on each other and the shifted voice alone reaches the
+        # rail.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            burst = rate // 10
+            values = array("h", bytes(2 * burst * channels))
+            state = 12345
+            for i in range(burst * channels):
+                state = (state * 1103515245 + 12345) & 0x7FFFFFFF
+                values[i] = (state >> 8) % 20001 - 10000
+            frames = 3 * rate
+            padded = values + array("h", bytes(2 * (frames - burst)
+                                               * channels))
+            out = render(PitchShifter, padded, rate, channels, frames,
+                         pitch=12.0, mix=2.0, delay_ms=0.0, feedback=0.95)
+            self.assertTrue(max(out) == 32767 or min(out) == -32768,
+                            (rate, channels, max(out), min(out)))
+
     def test_a_mono_source_is_one_channel_of_a_stereo_one(self):
         for rate in RATES:
             for options in ({}, dict(patch=4), dict(patch=5, window_ms=15.0),
@@ -960,6 +980,42 @@ def test_a_return_from_mix_0_is_a_fresh_instance_at_that_mix(self):
                 self.assertEqual(got[18 * BLOCK * channels:], fresh,
                                  (rate, channels, name))
 
+    def test_a_level_set_before_the_first_pull_plays_from_the_first_frame(
+            self):
+        # A patch or a Mix move before anything has been pulled: the voices
+        # start at the new level, not a block at the old one, byte for byte
+        # what an instance built at that setting plays. A DC input shows a
+        # dry that waited for a zero crossing; the 40 Hz sine one that
+        # crossed late.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            frames = 40 * BLOCK
+            dc = array("h", [6000] * (frames * channels))
+            slow = sine(frames, 40.0, rate, 12000, channels, phase=0.3)
+            for name, values in (("dc", dc), ("40 Hz", slow)):
+                for patch in range(len(PitchShifter.PATCHES)):
+                    got = played(values, rate, channels, 40,
+                                 {0: lambda e, p=patch: e.program_change(p)})
+                    fresh = render(PitchShifter, values, rate, channels,
+                                   frames, patch=patch)
+                    self.assertEqual(got, fresh, (rate, channels, name,
+                                                  "patch", patch))
+                for midi in (0, 1, 32, 63, 64, 65, 96, 126, 127):
+                    mix = _component.macro_value(
+                        (0.0, 2.0), _component.position_of_midi(
+                            "BIPOLAR", midi))
+                    got = played(values, rate, channels, 40,
+                                 {0: lambda e, m=midi: e.set_macro(MIX_I, m)})
+                    fresh = render(PitchShifter, values, rate, channels,
+                                   frames, mix=mix)
+                    self.assertEqual(got, fresh, (rate, channels, name,
+                                                  "mix", midi))
+                got = played(values, rate, channels, 40,
+                             {0: lambda e: (e.reset(), e.program_change(6))})
+                fresh = render(PitchShifter, values, rate, channels, frames,
+                               patch=6)
+                self.assertEqual(got, fresh, (rate, channels, name,
+                                              "reset, patch 6"))
+
     def test_mix_0_and_a_patch_together_is_a_fresh_instance_at_that_patch(
             self):
         for rate, channels in ((48000, 2), (22050, 1)):
@@ -1106,6 +1162,11 @@ def test_dry_through_shifter_is_red(self):
       "test_a_return_from_mix_0_is_a_fresh_instance_at_that_mix",
       "test_the_voice_at_unity_after_a_pitch_move_sits_where_the_splice_"
       "left_it")),
+    ("On CircuitPython's own pitch shifter a reset or a return from Mix 0 "
+     "does not restart the splice, so there it sits wherever the splice "
+     "was.",
+     ("DECLARED:PitchShifter,E10-reset,P4",
+      "DECLARED:PitchShifter,E10-mix0,P4")),
     ("The window is 30 ms unless you pass `window_ms`, 15 to 60, when you "
      "build it: a longer window splices less often and arrives later.",
      ("test_window_ms_is_set_at_construction",
@@ -1114,6 +1175,9 @@ def test_dry_through_shifter_is_red(self):
      "the shifted voice added on top, so a hot input can reach the rail.",
      ("test_the_dry_is_untouched", "test_dry_through_shifter_is_red",
       "test_a_hot_input_reaches_the_rail_at_mix_1")),
+    ("Feedback stacks level too, far past the input: at Feedback 127, Delay "
+     "0 and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail.",
+     "test_feedback_near_its_top_stacks_level_far_past_the_input"),
     ("A one-channel source gets a one-channel shifter with the same window.",
      "test_a_mono_source_is_one_channel_of_a_stereo_one"),
     ("Latency is zero samples: the dry is never delayed.",

From bc0559d1e5dfcdb6f14ebb21f445624234267101 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:10:43 -0500
Subject: [PATCH 45/76] ShimmerHall tests: read the 48 kHz traits off a stereo
 render's left channel, as the card does

---
 tests/test_cpython_effects_shimmerhall.py | 25 +++++++++++++++--------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 89c0cec..d6403ad 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -15,7 +15,8 @@
 a 2000 LSB peak, after an offset of 0 to 255 frames. A seed set draws f0
 (165 to 330 Hz) and the offset from this module's own integer generator,
 so every interpreter makes the same bytes. Bands are Goertzel sums over
-Hann frames, 1024 frames at 48 kHz and 512 at 22.05 kHz.
+Hann frames, 1024 frames at 48 kHz and 512 at 22.05 kHz, on the left
+channel of a stereo render at 48 kHz and a mono one at 22.05 kHz.
 
 The unit tests run a share of each trait's cells; `figures()` runs every
 cell the card names, eight seed sets each, and prints the evidence pack's
@@ -193,6 +194,12 @@ def db(power):
     return 10.0 * math.log(power) / math.log(10.0)
 
 
+def card_channels(rate):
+    """The card's material: stereo at 48 kHz (the left channel read), mono
+    at 22.05 kHz."""
+    return 2 if rate >= 44100 else 1
+
+
 def wet(cls, rate, channels, f0, offset, frames, **options):
     """Left channel of a Mix 2 render of the burst."""
     options.setdefault("mix", 2.0)
@@ -285,8 +292,8 @@ def _dry_source(self):
 
 def t1_onset(cls, rate, f0, offset, bloom):
     frames = law_frames(bloom + 400.0, rate) + offset
-    s1 = wet(cls, rate, 1, f0, offset, frames, bloom_ms=bloom, shimmer=1.0)
-    s0 = wet(cls, rate, 1, f0, offset, frames, bloom_ms=bloom, shimmer=0.0)
+    s1 = wet(cls, rate, card_channels(rate), f0, offset, frames, bloom_ms=bloom, shimmer=1.0)
+    s0 = wet(cls, rate, card_channels(rate), f0, offset, frames, bloom_ms=bloom, shimmer=0.0)
     hz = 2.0 * f0
     size = hann_size(rate)
     window = hann(size)
@@ -339,8 +346,8 @@ def t2_read(cls, rate, character, interval, seed):
     span = law_frames(500.0, rate)
     frames = start + span
     options = dict(character=character, interval=interval, rise=0.0)
-    s1 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, **options)
-    s0 = wet(cls, rate, 1, f0, offset, frames, shimmer=0.0, **options)
+    s1 = wet(cls, rate, card_channels(rate), f0, offset, frames, shimmer=1.0, **options)
+    s0 = wet(cls, rate, card_channels(rate), f0, offset, frames, shimmer=0.0, **options)
     d = [s1[n] - s0[n] for n in range(frames)]
     size = 2048 if rate >= 44100 else 1024
     window = hann(size)
@@ -383,10 +390,10 @@ def t3_read(cls, rate, bloom, seed):
     frames = law_frames(100.0 + 6 * bloom + 600.0, rate) + offset
     options = dict(character="rise", bloom_ms=bloom, damping_hz=16000.0,
                    decay=4.0, interval=12)
-    s0 = wet(cls, rate, 1, f0, offset, frames, shimmer=0.0, **options)
-    r0 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, rise=0.0,
+    s0 = wet(cls, rate, card_channels(rate), f0, offset, frames, shimmer=0.0, **options)
+    r0 = wet(cls, rate, card_channels(rate), f0, offset, frames, shimmer=1.0, rise=0.0,
              **options)
-    r9 = wet(cls, rate, 1, f0, offset, frames, shimmer=1.0, rise=0.9,
+    r9 = wet(cls, rate, card_channels(rate), f0, offset, frames, shimmer=1.0, rise=0.9,
              **options)
     hop = 256
     onsets = [t3_onset(band_track(r0, 2.0 * f0, rate, hop),
@@ -425,7 +432,7 @@ def band_peak(values, hz, rate):
 
 def t45_render(cls, rate, f0, offset, character, rise, damping):
     frames = law_frames(100.0 + 200.0 * 6 + 400.0, rate) + offset
-    return wet(cls, rate, 1, f0, offset, frames, character=character,
+    return wet(cls, rate, card_channels(rate), f0, offset, frames, character=character,
                shimmer=1.0, rise=rise, damping_hz=damping, bloom_ms=200.0,
                interval=12)
 

From 970e5f53db0d8b3c2fa79c5e1c21a73d04cd0420 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:21:14 -0500
Subject: [PATCH 46/76] ShimmerHall tests: read the left channel without a
 slice step, for MicroPython

---
 tests/test_cpython_effects_shimmerhall.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index d6403ad..9167db7 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -149,7 +149,8 @@ def left(out, channels):
     """The left channel (the only one, in mono)."""
     if channels == 1:
         return out
-    return out[0::2]
+    # A loop, not out[0::2]: MicroPython's array takes no slice step.
+    return [out[n] for n in range(0, len(out), 2)]
 
 
 def hann_size(rate):

From d69b0560b100000f347f75ba4cea4c48f20fe454 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:21:40 -0500
Subject: [PATCH 47/76] Octaver: dividers clock on ticks under Sensitivity, so
 a fading note never plays itself; ceiling -15 dBFS; Sensitivity and ranges
 stated at their level

The comparator reads +-2 LSB from 18 dB under Sensitivity, the dividers turn
over on that, and a gate after each takes it back out: a clock whose peaks are
unequal no longer crosses one rail only and passes the note. A4 at patch 0
now divides cleanly, so the drop-out disclosure goes. The peak gain is 5.03
(a square near E2, Tracking 40 Hz), so the ceiling moves to -15 dBFS.
---
 lib/audioeffects/rebuilt/octaver.py   | 103 ++++++++----
 tests/test_cpython_effects_octaver.py | 222 ++++++++++++++++++++------
 2 files changed, 248 insertions(+), 77 deletions(-)

diff --git a/lib/audioeffects/rebuilt/octaver.py b/lib/audioeffects/rebuilt/octaver.py
index de515c5..4a3990e 100644
--- a/lib/audioeffects/rebuilt/octaver.py
+++ b/lib/audioeffects/rebuilt/octaver.py
@@ -30,11 +30,22 @@
 DEFAULTS = (1.0, 0.7, 0.0, 90.0, 324.0, 70.3, -80.0)
 
 #: The comparator's table: 4097 points over the shaper's -1..1, exact zero
-#: across |i - 2048| <= 63 and the rails beyond. Interpolating between two
-#: points of a one-point step is a gain stage, which leaks an octave up and
-#: DC below Sensitivity; a dead band many points wide reads exact zero.
+#: across |i - 2048| <= 7, a tick of +-TICK out to |i - 2048| = 63, and the
+#: rails beyond. Interpolating between two points of a one-point step is a
+#: gain stage, which leaks an octave up and DC below Sensitivity; a dead band
+#: many points wide reads exact zero.
+#:
+#: The rails are Sensitivity: only they reach the octave. The ticks clock the
+#: dividers 18 dB under it, so a clock whose peaks are unequal (a second
+#: harmonic the tracking low-pass left, or the last few LSB of a quiet one)
+#: has crossed both sides by the time either side reaches a rail. Clocked on
+#: the rails alone, such a clock crossed one rail and not the other: the
+#: divider never turned over, and the signal times its one-sided pulses was
+#: the dry note itself.
 CURVE_POINTS = 4097
 DEAD_HALF = 63
+TICK_HALF = 7
+TICK = 2
 #: The comparator reaches the rail where its input times `pre_gain` is
 #: 64/2048, so `pre_gain = EDGE / 10^(Sensitivity/20)` puts the rail at the
 #: clock's level of Sensitivity. 1/32 is exact in every float format.
@@ -45,15 +56,21 @@
 CLOCK_Q = 0.5
 TONE_Q = 0.7071
 
-#: The divider of the clock leg: a +-1 square from the comparator's +-rail.
-CLOCK_THRESHOLD = 0.5
+#: The dividers turn over on the comparator's ticks: one LSB, under TICK.
+CLOCK_THRESHOLD = 1.0 / 32768.0
 CLOCK_HOLD_MS = 1.0
 
+#: The table after each divider: the identity, with exact zero for
+#: |x| < 16 LSB, which takes the ticks out of the square and leaves its rails
+#: as they are.
+GATE_HALF = 1
+
 #: Frames a mixer pull hands out, and so what every node and tap takes per
 #: pull: the palette's own block, so the Splitters' rings empty each pull.
 BLOCK = 256
 
 _CURVE = None
+_GATE = None
 
 
 def comparator_curve():
@@ -61,11 +78,28 @@ def comparator_curve():
     global _CURVE
     if _CURVE is None:
         rail = (CURVE_POINTS - 1) // 2 - DEAD_HALF
-        _CURVE = array("h", [-32767] * rail + [0] * (2 * DEAD_HALF + 1)
+        tick = DEAD_HALF - TICK_HALF
+        _CURVE = array("h", [-32767] * rail + [-TICK] * tick
+                       + [0] * (2 * TICK_HALF + 1) + [TICK] * tick
                        + [32767] * rail)
     return _CURVE
 
 
+def gate_curve():
+    """The table after each divider, built once and shared."""
+    global _GATE
+    if _GATE is None:
+        middle = (CURVE_POINTS - 1) // 2
+        _GATE = array("h", [0] * CURVE_POINTS)
+        for i in range(CURVE_POINTS):
+            step = i - middle
+            if abs(step) > GATE_HALF:
+                _GATE[i] = max(-32767, min(32767, 16 * step))
+        _GATE[1] = -32767
+        _GATE[CURVE_POINTS - 2] = 32767
+    return _GATE
+
+
 def pre_gain(sensitivity_db):
     """The comparator's input gain for a Sensitivity in dBFS."""
     return EDGE / (10.0 ** (sensitivity_db / 20.0))
@@ -93,8 +127,11 @@ class Octaver(_component.Component):
     follows.
     Tone 1 (100 to 2000 Hz) and Tone 2 (40 to 800 Hz) are two-pole
     low-passes at the hertz they show, on the first and second octave.
-    Sensitivity, from -90 to -40 dBFS, is how quiet a note can get before
-    the octaves stop.
+    Sensitivity, from -90 to -40 dBFS, is the level your note must keep
+    after Tracking's low-pass for the octaves to play, not the level you
+    play at. The higher the note, the more that low-pass takes, so a quiet
+    high note stops before a quiet low one: at patch 0 a sine at -60 dBFS
+    still has its octave on E2 and none on E4.
     Constructor values land on the nearest of each knob's 128 steps.
 
     **What you hear.** The octave is exactly half your note and sounds
@@ -103,21 +140,21 @@ class Octaver(_component.Component):
     below the note, until Octave 1 itself stops.
     On an A2 the octave follows your note's decay within 1 dB: it has no
     envelope of its own.
-    Below Sensitivity the octaves are silent, with no ghost and no hum.
+    Below Sensitivity the octaves are silent, with no ghost and no hum,
+    and as a note fades into it the octave never turns into the note
+    itself.
     With the Tones open the octave carries a fifth above it 4.4 dB
     quieter, as the pedal's multiplication does, wherever Tracking is set.
     Turning Tone 1 down thins that fifth more on high notes than on low
     ones.
 
-    **Its range.** At patch 0 every note from low E (E2) to E4 divides
-    cleanly, even with a strong second harmonic.
-    The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.
+    **Its range.** Played at -8.7 dBFS peak, every note at patch 0 from
+    low E (E2) to A4 divides cleanly, even with a strong second harmonic.
+    Played at -8.7 dBFS peak, the Bass patch covers E1 to G3, and High on
+    the neck covers D3 to E5; played quieter, each range ends lower.
     Below the range a low note's second harmonic clocks the divider and it
     skips; above it the clock is low-passed under Sensitivity and the
     octave goes silent.
-    At patch 0 a note with a weak fundamental can drop out at A4, mono or
-    stereo: after the clock's low-pass its fundamental is under
-    Sensitivity.
     Between -90 and -84.5 dBFS Sensitivity changes nothing: that whole
     stretch is one step of the clock.
 
@@ -126,8 +163,9 @@ class Octaver(_component.Component):
     A stereo source is clocked on its mid: with the right channel 45
     degrees ahead of the left, the fifth sits 3.2 dB under the octave
     instead of 4.4, on both channels.
-    The output can peak at about 3.8 times the input (a square, all three
-    levels at full with the Tones open), so keep the input under -13 dBFS.
+    The output can peak at about 5 times the input (a low square, all
+    three levels at full with the Tones open), so keep the input under
+    -15 dBFS.
     A control that jumps makes the output step: move it in small steps
     from the host if you need it smooth.
 
@@ -153,10 +191,11 @@ class Octaver(_component.Component):
     LATENCY_SAMPLES = 0
     TAIL_SAMPLES = None
 
-    #: The worst peak gain over the kit's material, every patch and every
-    #: stop, is 3.75 (a square, all three levels at full with the Tones
-    #: open): -13 dBFS keeps it inside full scale.
-    INPUT_CEILING_DBFS = -13.0
+    #: The worst peak gain is 5.03: a square near E2 with all three levels
+    #: at full, the Tones open and Tracking at 40 Hz, over every semitone
+    #: from E1 to A2 at both Tracking stops (the kit's own 100 Hz square
+    #: reads 3.75). -15 dBFS keeps it 1 dB inside full scale.
+    INPUT_CEILING_DBFS = -15.0
 
     MACRO_LABELS = ("Direct", "Octave 1", "Octave 2", "Tracking", "Tone 1",
                     "Tone 2", "Sensitivity")
@@ -326,8 +365,8 @@ def _mid(self, tap):
 
     def _clock_leg(self, tap):
         """Low-pass at Tracking and a comparator with a dead band: a
-        +-rail square at the note, zero while the clock is under
-        Sensitivity."""
+        +-rail square at the note, a tick of +-TICK while the clock is
+        under Sensitivity and over 18 dB under it, zero below that."""
         clock = self._mid(tap)
         for _ in range(2):
             section = self._own(audiobiquad.Biquad(
@@ -347,13 +386,23 @@ def _clock_leg(self, tap):
 
     def _divide(self, tap, order):
         """A divider on the comparator: a +-1 square at a half (order 1)
-        or a quarter (order 2) of the note, zero while the comparator
-        reads zero. Both orders count the same crossings, so the quarter
-        turns over only where the half does."""
-        return self._own(audiomath.SubOctave(
+        or a quarter (order 2) of the note, zero while the comparator is
+        off its rails. Both orders count the same crossings, so the quarter
+        turns over only where the half does.
+
+        The divider turns over on the ticks, and the gate after it takes
+        them out, so what reaches the multiply is the divider's square on
+        the rails and exact zero elsewhere."""
+        divider = self._own(audiomath.SubOctave(
             tap, order=order, mix=1.0, threshold=CLOCK_THRESHOLD,
             hold_ms=CLOCK_HOLD_MS, sample_rate=self._sample_rate,
             channel_count=self._channel_count))
+        gate = self._own(audioshaper.Waveshaper(
+            sample_rate=self._sample_rate,
+            channel_count=self._channel_count, curve=gate_curve(),
+            oversample=1, mix=1.0, pre_gain=1.0, post_gain=1.0))
+        gate.play(divider)
+        return gate
 
     def _first(self, tap):
         return self._divide(tap, 1)
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
index 506c0bb..6ba3f01 100644
--- a/tests/test_cpython_effects_octaver.py
+++ b/tests/test_cpython_effects_octaver.py
@@ -57,12 +57,11 @@
            3: ("E1", "A1", "E2", "A2", "D3", "G3"),
            4: ("D3", "G3", "B3", "E4", "A4", "E5")}
 
-#: The notes T5 claims clean at each patch. Patch 0 stops at E4: at A4 a
-#: draw with a weak fundamental drops out, mono and stereo
-#: (`T5_DROPOUTS`).
-T5_WINDOWS = {0: ("E2", "A2", "D3", "G3", "B3", "E4"),
-              3: WINDOWS[3],
-              4: WINDOWS[4]}
+#: The notes T5 claims clean at each patch: the whole window. Until the
+#: dividers clocked on the comparator's ticks, patch 0 stopped at E4: at A4
+#: the three draws of seeds 0-39 with the weakest fundamentals had a clock
+#: that crossed one rail and not the other, and played the note.
+T5_WINDOWS = WINDOWS
 
 
 # --------------------------------------------------------------------------
@@ -356,6 +355,93 @@ def t3_sensitivity(cls, rate, name, sens=-50.0):
     return worst
 
 
+def rbj_lowpass(x, fc, q, rate):
+    """The RBJ cookbook two-pole low-pass run over `x`, in float."""
+    w0 = 2.0 * math.pi * fc / rate
+    alpha = math.sin(w0) / (2.0 * q)
+    cw = math.cos(w0)
+    a0 = 1.0 + alpha
+    b0 = (1.0 - cw) / 2.0 / a0
+    b1 = (1.0 - cw) / a0
+    a1 = -2.0 * cw / a0
+    a2 = (1.0 - alpha) / a0
+    y = [0.0] * len(x)
+    x1 = x2 = y1 = y2 = 0.0
+    for i in range(len(x)):
+        v = b0 * x[i] + b1 * x1 + b0 * x2 - a1 * y1 - a2 * y2
+        x2, x1, y2, y1 = x1, x[i], y1, v
+        y[i] = v
+    return y
+
+
+#: The decaying notes the one-sided clock showed on: (patch, note, seed).
+#: At 0a69a2f each played its dry note 3 to 17 dB under the input for 54 to
+#: 194 ms at its end, with Octave 1 alone and no dry.
+ONE_SIDED = ((0, "E2", 3), (0, "G3", 1), (3, "D3", 7), (3, "A1", 7),
+             (2, "D3", 2))
+
+
+def t3_one_sided(cls, rate, patch, name, seed):
+    """Octave 1 alone on R decaying 80 dB over 4 s from -6 dBFS peak, at
+    `patch`, per 8/f window after the first two: (the worst of the output's
+    f over the input's f, in dB, over the windows the octave plays all the
+    way through; the same over the windows it stops in; the worst output
+    power against the input's over the windows whose clock peaks 3 dB under
+    Sensitivity, or None where there is none). The clock is the two Q 0.5
+    low-passes at the Tracking the patch shows, run over the input.
+
+    The window the octave stops in is read apart: an octave that ends
+    within a few cycles spreads its f/2 over the bins beside it, f among
+    them, however cleanly it divides."""
+    f = NOTES[name]
+    probe = cls(kc.feed(array("h", bytes(4)), rate, 1).port,
+                sample_rate=rate)
+    probe.program_change(patch)
+    fc = probe.macro(TRACKING)
+    sens = probe.macro(SENS)
+    probe.deinit()
+    n = 4 * rate
+    r = rich(f, n, seed, rate)
+    values = pcm([16384.0 / 12000.0 * r[i] * 10.0 ** (-4.0 * i / n)
+                  for i in range(n)])
+    xin = [float(v) for v in values]
+    clock = rbj_lowpass(rbj_lowpass(xin, fc, 0.5, rate), fc, 0.5, rate)
+    y = render(cls, values, rate, 1, patch=patch, macros=ONLY1)
+    width = int(round(8.0 * rate / f))
+    period = int(rate / f) + 1
+    worst = [-999.0, -999.0]
+    worst_quiet = None
+    edge = 32768.0 * 10.0 ** ((sens - 3.0) / 20.0)
+    for k in range(2, n // width):
+        lo, hi = k * width, (k + 1) * width
+        part = y[lo:hi]
+        if any(part):
+            through = any(part[-period:])
+            worst[not through] = max(worst[not through],
+                                     level_db(part, f, rate)
+                                     - level_db(xin[lo:hi], f, rate))
+        if max(abs(v) for v in clock[lo:hi]) < edge:
+            out = sum(float(v) * v for v in part) / width
+            inp = sum(v * v for v in xin[lo:hi]) / width
+            rel = 10.0 * math.log10(out + 1e-30) - 10.0 * math.log10(inp)
+            worst_quiet = rel if worst_quiet is None else max(worst_quiet,
+                                                              rel)
+    return worst[0], worst[1], worst_quiet
+
+
+def t3_steady_one_sided(cls, rate):
+    """Octave 1 alone on R (seed 7) at D3, -26 dBFS peak, at the Bass
+    patch, whose clock sits at Sensitivity: the output's f over the
+    input's f, in dB, after the first quarter."""
+    f = NOTES["D3"]
+    n = rate // 2
+    gain = 32768.0 * 10.0 ** (-26.0 / 20.0) / 12000.0
+    values = pcm([v * gain for v in rich(f, n, 7, rate)])
+    y = tail_part(render(cls, values, rate, 1, patch=3, macros=ONLY1))
+    return (level_db(y, f, rate)
+            - level_db(tail_part([float(v) for v in values]), f, rate))
+
+
 def t4_split(cls, rate, channels, name, tones_open):
     f = NOTES[name]
     n = rate
@@ -607,14 +693,6 @@ def _levels(self):
 # --------------------------------------------------------------------------
 # The trait tests (CPython: unittest)
 
-#: The draws of R that drop out at A4 at patch 0, at both rates:
-#: (channels, seed). Their fundamentals are the three weakest of seeds 0 to
-#: 39 (67.0 to 67.7 dB re 1 LSB, the median 73.1; stereo seed 7's mid is
-#: as weak as its left channel), and after the clock filter's 55 dB at
-#: 440 Hz they sit under Sensitivity.
-T5_DROPOUTS = ((1, 13), (1, 34), (2, 7))
-
-
 def _within(value, target, tolerance):
     return abs(value - target) <= tolerance
 
@@ -722,6 +800,47 @@ def test_silent_below_sensitivity(self):
                 self.assertLessEqual(t3_sensitivity(Octaver, rate, name),
                                      -60.0, (rate, name))
 
+    def test_no_dry_note_as_the_clock_fades(self):
+        """(c) A clock whose peaks are unequal crosses one rail before the
+        other. Octave 1 alone never passes the dry note: on decaying notes
+        its f stays 30 dB under the input's in every window it plays
+        through and 20 dB in the window it stops in, and it is 60 dB under
+        the input once the clock peaks 3 dB under Sensitivity; on a steady
+        note whose clock sits at Sensitivity, 40 dB.
+
+        At 0a69a2f the divider clocked on the rails alone and these read
+        -3 to -13 dB: the dry note. What is left at the edge is the
+        quiet side's peaks crossing its rail on some cycles and not on
+        others, which a clock 3 or 4 LSB high does near -80 dBFS (worst
+        -34.2 dB, patch 0 E2)."""
+        for rate in RATES:
+            for patch, name, seed in ONE_SIDED:
+                worst_f, stop_f, quiet = t3_one_sided(Octaver, rate, patch,
+                                                      name, seed)
+                self.assertLessEqual(worst_f, -30.0,
+                                     (rate, patch, name, seed))
+                self.assertLessEqual(stop_f, -20.0,
+                                     (rate, patch, name, seed))
+                self.assertIsNotNone(quiet)
+                self.assertLessEqual(quiet, -60.0, (rate, patch, name, seed))
+            self.assertLessEqual(t3_steady_one_sided(Octaver, rate), -40.0,
+                                 rate)
+
+    def test_a_quiet_high_note_stops_first(self):
+        """(d) Sensitivity reads the clock, after Tracking's low-pass: a
+        sine at -60 dBFS at patch 0 has its clock 9.4 dB over Sensitivity
+        at E2 (10.6 dB under the note) and 26.3 dB under it at E4 (46.3 dB
+        under the note), by `clock_attenuation`."""
+        amp = 32768.0 * 10.0 ** (-60.0 / 20.0)
+        for rate in RATES:
+            for name, plays in (("E2", True), ("E4", False)):
+                f = NOTES[name]
+                db = 20.0 * math.log10(clock_attenuation(f, 90.0))
+                self.assertEqual(-60.0 + db > -80.0 + 3.0, plays)
+                y = render(Octaver, pcm(sine(f, rate, rate, amp=amp)), rate,
+                           1, macros=ONLY1)
+                self.assertEqual(any(tail_part(y)), plays, (rate, name))
+
     def test_a_compressor_is_red(self):
         spread, _ = t3_envelope(Compressed, 48000, "E2", 0)
         self.assertGreater(spread, 1.0)
@@ -771,8 +890,8 @@ def test_a_divider_on_tone_1_is_red(self):
 
 
 class T5Range(TestCase):
-    """8/8 draws of R divide cleanly (f/2 20 dB over its neighbours) at
-    every note of each patch's window."""
+    """8/8 draws of R, at its 12000 peak (-8.7 dBFS), divide cleanly (f/2
+    20 dB over its neighbours) at every note of each patch's window."""
 
     def _window(self, rate, channels):
         for patch in (0, 3, 4):
@@ -789,20 +908,6 @@ def test_the_windows_stereo(self):
         for rate in RATES:
             self._window(rate, 2)
 
-    def test_a_weak_fundamental_can_drop_out_at_a4(self):
-        f = NOTES["A4"]
-        for rate in RATES:
-            n = rate // 2
-            for channels, seed in T5_DROPOUTS:
-                left = rich(f, n, seed, rate)
-                right = rich(f, n, seed, rate, shift=0.3) \
-                    if channels == 2 else None
-                y = render(Octaver, pcm(left, right), rate, channels,
-                           patch=0, macros=ONLY1)
-                self.assertLess(
-                    t5_margin(tail_part(channel(y, channels)), f, rate),
-                    20.0, (rate, channels, seed))
-
     def test_outside_the_window(self):
         rate = 48000
         clean, _ = t5_clean(Octaver, rate, 1, 0, "E1")
@@ -1113,9 +1218,11 @@ def intermodulation(freqs):
     def test_the_peak_gain(self):
         """The kit's square and sine at its own amplitude, at the settings
         the ceiling found worst, all three levels at full with the Tones at
-        both stops, and at every patch."""
+        both stops, and at every patch; and a square on every semitone from
+        E1 to A2 with all three levels at full, the Tones open and Tracking
+        at both stops, at both rates. The worst is a square near E2 with
+        Tracking at 40 Hz: 5.03 times its peak."""
         import kit_ceiling
-        rate = 48000
         amp = 3277
         worst = 0.0
         full = ((DIRECT, 127), (OCT1, 127), (OCT2, 127))
@@ -1125,14 +1232,23 @@ def test_the_peak_gain(self):
                     for t in (0, 127)]
         configs += [(p, ()) for p in sorted(Octaver.PATCHES)]
         for which in ("square", "sine"):
-            values = kit_ceiling.material(which, rate, 1, amp)
+            values = kit_ceiling.material(which, 48000, 1, amp)
             for patch, knobs in configs:
-                y = render(Octaver, values, rate, 1, patch=patch,
+                y = render(Octaver, values, 48000, 1, patch=patch,
                            macros=knobs)
                 worst = max(worst, max(abs(v) for v in y) / float(amp))
-        self.assertTrue(3.7 <= worst <= 3.8, worst)
+        for rate in RATES:
+            for semitone in range(18):
+                period = rate / (41.2034 * 2.0 ** (semitone / 12.0))
+                values = pcm([amp if (i / period) % 1.0 < 0.5 else -amp
+                              for i in range(rate)])
+                for stop in (0, 127):
+                    y = render(Octaver, values, rate, 1,
+                               macros=full + OPEN + ((TRACKING, stop),))
+                    worst = max(worst, max(abs(v) for v in y) / float(amp))
+        self.assertTrue(4.95 <= worst <= 5.1, worst)
         self.assertLessEqual(worst * 10.0 ** (
-            Octaver.INPUT_CEILING_DBFS / 20.0), 1.0)
+            Octaver.INPUT_CEILING_DBFS / 20.0), 0.9)
 
 
 CLAIMS = (
@@ -1153,10 +1269,15 @@ def test_the_peak_gain(self):
      ("TheSurface.test_the_spans",
       "T6Tone.test_tone_1_is_a_two_pole_low_pass",
       "T6Tone.test_tone_2_is_a_two_pole_low_pass")),
-    ("Sensitivity, from -90 to -40 dBFS, is how quiet a note can get before "
-     "the octaves stop.",
+    ("Sensitivity, from -90 to -40 dBFS, is the level your note must keep "
+     "after Tracking's low-pass for the octaves to play, not the level you "
+     "play at.",
      ("TheSurface.test_the_spans",
       "T3Dynamics.test_silent_below_sensitivity")),
+    ("The higher the note, the more that low-pass takes, so a quiet high "
+     "note stops before a quiet low one: at patch 0 a sine at -60 dBFS "
+     "still has its octave on E2 and none on E4.",
+     "T3Dynamics.test_a_quiet_high_note_stops_first"),
     ("Constructor values land on the nearest of each knob's 128 steps.",
      ("TheSurface.test_constructor_values_land_on_the_grid",
       "TheSurface.test_a_fresh_instance_reads_patch_0")),
@@ -1170,8 +1291,11 @@ def test_the_peak_gain(self):
     ("On an A2 the octave follows your note's decay within 1 dB: it has "
      "no envelope of its own.",
      "T3Dynamics.test_the_octave_follows_the_decay"),
-    ("Below Sensitivity the octaves are silent, with no ghost and no hum.",
-     "T3Dynamics.test_silent_below_sensitivity"),
+    ("Below Sensitivity the octaves are silent, with no ghost and no hum, "
+     "and as a note fades into it the octave never turns into the note "
+     "itself.",
+     ("T3Dynamics.test_silent_below_sensitivity",
+      "T3Dynamics.test_no_dry_note_as_the_clock_fades")),
     ("With the Tones open the octave carries a fifth above it 4.4 dB "
      "quieter, as the pedal's multiplication does, wherever Tracking is "
      "set.",
@@ -1179,11 +1303,13 @@ def test_the_peak_gain(self):
     ("Turning Tone 1 down thins that fifth more on high notes than on low "
      "ones.",
      "T6Tone.test_tone_1_is_a_two_pole_low_pass"),
-    ("At patch 0 every note from low E (E2) to E4 divides cleanly, even "
-     "with a strong second harmonic.",
-     ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo")),
-    ("The Bass patch covers E1 to G3, and High on the neck covers D3 to E5.",
+    ("Played at -8.7 dBFS peak, every note at patch 0 from low E (E2) to A4 "
+     "divides cleanly, even with a strong second harmonic.",
      ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo")),
+    ("Played at -8.7 dBFS peak, the Bass patch covers E1 to G3, and High on "
+     "the neck covers D3 to E5; played quieter, each range ends lower.",
+     ("T5Range.test_the_windows_mono", "T5Range.test_the_windows_stereo",
+      "T3Dynamics.test_a_quiet_high_note_stops_first")),
     ("Below the range a low note's second harmonic clocks the divider and "
      "it skips; above it the clock is low-passed under Sensitivity and the "
      "octave goes silent.",
@@ -1199,13 +1325,9 @@ def test_the_peak_gain(self):
      "instead of 4.4, on both channels.",
      ("T2Multiplication.test_stereo_45_degrees",
       "T2Multiplication.test_in_phase_stereo_reads_as_mono")),
-    ("At patch 0 a note with a weak fundamental can drop out at A4, mono "
-     "or stereo: after the clock's low-pass its fundamental is under "
-     "Sensitivity.",
-     "T5Range.test_a_weak_fundamental_can_drop_out_at_a4"),
-    ("The output can peak at about 3.8 times the input (a square, all "
+    ("The output can peak at about 5 times the input (a low square, all "
      "three levels at full with the Tones open), so keep the input under "
-     "-13 dBFS.",
+     "-15 dBFS.",
      "TheSurface.test_the_peak_gain"),
     ("A control that jumps makes the output step: move it in small steps "
      "from the host if you need it smooth.",

From ee5ebe35c7eaa4954e99f882c04f7f247123959f Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:29:25 -0500
Subject: [PATCH 48/76] ShimmerHall: declare only the macros whose E4 cells are
 red

---
 tests/support/lifecycle.py | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 8c68291..43f7428 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -247,12 +247,18 @@
     # instance does (the class's reset test); it is the control that never
     # was reset.
     ("ShimmerHall", "E1-", "P4"): "reset() empties the hall and restarts its modulation, so it never re-converges with the uninterrupted control (Reverb's E1 P4)",
-    ("ShimmerHall", "E4-", "P4"): "a move that reaches the hall, its input or its tank (Character, Bloom, Interval, Size, Mix to 0 and back) leaves the tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m0=", "P4"): "Character re-cuts the wet chain and empties the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m1=", "P4"): "Shimmer changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m3=", "P4"): "Bloom changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m4=", "P4"): "Interval changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m6=", "P4"): "Size re-cuts the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m8=", "P4"): "Mix to 0 and back empties the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
     ("ShimmerHall", "E5-", "P4"): "Mix to 0 and back empties the hall and restarts its modulation (as E1)",
     ("ShimmerHall", "E6-", "P4"): "a patch move reaches the hall's input or its tank and leaves it off the control's for good (Reverb's E6 P4)",
     ("ShimmerHall", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the hall (as E1)",
     ("ShimmerHall", "E11-", "P4"): "moves that reach the hall or empty it leave its tank off the control's for good (Reverb's E11 P4)",
-    ("ShimmerHall", "E4-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step",
+    ("ShimmerHall", "E4-m0=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Character)",
+    ("ShimmerHall", "E4-m3=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Bloom)",
     ("ShimmerHall", "E5-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
     ("ShimmerHall", "E6-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (a patch change)",
     ("ShimmerHall", "E9-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",

From a00bb9613dd63c1cf9a7bfa6a8438aa2158d77be Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:39:59 -0500
Subject: [PATCH 49/76] Lifecycle PR: a return from Mix 0 is judged against a
 fresh instance only when Mix 0 routed around the graph

A Mix 0 that keeps the graph running (every Phase 5 class but MultiTapDelay, and every node adapter) comes back to its own state, so PR prints na there.
---
 tests/support/LIFECYCLE.md |  9 +++++----
 tests/support/lifecycle.py | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/tests/support/LIFECYCLE.md b/tests/support/LIFECYCLE.md
index fe20bd5..1fc3bd7 100644
--- a/tests/support/LIFECYCLE.md
+++ b/tests/support/LIFECYCLE.md
@@ -97,10 +97,11 @@ at patch 0.
   plays its first block at the old setting, which P4's bound forgives.
 - **PR** (E1-reset@block, E10-reset, E5-mix0, E10-mix0) From the move that
   lands the class on a state it can be built at (a reset: patch 0; a
-  return from Mix 0: the cell's own configuration) on, 4096 frames are
-  byte-identical to a fresh instance built there and fed the source from
-  the same frame. Where the source stands is read off a dry run to the
-  move. No tail is forgiven: a child left at its own patch 0, a line kept
+  return from Mix 0 that routed around the graph, a rejoin: the cell's own
+  configuration; a Mix 0 that keeps the graph running prints `na`) on,
+  4096 frames are byte-identical to a fresh instance built there and fed
+  the source from the same frame. Where the source stands is read off a
+  dry run to the move. No tail is forgiven: a child left at its own patch 0, a line kept
   across a reset or a block primed twice is red here.
 - **P6** The three interpreters print identical lines for every cell. Each
   line carries `h:`, a CRC-32 of the event instance's whole render, so P6
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index b7c9999..59ef633 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -1374,6 +1374,19 @@ def _diverge(a, b, frames, fsize):
     return -1
 
 
+def _routes_around(cls, ev, rate, channels, patch, options):
+    """True when the event's move away routes the output around the graph
+    (`_route_around`), so the way back is a rejoin."""
+    feed = Feed(material_for("once", rate, channels), rate, channels, "256",
+                loop=False)
+    e = _build(cls, feed, rate, patch, options)
+    try:
+        act(e, feed, Ctx(e, patch), ev.away)
+        return bool(getattr(e, "_stranded", False))
+    finally:
+        e.deinit()
+
+
 def pr(cls, ev, rate, channels, patch, options):
     """PR: from the move that lands the class (a reset, a return from Mix
     0) on, it renders byte for byte what a fresh instance built at the
@@ -1381,6 +1394,11 @@ def pr(cls, ev, rate, channels, patch, options):
     fsize = 2 * channels
     values = material_for("once", rate, channels)
     upto = _land_pull(ev)
+    if ev.landing == "config" and not _routes_around(cls, ev, rate, channels,
+                                                     patch, options):
+        # Mix 0 that keeps the graph running is not a rejoin: the class
+        # comes back to its own state, not a fresh one's.
+        return "na(Mix 0 keeps the graph running)"
     landing = 0 if ev.landing == "reset" else patch
     fresh = {} if landing is None else {"patch": landing}
     start = 0

From f0ebdbb114e7739d694945ce8d404300a9c58dfd Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:51:14 -0500
Subject: [PATCH 50/76] Harmonizer: a voice turned off plays silence from the
 move on, not the dry at its old level

An off voice now plays its tap through a one-voice mixer held at level 0,
so the Mixer's level gate has nothing to hold open. Renders with no voice
turned off after it played are byte for byte what they were.
---
 lib/audioeffects/rebuilt/harmonizer.py   | 38 +++++++++--
 tests/test_cpython_effects_harmonizer.py | 82 +++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 8 deletions(-)

diff --git a/lib/audioeffects/rebuilt/harmonizer.py b/lib/audioeffects/rebuilt/harmonizer.py
index d308038..06437af 100644
--- a/lib/audioeffects/rebuilt/harmonizer.py
+++ b/lib/audioeffects/rebuilt/harmonizer.py
@@ -222,7 +222,7 @@ def _build(self, pitch=0.0, voice1=4.0, voice2=7.0, voice3=-12.0,
         channels = self._channel_count
         self._ready = False
         self._armed = False
-        #: Which voices play their shifter; the others play their tap at 0.
+        #: Which voices play their shifter; the others play their tap, silenced.
         self._on = [True, True, True]
         self._puller = None
 
@@ -257,12 +257,29 @@ def _build(self, pitch=0.0, voice1=4.0, voice2=7.0, voice3=-12.0,
             self._shifters.append(shifter)
 
         # Each mixer voice plays a Port, so switching a voice between its
-        # shifter and its bare tap re-points the port and primes nothing.
+        # shifter and its silenced tap re-points the port and primes nothing.
         self._ports = [self._own(audioroute.Port(self._taps[0]),
                                  reset=False)]
         for k in range(3):
             self._ports.append(self._own(audioroute.Port(self._shifters[k]),
                                          reset=False))
+        # What a voice that is off plays: its tap, held at level 0 for good.
+        self._drains = []
+        self._feeds = []
+        for k in range(3):
+            feed = self._own(audioroute.Port(self._hush), reset=False)
+            drain = self._own(audiomixer.Mixer(
+                voice_count=1, **self._pcm(1024 * channels)), reset=False)
+            drain.voice[0].level = 0.0
+            drain.voice[0].play(feed, loop=True)
+            # Its play() primed a block of the hush; one pull drops it, so
+            # the drain holds nothing when it first reads its tap.
+            drop = audiomixer.Mixer(voice_count=1, **self._pcm(16))
+            drop.voice[0].play(drain)
+            drop.voice[0].stop()
+            drop.deinit()
+            self._feeds.append(feed)
+            self._drains.append(drain)
         # Not reset by the walk: no voice holds a block between two pulls.
         self._mixer = self._own(audiomixer.Mixer(
             voice_count=4, **self._pcm(1024 * channels)), reset=False)
@@ -328,9 +345,15 @@ def _voice_source(self, k):
         return self._shifters[k]
 
     def _off_source(self, k):
-        """What voice `k` plays while it is off: its bare tap, at level 0,
-        so its shifter is not pulled."""
-        return self._taps[k + 1]
+        """What voice `k` plays while it is off: its tap through a
+        one-voice mixer that has only ever been at level 0. The voice reads
+        the tap, which keeps the split even and does not pull its shifter,
+        and plays silence from the first frame; the bare tap would play the
+        dry at the voice's old level until the voice's level gate closed.
+        The mixer's own voice never plays again, so nothing is primed from
+        the live tap when a voice goes off."""
+        self._feeds[k].play(self._taps[k + 1])
+        return self._drains[k]
 
     def _empty(self, k):
         """Empty voice `k`'s line before it comes back on."""
@@ -428,8 +451,9 @@ def _route(self):
         self._output = self._tail
 
     def _switch(self):
-        """Turn voices on and off. A voice going off plays its bare tap at
-        level 0, so the split stays even and its shifter is not pulled; a
+        """Turn voices on and off. A voice going off plays its tap through
+        a mixer held at level 0, so the split stays even, its shifter is
+        not pulled and the dry never leaks at the voice's old level; a
         voice coming back empties its shifter's line, plays it, then takes
         its level."""
         voices = self._mixer.voice
diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
index 2dfaaaa..4eb9462 100644
--- a/tests/test_cpython_effects_harmonizer.py
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -376,6 +376,13 @@ def _dry_level(self):
         return Harmonizer._dry_level(self) / (1 + on)
 
 
+class BareTapOff(Harmonizer):
+    """T7: a voice that is off plays its bare tap, the dry, at level 0."""
+
+    def _off_source(self, k):
+        return self._taps[k + 1]
+
+
 class Unrounded(Harmonizer):
     """T2: the node is handed the asked semitones, and floors them."""
 
@@ -1034,6 +1041,78 @@ def test_pulled_while_off_is_red(self):
             self.assertGreater(loud, 0, rate)
 
 
+# --------------------------------------------------------------------------
+# T7: a voice turned off plays nothing from the move on
+
+
+def sine(frames, channels, amp, period, lead=BLOCK):
+    """A sine of `period` frames after `lead` frames of silence."""
+    out = array("h", bytes(2 * frames * channels))
+    for i in range(lead, frames):
+        v = int(round(amp * math.sin(2.0 * math.pi * (i - lead) / period)))
+        for c in range(channels):
+            out[i * channels + c] = v
+    return out
+
+
+def t7_leak(cls, rate, channels, hz, mix_m, k, how):
+    """Frames, from the move on, where a render that turns voice `k` off
+    mid-stream differs from an instance built with it off: the dry or a
+    voice playing at an old level for want of the move."""
+    n = 40
+    at = 20
+    values = sine(n * BLOCK, channels, 8000.0, rate / hz)
+    base = [(MIX, mix_m), (SPREAD, 127)]
+    if how == "level":
+        def move(e):
+            e.set_macro(LEVEL[k], 0)
+        first = base
+        built = base + [(LEVEL[k], 0)]
+    else:
+        # Patch 0 with Spread and Mix as asked, then patch 6 (patch 0
+        # without voice 3); the reference is patch 0 with voice 3 off.
+        assert k == 2
+
+        def move(e):
+            e.program_change(6)
+            for index, value in base:
+                e.set_macro(index, value)
+        first = base
+        built = base + [(LEVEL[2], 0)]
+    y = render(cls, values, rate, channels, macros=first,
+               actions={at: move})
+    ref = render(cls, values, rate, channels, macros=built)
+    start = at * BLOCK * channels
+    return sorted(set(i // channels for i in range(start, len(y))
+                      if y[i] != ref[i]))
+
+
+class T7TurnOff(TestCase):
+    """Turning a voice off never lets the dry through at the voice's old
+    level and pan: from the move on, the render is the one of an instance
+    built with the voice off, byte for byte."""
+
+    def _cells(self, cls):
+        for rate in RATES:
+            for channels in CHANNELS:
+                for hz in (41.2, 50.0):
+                    for mix_m in (64, 127):
+                        for k, how in ((0, "level"), (2, "level"),
+                                       (2, "patch")):
+                            yield ((rate, channels, hz, mix_m, k, how),
+                                   t7_leak(cls, rate, channels, hz, mix_m,
+                                           k, how))
+
+    def test_off_plays_nothing(self):
+        for cell, leaked in self._cells(Harmonizer):
+            self.assertEqual(leaked, [], cell)
+
+    def test_the_bare_tap_is_red(self):
+        for cell, leaked in self._cells(BareTapOff):
+            if cell[:3] == (48000, 2, 50.0) and cell[3] == 127:
+                self.assertGreater(len(leaked), 0, cell)
+
+
 # --------------------------------------------------------------------------
 # The surface, the wire, the tail
 
@@ -1318,7 +1397,8 @@ def test_the_stated_ceiling_covers_every_setting(self):
       "TheSurface.test_the_window")),
     ("Each voice is its own machine: turning one on or off never changes "
      "the dry or the other voices.",
-     "T1Independent.test_the_sum_of_the_solos"),
+     ("T1Independent.test_the_sum_of_the_solos",
+      "T7TurnOff.test_off_plays_nothing")),
     ("Each voice sits on the closest pitch its shifter can make: within 3.4 "
      "cents of its interval from unison up, 6.8 cents down to an octave "
      "below and 13.7 cents below that.",

From 712f482e1c83518c8ecb50a569ff02a53e371e5f Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:52:34 -0500
Subject: [PATCH 51/76] ShimmerHall: skip E8 on CircuitPython (upstream
 PitchShift), disclose it, and state the longest tail bound

---
 lib/audioeffects/rebuilt/shimmerhall.py   | 26 ++++++++++++-----------
 tests/support/lifecycle.py                |  4 ++++
 tests/test_cpython_effects_shimmerhall.py | 14 ++++++++++--
 3 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index 7e11ccd..fdf2036 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -33,24 +33,26 @@
 hall to the rail.
 
 `tail_samples` bounds how long the output takes to reach exact zero once
-your input stops. `reset()` empties the hall, the line and the shifter, and
-restores patch 0.
-
-The patches: Octave Bloom (the defaults), Short Stagger, Fifth Halo, Slow
-Rise, Rise Damped, Falling Octaves.
+your input stops: 82 s at Rise 0.9 and Bloom 800 ms. `reset()` empties the
+hall, the line and the shifter, and restores patch 0. The patches: Octave
+Bloom (the defaults), Short Stagger, Fifth Halo, Slow Rise, Rise Damped,
+Falling Octaves.
 
 **Limits**
 
 A control that jumps makes the output step: move it in small steps from the
-host if you need it smooth.
-
-Moving Character or Size empties the hall: the tail drops and the dry
-carries on.
+host if you need it smooth. Moving Character or Size empties the hall: the
+tail drops and the dry carries on.
 
 Interval is a fixed shift in semitones, with no key awareness. Both
-shifters splice, so the shifted copy has a slight flutter. At a lower sample
-rate the band ends lower, so the climb reaches the top of it sooner. A mono source
-gets a mono rack. It needs a board with PSRAM.
+shifters splice, so the shifted copy has a slight flutter. At a lower
+sample rate the band ends lower, so the climb reaches the top of it sooner.
+A mono source gets a mono rack. It needs a board with PSRAM.
+
+When your source ends, the tail rings out as it would on silence. On a
+CircuitPython board, stop the rack from the host if your source can run
+dry in Bloom: CircuitPython's own pitch shifter waits on a source that
+comes back empty.
 
 A value outside a macro's span clamps to the nearer stop, and NaN takes the
 default; an `interval` other than the five raises `ValueError`.
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index aaafa60..387b1c2 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -282,6 +282,10 @@
         "upstream's GranularPitchShift never returns from a pull on a looped"
         " source that ends empty; audiodsp#243 fixed it on CPython and"
         " MicroPython",
+    ("ShimmerHall", "E8-", "circuitpython"):
+        "Bloom pulls upstream's PitchShift, which never returns from a pull"
+        " on a looped source that ends empty (audiodsp#243 fixed it on"
+        " CPython and MicroPython)",
 }
 
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 9167db7..010d95f 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -797,6 +797,15 @@ def test_tail_samples(self):
                 finally:
                     e.deinit()
 
+    def test_the_longest_tail(self):
+        for rate in RATES:
+            e = ShimmerHall(_port(rate), character="rise", rise=0.9,
+                            bloom_ms=800.0)
+            try:
+                self.assertEqual(int(e.tail_samples / rate + 0.5), 82)
+            finally:
+                e.deinit()
+
     def test_tail_is_zero_at_mix_0(self):
         e = ShimmerHall(_port(), mix=0.0)
         try:
@@ -1083,8 +1092,9 @@ def test_late_dry_is_red(self):
      "Rise at the top, a steady loud input fills the hall to the rail.",
      "test_the_input_ceiling"),
     ("`tail_samples` bounds how long the output takes to reach exact zero "
-     "once your input stops.",
-     ("test_tail_samples", "test_tail_is_zero_at_mix_0")),
+     "once your input stops: 82 s at Rise 0.9 and Bloom 800 ms.",
+     ("test_tail_samples", "test_tail_is_zero_at_mix_0",
+      "test_the_longest_tail")),
     ("`reset()` empties the hall, the line and the shifter, and restores "
      "patch 0.", "test_reset_empties_the_graph_and_returns_to_patch_0"),
     ("Moving Character or Size empties the hall: the tail drops and the dry "

From 35fc556f129b2075bf7d7edcb85a2e86e1c2570b Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 03:54:13 -0500
Subject: [PATCH 52/76] StereoWidener: a rack's reset keeps the constructor's
 Delay

Name _delay_exact in _KEPT, keep it while _seeding, and move the once-per-patch
work (hold _ready, refresh once, drop the exact Delay) into _apply_positions so
a patch and a rack's restore take one path. A refused program_change still
changes nothing: the base validates before it reaches _apply_positions.
---
 lib/audioeffects/rebuilt/stereowidener.py | 24 ++++++++------
 tests/test_cpython_effects_rack.py        | 38 +++++++++++++++++++++++
 2 files changed, 52 insertions(+), 10 deletions(-)

diff --git a/lib/audioeffects/rebuilt/stereowidener.py b/lib/audioeffects/rebuilt/stereowidener.py
index f4eada5..887e139 100644
--- a/lib/audioeffects/rebuilt/stereowidener.py
+++ b/lib/audioeffects/rebuilt/stereowidener.py
@@ -156,6 +156,10 @@ class StereoWidener(_component.Component):
     #: an anti-phase pair's side, and 2 x 16 383 still fits.
     INPUT_CEILING_DBFS = -6.03
 
+    #: The constructor's Delay, exactly, which a rack's reset puts back
+    #: with the knobs.
+    _KEPT = ("_delay_exact",)
+
     MACRO_LABELS = ("Width", "Delay", "Character")
     MACRO_MODES = {
         0: "BIPOLAR",
@@ -352,27 +356,27 @@ def _levels(self):
     # -- applying ------------------------------------------------------
 
     def _apply_macro(self, index, position):
-        if index == DELAY_I and self._ready and (
+        if index == DELAY_I and self._ready and not self._seeding and (
                 abs(position - self._delay_seed) > ECHO_TOLERANCE):
             self._delay_exact = None
         if self._ready:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the graph once."""
+    def _apply_positions(self, positions, patch_index):
+        """Apply a patch (or a rack's restore) whole, then refresh the graph
+        once. A patch drops the constructor's Delay; a restore keeps the
+        one it put back (`_KEPT`), so the two share this one path."""
         ready = self._ready
         self._ready = False
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._ready = ready
-        if type(self).PATCHES.get(index) is not None:
-            # Only a call the base accepted drops the constructor's Delay.
+        if not self._seeding:
             self._delay_exact = None
-            if ready:
-                self._refresh()
+        if ready:
+            self._refresh()
 
     def _refresh(self):
         if self._ms is None:
diff --git a/tests/test_cpython_effects_rack.py b/tests/test_cpython_effects_rack.py
index 585f2c0..b33d2b9 100644
--- a/tests/test_cpython_effects_rack.py
+++ b/tests/test_cpython_effects_rack.py
@@ -1065,6 +1065,41 @@ def run(rack):
     return wrong
 
 
+def t4_widener(cls, rate, channels):
+    """A StereoWidener built at Delay 20 ms comes back from the rack's reset
+    as built: it plays the 20 ms, reads 20.0 back, and renders what the
+    freshly built rack does, after its Delay was moved before the reset."""
+    wrong = []
+    frames = 12000
+    values = clicks(frames, channels, range(512, frames, 2400))
+    widener = rebuilt.module_class("StereoWidener")
+    chain = ((widener, {"delay_ms": 20.0}),)
+
+    def before(rack):
+        rack.effects[0].set_macro(1, 100)
+
+    def run(rack):
+        return pull(rack.output, frames - 512, channels)
+
+    for line in _against_fresh(cls, rate, channels, chain, values, run,
+                               before):
+        wrong.append("StereoWidener: %s" % line)
+    rack = cls.create(_feed(values, rate, channels).port, rate, chain=chain)
+    try:
+        before(rack)
+        rack.reset()
+        got = rack.effects[0].macro(1)
+        if got != 20.0:
+            wrong.append("StereoWidener: Delay reads %r after reset, 20.0 "
+                         "as built" % (got,))
+        if rack.effects[0]._delay_exact != 20.0:
+            wrong.append("StereoWidener: _delay_exact is %r after reset"
+                         % (rack.effects[0]._delay_exact,))
+    finally:
+        rack.deinit()
+    return wrong
+
+
 def t5_patch(cls):
     """A `patch=` the rack refuses releases every pedal it had built."""
     wrong = []
@@ -1259,6 +1294,9 @@ def test_exact_constructor_values_come_back(self):
             self.assertEqual(t4_exact(Rack, rate, channels), [],
                              (rate, channels))
 
+    def test_a_stereo_widener_comes_back_with_its_exact_delay(self):
+        self.assertEqual(t4_widener(Rack, 48000, 2), [])
+
     def test_reset_as_built_faults_are_red(self):
         self.assertNotEqual(t4_mix0(PutBackRack, 48000, 2), [])
         for plant in (PutBackRack, PositionsOnlyRack):

From a7ec4d706b5ac956de121385adfeb9003dbc9499 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:07:49 -0500
Subject: [PATCH 53/76] PitchShifter: a reset or a return from Mix 0 is new
 again, only a move that changes a voice's level re-arms, the
 early-output-read limit and the Feedback intervals are in the docstring

---
 lib/audioeffects/rebuilt/pitchshifter.py   |  31 +++-
 tests/support/kit_common.py                |   8 +-
 tests/support/lifecycle.py                 |  19 +-
 tests/test_cpython_effects_pitchshifter.py | 193 ++++++++++++++++++++-
 4 files changed, 225 insertions(+), 26 deletions(-)

diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
index 39a30e0..f575c59 100644
--- a/lib/audioeffects/rebuilt/pitchshifter.py
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -137,7 +137,9 @@ class PitchShifter(_component.Component):
     sample, with the shifted voice added on top, so a hot input can reach
     the rail.
     Feedback stacks level too, far past the input: at Feedback 127, Delay 0
-    and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail.
+    and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail at unison
+    or an octave up, and comes within 4 dB of it at an octave down or a
+    fourth or fifth either way.
 
     **Mono, latency, tail.** A one-channel source gets a one-channel
     shifter with the same window.
@@ -147,6 +149,8 @@ class PitchShifter(_component.Component):
     `reset()` empties the shifter and both delay lines and returns to
     patch 0.
     The class never reads the host's tempo.
+    If your host takes the output before it loads a patch or moves Mix, the
+    first 256 frames, 5 ms at 48 kHz, play at the old level.
 
     **Limits shared by the family.**
     A control that jumps makes the output step: move it in small steps from
@@ -216,8 +220,11 @@ def _build(self, pitch=7.0, fine=0.0, mix=1.0, delay_ms=0.0,
         self._wired = False
         #: Whether the host has asked for the output yet. Until it has,
         #: nothing has been pulled, and a control that moves a voice's
-        #: level re-arms the graph so the level holds from frame 0.
+        #: level re-arms the graph so the level holds from frame 0. A reset
+        #: or a return from Mix 0 starts that window again.
         self._taken = False
+        #: The two Mixer levels last handed to the voices.
+        self._applied = None
         #: Whether the loop's splicer has run since its line was last
         #: emptied: it then reads half a window later (`_loop_frames`).
         self._engaged = False
@@ -411,11 +418,17 @@ def _loop_frames(self):
             return frames - self._window * 0.5
         return frames
 
-    def _levels(self):
+    def _level_pair(self):
+        """The dry and the shifted voice's Mixer levels at this Mix."""
         mix = self._mix()
+        return (min(1.0, 2.0 - mix), min(1.0, mix))
+
+    def _levels(self):
         voices = self._mixer.voice
-        voices[0].level = min(1.0, 2.0 - mix)
-        voices[1].level = min(1.0, mix)
+        pair = self._level_pair()
+        voices[0].level = pair[0]
+        voices[1].level = pair[1]
+        self._applied = pair
 
     # -- applying ------------------------------------------------------
 
@@ -462,10 +475,15 @@ def _route(self):
             return
         if not self._wired:
             self._wire()
-        elif self._rejoin() or not self._taken:
+        elif self._rejoin():
+            # The graph was emptied: it is new again until it is pulled.
+            self._taken = False
+            self._rearm()
+        elif not self._taken and self._level_pair() != self._applied:
             # Not pulled yet: a level moved now would wait for its voice's
             # next zero crossing, a block of the old level, where an
             # instance built at this setting plays the new one from frame 0.
+            # A move that leaves both levels alone has nothing to wait for.
             self._rearm()
         else:
             self._levels()
@@ -485,6 +503,7 @@ def reset(self):
         wired = self._wired
         _component.Component.reset(self)
         if wired:
+            self._taken = False
             self._rearm()
 
     @property
diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index b70b861..f898962 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -35,9 +35,11 @@
 # times the input's peak on a DC, so the rail is reachable below any useful
 # ceiling. The docstring says so ("Feedback stacks level too, far past the
 # input: at Feedback 127, Delay 0 and Mix 2 a noise burst peaking at
-# -10.3 dBFS reaches the rail"), and test_feedback_near_its_top_stacks_
-# level_far_past_the_input holds it. The square, sine and DC cells there, at
-# every rate and channel count.
+# -10.3 dBFS reaches the rail at unison or an octave up, and comes within
+# 4 dB of it at an octave down or a fourth or fifth either way"), and
+# test_feedback_near_its_top_stacks_level_far_past_the_input holds it at each
+# Pitch named. The square, sine and DC cells there, at every rate and channel
+# count.
 for _material in ("square", "sine", "dc"):
     for _rate in RATES:
         for _channels in CHANNELS:
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 277d840..00b67ed 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -114,16 +114,17 @@
         "CircuitPython only: as E10-reset, the return from Mix 0 empties the"
         " lines but CircuitPython's PitchShift keeps its positions",
     ("PitchShifter", "E10-macros", "P4"):
-        "CircuitPython only: a macro moved before the first pull re-arms the"
-        " graph so its voice levels hold from frame 0, and the re-arm's"
-        " priming pulls move CircuitPython's own PitchShift off the"
-        " control's splice phase (it keeps its positions through a clear);"
-        " CPython and MicroPython are ok (ruled a CircuitPython-own"
-        " difference)",
+        "CircuitPython only: the macros move to 127 before the first pull,"
+        " which changes the Mixer levels, so the graph is re-armed (only a"
+        " move that changes a level re-arms) and the re-arm's priming pulls"
+        " move CircuitPython's own PitchShift off the control's splice phase"
+        " (it keeps its positions through a clear); CPython and MicroPython"
+        " are ok (ruled a CircuitPython-own difference)",
     ("PitchShifter", "E10-patch", "P4"):
-        "CircuitPython only: as E10-macros, a patch loaded before the first"
-        " pull is re-armed, and CircuitPython's PitchShift keeps its"
-        " positions",
+        "CircuitPython only: as E10-macros, the patch loaded before the first"
+        " pull changes the Mixer levels and is re-armed, and CircuitPython's"
+        " PitchShift keeps its positions (28 of the 32 cells; the four that"
+        " start at patch 2 are ok)",
     ("PitchShifter", "E4-m2=", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step (Mix)",
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
index eea0b18..8d605ab 100644
--- a/tests/test_cpython_effects_pitchshifter.py
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -773,9 +773,11 @@ def test_a_hot_input_reaches_the_rail_at_mix_1(self):
 
     def test_feedback_near_its_top_stacks_level_far_past_the_input(self):
         # A noise burst peaking at -10.3 dBFS (10000 of 32768), through
-        # Feedback 127 with Delay 0 and Mix 2, an octave up: the repeats
-        # pile up on each other and the shifted voice alone reaches the
-        # rail.
+        # Feedback 127 with Delay 0 and Mix 2: at unison and an octave up
+        # the repeats pile up on each other and the shifted voice alone
+        # reaches the rail; at an octave down and a fourth or a fifth either
+        # way it comes within 4 dB of it.
+        close = 32768 * 10 ** (-4 / 20.0)
         for rate, channels in ((48000, 2), (22050, 1)):
             burst = rate // 10
             values = array("h", bytes(2 * burst * channels))
@@ -783,13 +785,21 @@ def test_feedback_near_its_top_stacks_level_far_past_the_input(self):
             for i in range(burst * channels):
                 state = (state * 1103515245 + 12345) & 0x7FFFFFFF
                 values[i] = (state >> 8) % 20001 - 10000
+            self.assertTrue(9900 < max(max(values), -min(values)) <= 10000)
             frames = 3 * rate
             padded = values + array("h", bytes(2 * (frames - burst)
                                                * channels))
-            out = render(PitchShifter, padded, rate, channels, frames,
-                         pitch=12.0, mix=2.0, delay_ms=0.0, feedback=0.95)
-            self.assertTrue(max(out) == 32767 or min(out) == -32768,
-                            (rate, channels, max(out), min(out)))
+            for pitch in (-12, -7, -5, 0, 5, 7, 12):
+                out = render(PitchShifter, padded, rate, channels, frames,
+                             pitch=float(pitch), mix=2.0, delay_ms=0.0,
+                             feedback=0.95)
+                peak = max(max(out), -min(out))
+                where = (rate, channels, pitch, peak)
+                if pitch in (0, 12):
+                    self.assertTrue(max(out) == 32767 or min(out) == -32768,
+                                    where)
+                else:
+                    self.assertGreaterEqual(peak, close, where)
 
     def test_a_mono_source_is_one_channel_of_a_stereo_one(self):
         for rate in RATES:
@@ -1032,6 +1042,168 @@ def both(e):
             self.assertEqual(got[12 * BLOCK * channels:], fresh,
                              (rate, channels))
 
+    def test_a_move_right_after_a_reset_is_a_fresh_instance_at_that_setting(
+            self):
+        # reset() makes the instance new again: until the next pull a patch
+        # or a Mix move re-arms it as it would a new one, so the voices play
+        # the new level from the first frame after the move.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            blocks = 30
+            dc = array("h", [6000] * (blocks * BLOCK * channels))
+            later = dc[12 * BLOCK * channels:]
+            for patch in range(len(PitchShifter.PATCHES)):
+                got = played(dc, rate, channels, blocks,
+                             {12: lambda e, p=patch: (e.reset(),
+                                                      e.program_change(p))})
+                fresh = render(PitchShifter, later, rate, channels,
+                               (blocks - 12) * BLOCK, patch=patch)
+                self.assertEqual(got[12 * BLOCK * channels:], fresh,
+                                 (rate, channels, "patch", patch))
+            for midi in (1, 32, 96, 127):
+                mix = _component.macro_value(
+                    (0.0, 2.0), _component.position_of_midi("BIPOLAR", midi))
+                got = played(dc, rate, channels, blocks,
+                             {12: lambda e, m=midi: (e.reset(),
+                                                     e.set_macro(MIX_I, m))})
+                fresh = render(PitchShifter, later, rate, channels,
+                               (blocks - 12) * BLOCK, mix=mix)
+                self.assertEqual(got[12 * BLOCK * channels:], fresh,
+                                 (rate, channels, "mix", midi))
+
+    def test_a_move_right_after_a_return_from_mix_0_is_a_fresh_instance(
+            self):
+        # The return from Mix 0 re-arms the graph; a patch loaded before the
+        # next pull re-arms it again at the patch's levels.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            blocks = 30
+            dc = array("h", [6000] * (blocks * BLOCK * channels))
+
+            def back(e):
+                e.set_macro(MIX_I, 64)
+                e.program_change(6)
+            got = played(dc, rate, channels, blocks,
+                         {10: lambda e: e.set_macro(MIX_I, 0), 18: back})
+            fresh = render(PitchShifter, dc[18 * BLOCK * channels:], rate,
+                           channels, (blocks - 18) * BLOCK, patch=6)
+            self.assertEqual(got[18 * BLOCK * channels:], fresh,
+                             (rate, channels))
+
+    def test_only_a_move_that_changes_a_voice_level_re_arms(self):
+        # Before the output is first taken, Pitch, Fine, Delay, Feedback and
+        # a patch that leaves both Mixer levels where they are do not re-arm
+        # the graph (a re-arm primes the shifter again); a move that changes
+        # a level does, once, and the same level again does not.
+        def counted(e):
+            count = [0]
+            rearm = e._rearm
+
+            def wrapped():
+                count[0] += 1
+                rearm()
+            e._rearm = wrapped
+            return count
+
+        def mix_of(midi):
+            return _component.macro_value(
+                (0.0, 2.0), _component.position_of_midi("BIPOLAR", midi))
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(37)
+            frames = 24 * BLOCK
+            values = array("h", [rng.next() % 40001 - 20000
+                                 for _ in range(frames * channels)])
+            neutral = (
+                ("pitch", lambda e: e.set_macro(PITCH_I, 127),
+                 {"pitch": 12.0}),
+                ("delay", lambda e: e.set_macro(DELAY_I, 64),
+                 {"delay_ms": 112.5 * 64 / 127}),
+                ("mix at unity", lambda e: e.set_macro(MIX_I, 64), {}),
+                ("patch 4", lambda e: e.program_change(4), {"patch": 4}),
+                ("patch 4 macro by macro",
+                 lambda e: [e.set_macro(i, m) for i, m in
+                            enumerate(PitchShifter.PATCHES[4][1])],
+                 {"patch": 4}),
+                ("patch 3 and back", lambda e: (e.program_change(3),
+                                                e.program_change(0)), {}),
+            )
+            for name, move, options in neutral:
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                try:
+                    count = counted(e)
+                    move(e)
+                    got = kc.samples(kc.render(e, frames))
+                finally:
+                    e.deinit()
+                self.assertEqual(count[0], 0, (rate, channels, name))
+                fresh = render(PitchShifter, values, rate, channels,
+                               frames, **options)
+                self.assertEqual(got, fresh, (rate, channels, name))
+            for index, midi in ((FINE_I, 3), (FEEDBACK_I, 90)):
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                try:
+                    count = counted(e)
+                    e.set_macro(index, midi)
+                finally:
+                    e.deinit()
+                self.assertEqual(count[0], 0, (rate, channels, index))
+            changing = (
+                ("mix 127", lambda e: e.set_macro(MIX_I, 127),
+                 {"mix": 2.0}),
+                ("mix 32", lambda e: e.set_macro(MIX_I, 32),
+                 {"mix": mix_of(32)}),
+                ("patch 6", lambda e: e.program_change(6), {"patch": 6}),
+            )
+            for name, move, options in changing:
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                try:
+                    count = counted(e)
+                    move(e)
+                    first = count[0]
+                    move(e)
+                    got = kc.samples(kc.render(e, frames))
+                finally:
+                    e.deinit()
+                self.assertEqual((first, count[0]), (1, 1),
+                                 (rate, channels, name))
+                fresh = render(PitchShifter, values, rate, channels, frames,
+                               **options)
+                self.assertEqual(got, fresh, (rate, channels, name))
+            # Once the output has been taken, no move re-arms.
+            e = PitchShifter(kc.feed(values, rate, channels).port)
+            try:
+                count = counted(e)
+                e.output
+                e.program_change(6)
+                e.set_macro(MIX_I, 127)
+            finally:
+                e.deinit()
+            self.assertEqual(count[0], 0, (rate, channels, "taken"))
+
+    def test_an_output_taken_before_a_patch_plays_the_old_level_at_first(
+            self):
+        # The limit the docstring discloses: a host that takes the output
+        # before it loads a patch hears the first block (256 frames) at the
+        # old level, and nothing after it. The class cannot see a pull, so
+        # it has stopped re-arming once the output has been taken.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            frames = 40 * BLOCK
+            dc = array("h", [6000] * (frames * channels))
+            slow = sine(frames, 40.0, rate, 12000, channels, phase=0.3)
+            for name, values in (("dc", dc), ("40 Hz", slow)):
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                try:
+                    e.output
+                    e.program_change(6)
+                    got = kc.samples(kc.render(e, frames))
+                finally:
+                    e.deinit()
+                fresh = render(PitchShifter, values, rate, channels, frames,
+                               patch=6)
+                differ = [n for n in range(frames)
+                          if got[n * channels:(n + 1) * channels]
+                          != fresh[n * channels:(n + 1) * channels]]
+                self.assertTrue(differ, (rate, channels, name))
+                self.assertLess(max(differ), BLOCK, (rate, channels, name))
+
     def test_the_voice_at_unity_after_a_pitch_move_sits_where_the_splice_left_it(
             self):
         # From a fresh start (test_mix_2_is_the_shifted_voice_alone) or a
@@ -1176,8 +1348,13 @@ def test_dry_through_shifter_is_red(self):
      ("test_the_dry_is_untouched", "test_dry_through_shifter_is_red",
       "test_a_hot_input_reaches_the_rail_at_mix_1")),
     ("Feedback stacks level too, far past the input: at Feedback 127, Delay "
-     "0 and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail.",
+     "0 and Mix 2 a noise burst peaking at -10.3 dBFS reaches the rail at "
+     "unison or an octave up, and comes within 4 dB of it at an octave down "
+     "or a fourth or fifth either way.",
      "test_feedback_near_its_top_stacks_level_far_past_the_input"),
+    ("If your host takes the output before it loads a patch or moves Mix, "
+     "the first 256 frames, 5 ms at 48 kHz, play at the old level.",
+     "test_an_output_taken_before_a_patch_plays_the_old_level_at_first"),
     ("A one-channel source gets a one-channel shifter with the same window.",
      "test_a_mono_source_is_one_channel_of_a_stereo_one"),
     ("Latency is zero samples: the dry is never delayed.",

From 2a8c3a895be581e28fe3f64a83f9c774bcff6723 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:16:20 -0500
Subject: [PATCH 54/76] Harmonizer: name CircuitPython's own pitch shifter in
 the reset line, tied to the E10 declared rows

---
 lib/audioeffects/rebuilt/harmonizer.py   | 2 ++
 tests/test_cpython_effects_harmonizer.py | 4 ++++
 2 files changed, 6 insertions(+)

diff --git a/lib/audioeffects/rebuilt/harmonizer.py b/lib/audioeffects/rebuilt/harmonizer.py
index 06437af..038101c 100644
--- a/lib/audioeffects/rebuilt/harmonizer.py
+++ b/lib/audioeffects/rebuilt/harmonizer.py
@@ -151,6 +151,8 @@ class Harmonizer(_component.Component):
     0 at Mix 0 or with every voice off.
     `reset()` empties the three lines, starts their splices where a new
     instance's start, and returns to patch 0.
+    On CircuitPython's own pitch shifter a reset does not restart the
+    splices.
     The class never reads the host's tempo.
     """
 
diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
index 4eb9462..eeb165e 100644
--- a/tests/test_cpython_effects_harmonizer.py
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -1454,6 +1454,10 @@ def test_the_stated_ceiling_covers_every_setting(self):
     ("`reset()` empties the three lines, starts their splices where a new "
      "instance's start, and returns to patch 0.",
      "TheSurface.test_reset_renders_as_fresh"),
+    ("On CircuitPython's own pitch shifter a reset does not restart the "
+     "splices.",
+     ("DECLARED:Harmonizer,E10-reset,P4",
+      "DECLARED:Harmonizer,E10-mix0,P4")),
     ("The class never reads the host's tempo.",
      "TheSurface.test_never_reads_the_tempo"),
 )

From 47dd60cbd51b8470a9ae2ffa346fa23687b989e3 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:29:13 -0500
Subject: [PATCH 55/76] PitchShifter: a reset or a return from Mix 0 no longer
 hands the first-block window back, so a Mix sweep after a reset keeps the
 repeats; the early-read sentence covers a patch right after a reset

---
 lib/audioeffects/rebuilt/pitchshifter.py   |  12 +--
 tests/test_cpython_effects_pitchshifter.py | 109 +++++++++++++++------
 2 files changed, 84 insertions(+), 37 deletions(-)

diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
index f575c59..cb7d687 100644
--- a/lib/audioeffects/rebuilt/pitchshifter.py
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -149,8 +149,9 @@ class PitchShifter(_component.Component):
     `reset()` empties the shifter and both delay lines and returns to
     patch 0.
     The class never reads the host's tempo.
-    If your host takes the output before it loads a patch or moves Mix, the
-    first 256 frames, 5 ms at 48 kHz, play at the old level.
+    If your host takes the output before it loads a patch or moves Mix, or
+    loads a patch right after a reset, the first 256 frames, 5 ms at
+    48 kHz, play at the old level.
 
     **Limits shared by the family.**
     A control that jumps makes the output step: move it in small steps from
@@ -221,7 +222,9 @@ def _build(self, pitch=7.0, fine=0.0, mix=1.0, delay_ms=0.0,
         #: Whether the host has asked for the output yet. Until it has,
         #: nothing has been pulled, and a control that moves a voice's
         #: level re-arms the graph so the level holds from frame 0. A reset
-        #: or a return from Mix 0 starts that window again.
+        #: or a return from Mix 0 does not start that window again: the
+        #: class cannot see a pull, and a host that keeps the node it took
+        #: would have every later Mix move empty the repeats.
         self._taken = False
         #: The two Mixer levels last handed to the voices.
         self._applied = None
@@ -476,8 +479,6 @@ def _route(self):
         if not self._wired:
             self._wire()
         elif self._rejoin():
-            # The graph was emptied: it is new again until it is pulled.
-            self._taken = False
             self._rearm()
         elif not self._taken and self._level_pair() != self._applied:
             # Not pulled yet: a level moved now would wait for its voice's
@@ -503,7 +504,6 @@ def reset(self):
         wired = self._wired
         _component.Component.reset(self)
         if wired:
-            self._taken = False
             self._rearm()
 
     @property
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
index 8d605ab..a3575e7 100644
--- a/tests/test_cpython_effects_pitchshifter.py
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -1042,38 +1042,77 @@ def both(e):
             self.assertEqual(got[12 * BLOCK * channels:], fresh,
                              (rate, channels))
 
-    def test_a_move_right_after_a_reset_is_a_fresh_instance_at_that_setting(
-            self):
-        # reset() makes the instance new again: until the next pull a patch
-        # or a Mix move re-arms it as it would a new one, so the voices play
-        # the new level from the first frame after the move.
+    def test_a_mix_sweep_after_a_reset_does_not_empty_the_repeats(self):
+        # A host that took the output once and keeps the node: a reset does
+        # not hand the re-arm window back, so Mix moves that change a level
+        # while it plays are ordinary moves and the repeats carry on.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(41)
+            blocks = 20
+            values = array("h", bytes(2 * blocks * BLOCK * channels))
+            for n in range(6 * BLOCK * channels):
+                values[n] = rng.next() % 40001 - 20000
+            sweep = (70, 76, 82, 88, 94, 100, 106, 112, 118, 124)
+            energies = []
+            rearms = []
+            for with_reset in (True, False):
+                e = PitchShifter(kc.feed(values, rate, channels).port)
+                try:
+                    count = [0]
+                    rearm = e._rearm
+
+                    def wrapped(count=count, rearm=rearm):
+                        count[0] += 1
+                        rearm()
+                    node = e.output
+                    out = []
+                    for k in range(blocks):
+                        if k == 3:
+                            if with_reset:
+                                e.reset()
+                            e.set_macro(FEEDBACK_I, 120)
+                            e.set_macro(DELAY_I, 20)
+                        if k == 5:
+                            e._rearm = wrapped
+                        if k >= 7:
+                            e.set_macro(MIX_I, sweep[k - 7] if k < 17 else 64)
+                        out.append(bytes(kc.audiocore.get_buffer(node)[1]))
+                    rearms.append(count[0])
+                    energies.append(sum(
+                        sum(x * x for x in memoryview(b).cast("h"))
+                        for b in out[8:17]))
+                finally:
+                    e.deinit()
+            self.assertEqual(rearms, [0, 0], (rate, channels))
+            self.assertGreater(energies[0], 0.25 * energies[1],
+                               (rate, channels, energies))
+
+    def test_a_patch_right_after_a_reset_plays_the_old_level_at_first(self):
+        # The limit the docstring discloses beside the early output read:
+        # a reset does not hand the first-block window back, so a patch
+        # loaded right after one plays its first block (256 frames) at the
+        # old level and nothing after it.
         for rate, channels in ((48000, 2), (22050, 1)):
             blocks = 30
             dc = array("h", [6000] * (blocks * BLOCK * channels))
             later = dc[12 * BLOCK * channels:]
-            for patch in range(len(PitchShifter.PATCHES)):
-                got = played(dc, rate, channels, blocks,
-                             {12: lambda e, p=patch: (e.reset(),
-                                                      e.program_change(p))})
-                fresh = render(PitchShifter, later, rate, channels,
-                               (blocks - 12) * BLOCK, patch=patch)
-                self.assertEqual(got[12 * BLOCK * channels:], fresh,
-                                 (rate, channels, "patch", patch))
-            for midi in (1, 32, 96, 127):
-                mix = _component.macro_value(
-                    (0.0, 2.0), _component.position_of_midi("BIPOLAR", midi))
-                got = played(dc, rate, channels, blocks,
-                             {12: lambda e, m=midi: (e.reset(),
-                                                     e.set_macro(MIX_I, m))})
-                fresh = render(PitchShifter, later, rate, channels,
-                               (blocks - 12) * BLOCK, mix=mix)
-                self.assertEqual(got[12 * BLOCK * channels:], fresh,
-                                 (rate, channels, "mix", midi))
-
-    def test_a_move_right_after_a_return_from_mix_0_is_a_fresh_instance(
+            got = played(dc, rate, channels, blocks,
+                         {12: lambda e: (e.reset(), e.program_change(6))})
+            fresh = render(PitchShifter, later, rate, channels,
+                           (blocks - 12) * BLOCK, patch=6)
+            got = got[12 * BLOCK * channels:]
+            differ = [n for n in range(len(fresh) // (2 * channels))
+                      if got[n * channels:(n + 1) * channels]
+                      != fresh[n * channels:(n + 1) * channels]]
+            self.assertTrue(differ, (rate, channels))
+            self.assertLess(max(differ), BLOCK, (rate, channels))
+
+    def test_a_patch_right_after_a_return_from_mix_0_plays_the_old_level(
             self):
-        # The return from Mix 0 re-arms the graph; a patch loaded before the
-        # next pull re-arms it again at the patch's levels.
+        # The return from Mix 0 re-arms the graph at the Mix it comes back
+        # to (test_a_return_from_mix_0_is_a_fresh_instance_at_that_mix); a
+        # patch loaded after it, once the output has been taken, is an
+        # ordinary move and plays its first block at the old level.
         for rate, channels in ((48000, 2), (22050, 1)):
             blocks = 30
             dc = array("h", [6000] * (blocks * BLOCK * channels))
@@ -1085,8 +1124,12 @@ def back(e):
                          {10: lambda e: e.set_macro(MIX_I, 0), 18: back})
             fresh = render(PitchShifter, dc[18 * BLOCK * channels:], rate,
                            channels, (blocks - 18) * BLOCK, patch=6)
-            self.assertEqual(got[18 * BLOCK * channels:], fresh,
-                             (rate, channels))
+            got = got[18 * BLOCK * channels:]
+            differ = [n for n in range(len(fresh) // (2 * channels))
+                      if got[n * channels:(n + 1) * channels]
+                      != fresh[n * channels:(n + 1) * channels]]
+            self.assertTrue(differ, (rate, channels))
+            self.assertLess(max(differ), BLOCK, (rate, channels))
 
     def test_only_a_move_that_changes_a_voice_level_re_arms(self):
         # Before the output is first taken, Pitch, Fine, Delay, Feedback and
@@ -1353,8 +1396,12 @@ def test_dry_through_shifter_is_red(self):
      "or a fourth or fifth either way.",
      "test_feedback_near_its_top_stacks_level_far_past_the_input"),
     ("If your host takes the output before it loads a patch or moves Mix, "
-     "the first 256 frames, 5 ms at 48 kHz, play at the old level.",
-     "test_an_output_taken_before_a_patch_plays_the_old_level_at_first"),
+     "or loads a patch right after a reset, the first 256 frames, 5 ms at "
+     "48 kHz, play at the old level.",
+     ("test_an_output_taken_before_a_patch_plays_the_old_level_at_first",
+      "test_a_patch_right_after_a_reset_plays_the_old_level_at_first",
+      "test_a_patch_right_after_a_return_from_mix_0_plays_the_old_level",
+      "test_a_mix_sweep_after_a_reset_does_not_empty_the_repeats")),
     ("A one-channel source gets a one-channel shifter with the same window.",
      "test_a_mono_source_is_one_channel_of_a_stereo_one"),
     ("Latency is zero samples: the dry is never delayed.",

From 524c4fe09b7bf9af2ea4515a104a0e01a0c1039a Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:36:06 -0500
Subject: [PATCH 56/76] PitchShifter: patches and a rack's put-back share one
 refresh (_apply_positions), a put-back at Mix 0 waits to be armed; a rack
 holding one resets to a fresh rack's render

---
 lib/audioeffects/rebuilt/pitchshifter.py | 22 +++++++----
 tests/test_cpython_effects_rack.py       | 48 ++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/lib/audioeffects/rebuilt/pitchshifter.py b/lib/audioeffects/rebuilt/pitchshifter.py
index cb7d687..44a26af 100644
--- a/lib/audioeffects/rebuilt/pitchshifter.py
+++ b/lib/audioeffects/rebuilt/pitchshifter.py
@@ -439,17 +439,18 @@ def _apply_macro(self, index, position):
         if self._ready:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the graph once."""
+    def _apply_positions(self, positions, patch_index):
+        """Set the knobs whole, then refresh the graph once: a patch and a
+        rack's put-back after a reset both land here, so neither passes
+        through a Mix 0 or a half-moved interval on the way."""
         ready = self._ready
         self._ready = False
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._ready = ready
-        if ready and type(self).PATCHES.get(index) is not None:
+        if ready:
             self._refresh()
 
     def _refresh(self):
@@ -503,8 +504,15 @@ def reset(self):
         from there as a new instance does."""
         wired = self._wired
         _component.Component.reset(self)
-        if wired:
+        if not wired:
+            return
+        if self._mix() > 0.0:
             self._rearm()
+        else:
+            # A rack's put-back can restore Mix 0: the output is the
+            # source's reader, and the graph behind it waits to be armed
+            # when Mix comes back up, as it does in a new instance.
+            self._stranded = True
 
     @property
     def tail_samples(self):
diff --git a/tests/test_cpython_effects_rack.py b/tests/test_cpython_effects_rack.py
index b33d2b9..98bca3f 100644
--- a/tests/test_cpython_effects_rack.py
+++ b/tests/test_cpython_effects_rack.py
@@ -1100,6 +1100,51 @@ def run(rack):
     return wrong
 
 
+def t4_pitchshifter(cls, rate, channels):
+    """A PitchShifter in a rack comes back from the rack's reset as built
+    and re-armed: after its knobs were moved it renders what the freshly
+    built rack does, whether it was built playing or at Mix 0, and a Mix
+    move after the reset keeps the repeats."""
+    wrong = []
+    frames = 14000
+    # A held level under the clicks, so the signal never crosses zero: a
+    # level a re-arm leaves unplayed waits for a crossing it does not get.
+    values = clicks(frames, channels, range(512, frames, 2400))
+    for i in range(len(values)):
+        values[i] += 6000
+    shifter = rebuilt.module_class("PitchShifter")
+    cases = (
+        ("defaults", {}, ((0, 40), (1, 100), (2, 90), (3, 50), (4, 90)),
+         ()),
+        ("off the defaults", {"pitch": -5.0, "fine": 20.0, "mix": 1.5,
+                              "delay_ms": 30.0, "feedback": 0.4,
+                              "window_ms": 20.0},
+         ((0, 100), (4, 0), (2, 20)), ()),
+        ("built at Mix 0", {"mix": 0.0, "pitch": 4.0},
+         ((2, 100), (4, 80)), ()),
+        ("Mix 0 after the reset", {"mix": 1.0, "feedback": 0.5},
+         ((0, 20), (2, 40)), ((2, 0), (2, 100))),
+    )
+    for label, options, moves, after in cases:
+        chain = ((shifter, options),)
+
+        def before(rack, moves=moves):
+            for index, value in moves:
+                rack.effects[0].set_macro(index, value)
+
+        def run(rack, after=after):
+            out = pull(rack.output, 4000, channels)
+            for index, value in after:
+                rack.effects[0].set_macro(index, value)
+                out += pull(rack.output, 3000, channels)
+            return out
+
+        for line in _against_fresh(cls, rate, channels, chain, values, run,
+                                   before):
+            wrong.append("PitchShifter, %s: %s" % (label, line))
+    return wrong
+
+
 def t5_patch(cls):
     """A `patch=` the rack refuses releases every pedal it had built."""
     wrong = []
@@ -1297,6 +1342,9 @@ def test_exact_constructor_values_come_back(self):
     def test_a_stereo_widener_comes_back_with_its_exact_delay(self):
         self.assertEqual(t4_widener(Rack, 48000, 2), [])
 
+    def test_a_pitch_shifter_comes_back_re_armed_and_as_built(self):
+        self.assertEqual(t4_pitchshifter(Rack, 48000, 2), [])
+
     def test_reset_as_built_faults_are_red(self):
         self.assertNotEqual(t4_mix0(PutBackRack, 48000, 2), [])
         for plant in (PutBackRack, PositionsOnlyRack):

From ae46a41d39c675d2bfe31fba608465dbb6ea43ed Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:44:09 -0500
Subject: [PATCH 57/76] Octaver: a patch and a return from the wire start where
 a fresh instance does

patch= now lands before the voices are armed, and the all-pass is cleared
after arming, so its first block of the source starts at the Tracking in
force instead of gliding there from patch 0's 90 Hz. A return from the
wire at patches 3 and 4 (Tracking 50 and 200 Hz) and a patch before the
first pull now render as a fresh instance built there.

The lifecycle matrix names Octave 1 as the Octaver's Mix keyword, and its
E12 moves to patches 1, 2 and 5 join the declared P1 rows.
---
 lib/audioeffects/rebuilt/octaver.py   | 15 ++++++-
 tests/support/lifecycle.py            | 13 ++++++
 tests/test_cpython_effects_octaver.py | 59 +++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 2 deletions(-)

diff --git a/lib/audioeffects/rebuilt/octaver.py b/lib/audioeffects/rebuilt/octaver.py
index 4a3990e..c378ea1 100644
--- a/lib/audioeffects/rebuilt/octaver.py
+++ b/lib/audioeffects/rebuilt/octaver.py
@@ -319,11 +319,15 @@ def _build(self, direct=1.0, octave1=0.7, octave2=0.0, tracking_hz=90.0,
             if self._macros[i] != position:
                 self._macros[i] = position
                 self._apply_macro(i, position)
+        # The patch lands before the voices are armed, so the instance
+        # starts at it: loaded after, the all-pass walked its first block
+        # from patch 0's Tracking and each level waited for a crossing, and
+        # `patch=` did not build what the patch's own values build.
+        if patch is not None:
+            self.program_change(patch)
 
         self._ready = True
         self._route()
-        if patch is not None:
-            self.program_change(patch)
 
     def _grid(self, asked):
         """Each constructor value as its knob's nearest MIDI step: NaN is
@@ -518,6 +522,13 @@ def _arm(self):
         voices[2].play(self._tone2, loop=True)
         self._pull()
         self._in.play(self._adapter)
+        # The all-pass glides a Tracking move over one block from the
+        # coefficient it last played at. It has played only the arming's
+        # zeros, so it holds nothing to keep: cleared, its first block of
+        # the source starts at the Tracking then in force, as a rejoin's
+        # does, and a move before the first pull lands at once.
+        if self._allpass is not None:
+            audiocore.reset_buffer(self._allpass)
 
     def _pull(self):
         """Pull one block from the mixer and drop it.
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 7c4f575..dc993ce 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -150,6 +150,18 @@
     ("Octaver", "E6-p5", "P1"):
         "the event changes to patch 5, where Octave 1 at 0 is a level move,"
         " not the wire, so the output is not the source by design",
+    ("Octaver", "E12-p1", "P1"):
+        "the move before the first pull is to patch 1, where Octave 1 at 0"
+        " is a level move, not the wire, so the output is not the source by"
+        " design",
+    ("Octaver", "E12-p2", "P1"):
+        "the move before the first pull is to patch 2, where Octave 1 at 0"
+        " is a level move, not the wire, so the output is not the source by"
+        " design",
+    ("Octaver", "E12-p5", "P1"):
+        "the move before the first pull is to patch 5, where Octave 1 at 0"
+        " is a level move, not the wire, so the output is not the source by"
+        " design",
     ("Octaver", "E11-mix+patch", "P1"):
         "the event ends on patch 5, where Octave 1 at 0 is a level move,"
         " not the wire, so the output is not the source by design",
@@ -826,6 +838,7 @@ def fresh_position(cls, index, midi):
 #: `mix`.
 MIX_KEYWORD = {
     "SlapbackDelay": "level",
+    "Octaver": "octave1",
 }
 
 
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
index 6ba3f01..c8ebbe6 100644
--- a/tests/test_cpython_effects_octaver.py
+++ b/tests/test_cpython_effects_octaver.py
@@ -1174,6 +1174,65 @@ def test_reset_renders_as_fresh(self):
         e.deinit()
         self.assertEqual(after, render(Octaver, values, rate, 1))
 
+    def _values_of(self, patch):
+        """The constructor keywords that build `patch`'s knobs."""
+        from audioeffects import _component
+        names = ("direct", "octave1", "octave2", "tracking_hz", "tone1_hz",
+                 "tone2_hz", "sensitivity_db")
+        grid = Octaver.PATCHES[patch][1]
+        return {names[i]: _component.macro_value(
+            Octaver._MACRO_RANGES[i],
+            _component.position_of_midi("UNIPOLAR", grid[i]))
+            for i in range(7)}
+
+    def test_a_patch_builds_as_its_values(self):
+        # `patch=` lands every knob before the voices are armed: the
+        # all-pass glides a Tracking move over one block, so a patch
+        # loaded after arming walked its first block from patch 0's 90 Hz.
+        for rate in RATES:
+            values = self._material(rate, 1)
+            for patch in sorted(Octaver.PATCHES):
+                with self.subTest(rate=rate, patch=patch):
+                    self.assertEqual(
+                        render(Octaver, values, rate, 1,
+                               options={"patch": patch}),
+                        render(Octaver, values, rate, 1,
+                               options=self._values_of(patch)))
+
+    def test_a_patch_before_the_first_pull_renders_as_fresh(self):
+        # Arming plays only silence, so the all-pass has heard nothing yet:
+        # a Tracking move before the first pull lands at once, not walked
+        # over the first block from where the arming left it. (Patches 1,
+        # 2 and 5 move Direct, which the mixer takes half a block late.)
+        for rate in RATES:
+            values = self._material(rate, 1)
+            for patch in (0, 3, 4):
+                with self.subTest(rate=rate, patch=patch):
+                    self.assertEqual(
+                        render(Octaver, values, rate, 1, patch=patch),
+                        render(Octaver, values, rate, 1,
+                               options={"patch": patch}))
+
+    def test_a_return_from_the_wire_renders_as_fresh(self):
+        # Octave 1 to 0 is the wire at patches 0, 3 and 4; the way back
+        # renders what a fresh instance built at the patch renders.
+        for rate in RATES:
+            values = self._material(rate, 1)
+            n = len(values)
+            gap = array("h", bytes(2 * BLOCK * 16))
+            for patch in (0, 3, 4):
+                with self.subTest(rate=rate, patch=patch):
+                    feed = kc.feed(values + gap + values, rate, 1)
+                    e = Octaver(feed.port, sample_rate=rate, patch=patch)
+                    kc.render(e, n)
+                    e.set_macro(OCT1, 0)
+                    kc.render(e, len(gap))
+                    e.set_macro(OCT1, Octaver.PATCHES[patch][1][OCT1])
+                    after = kc.samples(kc.render(e, n))
+                    e.deinit()
+                    self.assertEqual(after, render(
+                        Octaver, values, rate, 1, options={"patch": patch}))
+
     def test_never_reads_the_tempo(self):
         calls = []
 

From 31412a1fbfc6993d7e7ada4a6ea66c737199477f Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:54:12 -0500
Subject: [PATCH 58/76] ShimmerHall: a reset, a return from Mix 0 and a Mix
 move before the first pull play the dry at the new level from frame 0; T1
 reads the exact Bloom the constructor keeps

---
 lib/audioeffects/rebuilt/shimmerhall.py   |  70 ++++++++++-
 tests/test_cpython_effects_shimmerhall.py | 145 +++++++++++++++++++++-
 2 files changed, 206 insertions(+), 9 deletions(-)

diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index fdf2036..782bb81 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -42,7 +42,9 @@
 
 A control that jumps makes the output step: move it in small steps from the
 host if you need it smooth. Moving Character or Size empties the hall: the
-tail drops and the dry carries on.
+tail drops and the dry carries on. If your host takes the output before it
+loads a patch or moves Mix, the first 256 frames, 5 ms at 48 kHz, play at the
+old level.
 
 Interval is a fixed shift in semitones, with no key awareness. Both
 shifters splice, so the shifted copy has a slight flutter. At a lower
@@ -319,6 +321,15 @@ def _build(self, character="bloom", shimmer=SHIMMER, rise=RISE,
         self._ready = False
         #: True once the voices have been played (`_wire`).
         self._wired = False
+        #: Whether the host has asked for the output yet. Until it has,
+        #: nothing has been pulled, and a control that moves a voice's level
+        #: re-arms the graph so the level holds from frame 0. A reset or a
+        #: return from Mix 0 does not start that window again: the class
+        #: cannot see a pull, and a host that keeps the node it took would
+        #: have every later level move empty the hall.
+        self._taken = False
+        #: The two Mixer levels last handed to the voices.
+        self._applied = None
         #: True while the wet chain is Rise's.
         self._rise = None
         #: What each node was last handed, by name.
@@ -535,11 +546,17 @@ def _refresh(self):
             self._clear_nodes(only=(self._shift, self._fd, self._hall))
         self._route()
 
-    def _levels(self):
+    def _level_pair(self):
+        """The dry and the hall's Mixer levels at this Mix."""
         mix = self._mix()
+        return (min(1.0, 2.0 - mix), min(1.0, mix))
+
+    def _levels(self):
         voices = self._mixer.voice
-        voices[0].level = min(1.0, 2.0 - mix)
-        voices[1].level = min(1.0, mix)
+        pair = self._level_pair()
+        voices[0].level = pair[0]
+        voices[1].level = pair[1]
+        self._applied = pair
 
     def _route(self):
         """Point the output at the source's reader at Mix 0, or at the
@@ -549,11 +566,51 @@ def _route(self):
             return
         if not self._wired:
             self._wire()
+        elif self._rejoin():
+            self._rearm()
+        elif not self._taken and self._level_pair() != self._applied:
+            # Not pulled yet: a level moved now would wait for its voice's
+            # next zero crossing, a block of the old level, where an
+            # instance built at this setting plays the new one from frame 0.
+            # A move that leaves both levels alone has nothing to wait for.
+            self._rearm()
         else:
             self._levels()
-            self._rejoin()
         self._output = self._tail
 
+    @property
+    def output(self):
+        """The node the host plays. Asking for it is the host's first step
+        to pulling, so from here a level that moves is an ordinary move."""
+        self._check_live()
+        self._taken = True
+        return self._output
+
+    def reset(self):
+        """Empty the hall, the line and the shifter, return to patch 0, and
+        play from there as a new instance does."""
+        wired = self._wired
+        _component.Component.reset(self)
+        if not wired:
+            return
+        if self._mix() > 0.0:
+            self._rearm()
+        else:
+            # A rack's put-back can restore Mix 0: the output is the
+            # source's reader, and the graph behind it waits to be armed
+            # when Mix comes back up, as it does in a new instance.
+            self._stranded = True
+
+    def _rearm(self):
+        """Wire the graph again as the constructor does, once it has been
+        cleared: a voice's new level is picked up at its next zero crossing
+        unless the voice is played again, so a graph that is cleared while
+        a level changes would otherwise carry the old level into the first
+        frames. The input goes back to silence first, so no frame is taken
+        from the borrowed source."""
+        self._in.play(self._hush)
+        self._wire()
+
     def _wire(self):
         """Play the voices, the first time the output reaches the mixer.
 
@@ -575,6 +632,9 @@ def _wire(self):
         self._in.play(self._head)
         self._clear_nodes(only=(self._shift, self._fd, self._hall))
         self._wired = True
+        # A control touched at Mix 0 before the first wiring marked the
+        # graph stranded; wiring is what that mark waits for.
+        self._stranded = False
 
     def _pull(self):
         """Pull one block from the mixer and drop it. `_tail` forwards no
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 010d95f..886d0e8 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -75,9 +75,11 @@ def law_frames(ms, rate):
 
 
 def law_bloom(ms):
-    """Bloom on its 0-127 grid: 20 to 800 ms, log."""
-    step = int(math.log(ms / 20.0) / math.log(40.0) * 127.0 + 0.5)
-    return 20.0 * 40.0 ** (step / 127.0)
+    """The Bloom a constructor value plays: exactly the ms it was given.
+    The constructor keeps a value off the 0-127 grid as the knob's own
+    position, between steps, so 200 ms plays 200.00 ms and not the 198.42
+    of the nearest step; only a MIDI move lands on a step."""
+    return ms
 
 
 def law_rise(rise):
@@ -342,7 +344,8 @@ def t2_read(cls, rate, character, interval, seed):
     """The energy-weighted mean shift of d = (Shimmer 1) - (Shimmer 0), in
     semitones, over the 500 ms from Bloom."""
     f0, offset = seed_set(seed)
-    bloom = law_bloom(275.0)
+    # The card's patch-0 Bloom, which a default-built instance plays.
+    bloom = 20.0 * 40.0 ** (90.0 / 127.0)
     start = law_frames(bloom, rate) + offset
     span = law_frames(500.0, rate)
     frames = start + span
@@ -879,6 +882,136 @@ def test_a_size_move_empties_the_hall(self):
             self.assertGreater(max(abs(x) for x in ringing), 20, character)
             self.assertEqual(max(abs(x) for x in after), 0, character)
 
+    # -- the dry's level from frame 0: a reset, a return from Mix 0, a
+    # Mix move before the first pull ------------------------------------
+
+    def _dc(self, rate, channels, blocks):
+        return array("h", [6000] * (blocks * BLOCK * channels))
+
+    def _same_as_fresh(self, build, moves, fresh_from, fresh_options,
+                       blocks=14, name=""):
+        """Render `build` with `moves`, and a fresh instance built with
+        `fresh_options` fed the DC from block `fresh_from` on; the two must
+        agree byte for byte from there."""
+        for rate, channels in ((48000, 2), (22050, 1)):
+            values = self._dc(rate, channels, blocks)
+            feed = kc.feed(values, rate, channels)
+            e = build(feed.port)
+            try:
+                out = kc.samples(kc.render(e, blocks * BLOCK, moves))
+            finally:
+                e.deinit()
+            start = fresh_from * BLOCK * channels
+            want = render(ShimmerHall, values[start:], rate, channels,
+                          (blocks - fresh_from) * BLOCK, **fresh_options)
+            got = out[start:]
+            differ = [n for n in range(len(want) // channels)
+                      if got[n * channels:(n + 1) * channels]
+                      != want[n * channels:(n + 1) * channels]]
+            self.assertEqual(differ[:3], [], (name, rate, channels,
+                                              len(differ)))
+
+    def test_a_reset_from_mix_2_plays_the_dry_from_frame_0(self):
+        self._same_as_fresh(
+            lambda port: ShimmerHall(port, mix=2.0),
+            {6: lambda e: e.reset()}, 6, {}, name="reset from Mix 2")
+
+    def test_a_reset_before_the_first_pull_plays_the_dry_from_frame_0(self):
+        self._same_as_fresh(
+            lambda port: ShimmerHall(port, mix=2.0),
+            {0: lambda e: e.reset()}, 0, {}, name="reset before a pull")
+
+    def test_a_return_from_mix_0_plays_the_dry_from_frame_0(self):
+        self._same_as_fresh(
+            ShimmerHall,
+            {2: lambda e: e.set_macro(MIX_I, 0),
+             6: lambda e: e.set_macro(MIX_I, 127)}, 6, dict(mix=2.0),
+            name="Mix 0 then 127")
+
+    def test_a_mix_move_before_the_first_pull_plays_the_dry_from_frame_0(
+            self):
+        self._same_as_fresh(
+            ShimmerHall, {0: lambda e: e.set_macro(MIX_I, 127)}, 0,
+            dict(mix=2.0), name="Mix 127 before the first pull")
+        self._same_as_fresh(
+            ShimmerHall, {0: lambda e: e.program_change(1)}, 0,
+            dict(patch=1), name="patch 1 before the first pull")
+
+    def test_a_reset_from_rise_plays_as_a_new_instance(self):
+        self._same_as_fresh(
+            lambda port: ShimmerHall(port, character="rise", mix=2.0),
+            {6: lambda e: e.reset()}, 6, {}, name="reset from Rise")
+
+    def test_only_a_move_that_changes_a_voice_level_re_arms(self):
+        # Before the output is first taken a move that changes a Mixer
+        # level re-arms the graph, once; a move that leaves both levels
+        # alone does not. After it is taken, or after a reset, none does.
+        def counted(e):
+            count = [0]
+            rearm = e._rearm
+
+            def wrapped():
+                count[0] += 1
+                rearm()
+            e._rearm = wrapped
+            return count
+        for name, move, rearms in (
+                ("shimmer", lambda e: e.set_macro(SHIMMER_I, 127), 0),
+                ("interval", lambda e: e.set_macro(INTERVAL_I, 0), 0),
+                ("patch 2", lambda e: e.program_change(2), 1),
+                ("mix 127", lambda e: e.set_macro(MIX_I, 127), 1)):
+            e = ShimmerHall(_port())
+            try:
+                count = counted(e)
+                move(e)
+                move(e)
+            finally:
+                e.deinit()
+            self.assertEqual(count[0], rearms, name)
+        e = ShimmerHall(_port(), mix=2.0)
+        try:
+            count = counted(e)
+            e.output
+            e.program_change(2)
+            e.set_macro(MIX_I, 127)
+            self.assertEqual(count[0], 0, "taken")
+            e.reset()
+            self.assertEqual(count[0], 1, "the reset itself")
+            e.set_macro(MIX_I, 127)
+            e.program_change(2)
+            self.assertEqual(count[0], 1, "after a reset")
+        finally:
+            e.deinit()
+
+    def test_an_output_taken_before_mix_moves_plays_the_old_level_at_first(
+            self):
+        # The limit the docstring discloses: a host that takes the output
+        # before it moves Mix or loads a patch hears the first block (256
+        # frames) at the old level, and nothing after it.
+        for rate, channels in ((48000, 2), (22050, 1)):
+            blocks = 14
+            values = self._dc(rate, channels, blocks)
+            for name, options, move, fresh in (
+                    ("Mix 127", {}, lambda e: e.set_macro(MIX_I, 127),
+                     dict(mix=2.0)),
+                    ("patch 0 from Mix 2", dict(mix=2.0),
+                     lambda e: e.program_change(0), {})):
+                e = ShimmerHall(kc.feed(values, rate, channels).port,
+                                **options)
+                try:
+                    e.output
+                    move(e)
+                    got = kc.samples(kc.render(e, blocks * BLOCK))
+                finally:
+                    e.deinit()
+                want = render(ShimmerHall, values, rate, channels,
+                              blocks * BLOCK, **fresh)
+                differ = [n for n in range(blocks * BLOCK)
+                          if got[n * channels:(n + 1) * channels]
+                          != want[n * channels:(n + 1) * channels]]
+                self.assertTrue(differ, (name, rate, channels))
+                self.assertLess(max(differ), BLOCK, (name, rate, channels))
+
     def test_the_input_ceiling(self):
         # Every level at the top, a steady 100 Hz square: clean at -24
         # dBFS, on the rail at -12.
@@ -1104,6 +1237,10 @@ def test_late_dry_is_red(self):
     ("A control that jumps makes the output step: move it in small steps "
      "from the host if you need it smooth.",
      "DECLARED:ShimmerHall,E6-,P5"),
+    ("If your host takes the output before it loads a patch or moves Mix, "
+     "the first 256 frames, 5 ms at 48 kHz, play at the old level.",
+     ("test_an_output_taken_before_mix_moves_plays_the_old_level_at_first",
+      "test_only_a_move_that_changes_a_voice_level_re_arms")),
     ("Interval is a fixed shift in semitones, with no key awareness.",
      "test_interval_has_five_zones"),
     ("A value outside a macro's span clamps to the nearer stop, and NaN "

From 3701a1e11d2a8cc2db0c83e29f7c77600b1549a8 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 04:57:52 -0500
Subject: [PATCH 59/76] Kit paperwork: a card's range row (1-3, Voice 1 ...
 Voice 3) names one macro per index

---
 tests/support/kit_paperwork.py | 27 ++++++++++++++++++++++-----
 tests/test_kit.py              | 13 +++++++++++++
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/tests/support/kit_paperwork.py b/tests/support/kit_paperwork.py
index 2170edd..184a561 100644
--- a/tests/support/kit_paperwork.py
+++ b/tests/support/kit_paperwork.py
@@ -224,13 +224,30 @@ def card_surface(text):
             continue
         if not "".join(cells).strip("-: "):
             continue
+        words = cells[header.index("Mode")].replace(",", " ").split()
+        mode = words[0].upper() if words else ""
+        number = cells[header.index("#")].replace("\u2013", "-")
+        label = cells[header.index("Label")].replace("`", "").strip()
+        if "-" in number:
+            # A range row: "1-3 | `Voice 1` ... `Voice 3`" names one macro
+            # per index, the label's trailing number counting with it.
+            try:
+                first, last = (int(n) for n in number.split("-", 1))
+            except ValueError:
+                continue
+            stem = label.split("\u2026")[0].split("...")[0].strip()
+            base = stem.rstrip("0123456789").rstrip()
+            start = stem[len(base):].strip()
+            for step, index in enumerate(range(first, last + 1)):
+                name = ("%s %d" % (base, int(start) + step) if start
+                        else base)
+                rows.append((index, name, mode))
+            continue
         try:
-            index = int(cells[header.index("#")])
-        except (ValueError, IndexError):
+            index = int(number)
+        except ValueError:
             continue
-        label = cells[header.index("Label")].strip("`").strip()
-        words = cells[header.index("Mode")].replace(",", " ").split()
-        rows.append((index, label, words[0].upper() if words else ""))
+        rows.append((index, label.strip(), mode))
     return rows if header is not None else None
 
 
diff --git a/tests/test_kit.py b/tests/test_kit.py
index 85b8200..18252f2 100644
--- a/tests/test_kit.py
+++ b/tests/test_kit.py
@@ -545,6 +545,19 @@ def test_the_surface_against_the_card(self):
                                       "| # | Trait |\n|---|---|\n"),
                          {"surface": "na(no surface table in section 3)"})
 
+    def test_a_range_row_names_one_macro_per_index(self):
+        rows = kit_paperwork.card_surface(
+            "## 3. The surface\n\n| # | Label | Mode |\n|---|---|---|\n"
+            "| 0 | `Pitch` | BIPOLAR |\n"
+            "| 1\u20133 | `Voice 1` \u2026 `Voice 3` | BIPOLAR |\n"
+            "| 4-5 | `Level 1` ... `Level 2` | UNIPOLAR |\n")
+        self.assertEqual(rows, [(0, "Pitch", "BIPOLAR"),
+                                (1, "Voice 1", "BIPOLAR"),
+                                (2, "Voice 2", "BIPOLAR"),
+                                (3, "Voice 3", "BIPOLAR"),
+                                (4, "Level 1", "UNIPOLAR"),
+                                (5, "Level 2", "UNIPOLAR")])
+
     def test_the_citation_forms(self):
         found = kit_paperwork.citations(
             "`src/shared/a.c:344`, called at :529 (`b.h:3-5`, `:7`); "

From 180180771ba1f25a33de6ecf655023487f43c670 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 05:00:29 -0500
Subject: [PATCH 60/76] AirSpace: a whole-step check that takes inf and NaN

---
 lib/audioeffects/rebuilt/airspace.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
index cadefd0..0c7947c 100644
--- a/lib/audioeffects/rebuilt/airspace.py
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -386,8 +386,10 @@ def set_macro(self, index, value, channel=0, note_id=-1,
         try:
             position = _component.position_of_midi("UNIPOLAR", value)
             if abs(position - self._macros[index]) > STEP_TOLERANCE:
-                self._snap[index] = abs(value - round(value)) <= 127.0 * (
-                    STEP_TOLERANCE)
+                fraction = value % 1.0
+                limit = 127.0 * STEP_TOLERANCE
+                self._snap[index] = (fraction <= limit
+                                     or fraction >= 1.0 - limit)
             _component.Component.set_macro(
                 self, index, value, channel, note_id, sample_position)
         except Exception:

From d565ebcbc9aaa86fe020643e62d7504aeaa6fadb Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 05:08:17 -0500
Subject: [PATCH 61/76] PitchShifter: the lifecycle and kit tables on the
 landing branch's format: the CircuitPython-only rows scoped, the E12 and PR
 cells of its own splice, the Feedback-top ceiling cells

---
 tests/support/kit_common.py | 26 ++++++-----
 tests/support/lifecycle.py  | 91 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 105 insertions(+), 12 deletions(-)

diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index bd85eed..34b0529 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -62,19 +62,23 @@
 # -10.3 dBFS reaches the rail at unison or an octave up, and comes within
 # 4 dB of it at an octave down or a fourth or fifth either way"), and
 # test_feedback_near_its_top_stacks_level_far_past_the_input holds it at each
-# Pitch named. The square, sine and DC cells there, at every rate and channel
-# count.
-for _material in ("square", "sine", "dc"):
+# Pitch named. Every material (the square, sine and DC, and the squares at
+# the wider periods) and each combination that puts Feedback at 127 (alone,
+# with the levels at 127, and with every macro at 127), at every rate and
+# channel count; the cells with Feedback below its top stay live.
+for _material in ("square", "sine", "dc", "sq41", "sq55", "sq82", "sq110",
+                  "sq147"):
     for _rate in RATES:
         for _channels in CHANNELS:
-            DECLARED[("PitchShifter", "ceiling", "%s/%d/%d/m4=127" % (
-                _material, _rate, _channels))] = (
-                "Feedback 0.95 stacks repeats on the dry, up to 21 times the"
-                " input's peak: the class docstring says Feedback stacks"
-                " level far past the input, a -10.3 dBFS noise burst"
-                " reaching the rail at Feedback 127, Delay 0 and Mix 2"
-                " (test_feedback_near_its_top_stacks_level_far_past_the_"
-                "input)")
+            for _cell in ("m4=127", "lv=127+m4=127", "all=127"):
+                DECLARED[("PitchShifter", "ceiling", "%s/%d/%d/%s" % (
+                    _material, _rate, _channels, _cell))] = (
+                    "Feedback 0.95 stacks repeats on the dry, up to 21"
+                    " times the input's peak: the class docstring says"
+                    " Feedback stacks level far past the input, a -10.3"
+                    " dBFS noise burst reaching the rail at Feedback 127,"
+                    " Delay 0 and Mix 2 (test_feedback_near_its_top_stacks_"
+                    "level_far_past_the_input)")
 
 CPYTHON = sys.implementation.name == "cpython"
 
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index a8c2262..60bb8c0 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -144,6 +144,90 @@
         " pull changes the Mixer levels and is re-armed, and CircuitPython's"
         " PitchShift keeps its positions (28 of the 32 cells; the four that"
         " start at patch 2 are ok)",
+    ("PitchShifter", "E12-p1", "P4", "circuitpython"):
+        "CircuitPython only: patch 1 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-p1", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
+    ("PitchShifter", "E12-p2", "P4", "circuitpython"):
+        "CircuitPython only: patch 2 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-p2", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
+    ("PitchShifter", "E12-p3", "P4", "circuitpython"):
+        "CircuitPython only: patch 3 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-p3", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
+    ("PitchShifter", "E12-p5", "P4", "circuitpython"):
+        "CircuitPython only: patch 5 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-p5", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
+    ("PitchShifter", "E12-p6", "P4", "circuitpython"):
+        "CircuitPython only: patch 6 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-p6", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
+    ("PitchShifter", "E12-mix127", "P4", "circuitpython"):
+        "CircuitPython only: Mix 127 before the first pull moves the interval"
+        " or the Mixer levels, so the shifter is primed again (a level move"
+        " re-arms the graph) after the constructor primed it at the old"
+        " ratio, and CircuitPython's own PitchShift keeps its read position"
+        " through a clear, so it sits off the splice phase of an instance"
+        " built at the setting; patch 4 and the defaults, which change"
+        " neither, match, and CPython and MicroPython are ok (ruled a"
+        " CircuitPython-own difference)",
+    ("PitchShifter", "E12-mix127", "PF", "circuitpython"):
+        "CircuitPython only: the first block carries the same splice-phase"
+        " difference as P4 (the shifter is primed again and CircuitPython's own"
+        " PitchShift keeps its positions); which rates show it in the first"
+        " block depends on where the phase lands",
     ("PitchShifter", "E4-m2=", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
         " makes the output step (Mix)",
@@ -449,7 +533,12 @@
 #: excused only here, never in DECLARED: a class NAME -> the free-running
 #: phase that keeps it from matching a fresh instance, named (an LFO, a
 #: wow table). A red PR cell of a class named here prints `decl`.
-FREE_PHASE = {}
+FREE_PHASE = {
+    "PitchShifter": "the splice phase of CircuitPython's own PitchShift,"
+                    " which a clear does not restart: a reset or a return"
+                    " from Mix 0 leaves it where it was, and a fresh"
+                    " instance starts at 0 (CPython and MicroPython match)",
+}
 
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
 

From 9423287d0b14380e2ab5487de05a5f06bd1c3c18 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 05:08:49 -0500
Subject: [PATCH 62/76] Kit: declare PitchShifter's BIPOLAR Mix against its
 card (a recorded departure)

---
 tests/support/kit_common.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/support/kit_common.py b/tests/support/kit_common.py
index 34b0529..0fe5082 100644
--- a/tests/support/kit_common.py
+++ b/tests/support/kit_common.py
@@ -29,6 +29,10 @@
 #: cell prints `decl` and is counted as a declared exception. Nothing else
 #: skips a cell.
 DECLARED = {
+    ("PitchShifter", "paperwork", "surface-m2"):
+        "Mix is BIPOLAR so MIDI 64 is exactly 1 (the dry at unity at the"
+        " defaults); the card's section 3 says UNIPOLAR and is superseded"
+        " on that point by a recorded ruling",
     ("StereoWidener", "plants", "H3/"):
         "delay_slew acts only while a Delay move walks the read head, and"
         " the kit's render never moves a control; H3's own test shows the"

From 3e24f988a44a1945221fd4fd4ea7d7bb79904798 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 05:16:15 -0500
Subject: [PATCH 63/76] ShimmerHall: patches and a rack's put-back share one
 refresh (_apply_positions); the P4 reasons name the shifter's splice restart;
 the CircuitPython-only splice-phase rows; a rack holding it resets to a fresh
 rack's render

---
 lib/audioeffects/rebuilt/shimmerhall.py   | 13 +++---
 tests/support/lifecycle.py                | 54 ++++++++++++++++++-----
 tests/test_cpython_effects_shimmerhall.py | 43 ++++++++++++++++++
 3 files changed, 94 insertions(+), 16 deletions(-)

diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index 782bb81..7da4dfd 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -477,17 +477,18 @@ def _apply_macro(self, index, position):
         if self._ready:
             self._refresh()
 
-    def program_change(self, index, channel=0, note_id=-1,
-                       sample_position=0):
-        """Apply patch `index` whole, then refresh the graph once."""
+    def _apply_positions(self, positions, patch_index):
+        """Set the knobs whole, then refresh the graph once: a patch and a
+        rack's put-back after a reset both land here, so neither passes
+        through a Mix 0 or a half-moved Character on the way."""
         ready = self._ready
         self._ready = False
         try:
-            _component.Component.program_change(
-                self, index, channel, note_id, sample_position)
+            _component.Component._apply_positions(self, positions,
+                                                  patch_index)
         finally:
             self._ready = ready
-        if ready and type(self).PATCHES.get(index) is not None:
+        if ready:
             self._refresh()
 
     def _hand(self, node, key, **settings):
diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 85ac7f2..80b339d 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -93,6 +93,21 @@
 #:   comma-separated: ("PitchShifter", "E10-reset", "P4", "circuitpython").
 #:
 #: A row without a scope matches every patch on every interpreter.
+#: ShimmerHall on CircuitPython only (the rows below name it): Bloom's
+#: shifter is CircuitPython's own `audiodelays.PitchShift`, which keeps its
+#: read, write and overlap positions through a clear (audiodsp#240 is in
+#: audiodsp's copy only), so a re-arm's or a reset's priming pulls leave it
+#: at another splice phase than a control that was only built, and the
+#: hall's tank then stays a few LSB off the control's. CPython and
+#: MicroPython are ok; a ruled CircuitPython-own difference.
+_SHIMMER_CP = (
+    "CircuitPython only: its own audiodelays.PitchShift keeps its read,"
+    " write and overlap positions through a clear (audiodsp#240 is in"
+    " audiodsp's copy only), so the reset's or the re-arm's priming pulls"
+    " leave Bloom's shifter at another splice phase than the control's"
+    " and the hall's tank stays a few LSB off it; CPython and MicroPython"
+    " are ok (ruled a CircuitPython-own difference)")
+
 DECLARED = {
     ("StereoWidener", "E4-m0=", "P5"):
         "family limit, disclosed (audiocomponents#117): a control that jumps"
@@ -329,26 +344,35 @@
         'family limit, disclosed (audiocomponents#117): a control that jumps makes the output step (Mix)',
     # ShimmerHall: its hall is the rebuilt Reverb, whose rows above say why
     # a tank that was emptied, or fed differently for a moment, never meets
-    # an uninterrupted one byte for byte. A reset renders exactly as a fresh
-    # instance does (the class's reset test); it is the control that never
-    # was reset.
-    ("ShimmerHall", "E1-", "P4"): "reset() empties the hall and restarts its modulation, so it never re-converges with the uninterrupted control (Reverb's E1 P4)",
-    ("ShimmerHall", "E4-m0=", "P4"): "Character re-cuts the wet chain and empties the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    # an uninterrupted one byte for byte; and Bloom's shifter is a splice
+    # shifter, whose output depends on where its read position sits in the
+    # window (the ruling's N2). A reset renders exactly as a fresh instance
+    # does (the class's reset test); it is the control that never was reset.
+    ("ShimmerHall", "E1-", "P4"): "reset() empties the hall and restarts its modulation, and restarts the shifter's splice, so it never re-converges with the uninterrupted control (Reverb's E1 P4; the splice phase, N2)",
+    ("ShimmerHall", "E4-m0=", "P4"): "Character re-cuts the wet chain, so it empties the hall and restarts the shifter's splice, and leaves the hall's tank off the control's for good (Reverb's E4 P4; the splice phase, N2)",
     ("ShimmerHall", "E4-m1=", "P4"): "Shimmer changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
     ("ShimmerHall", "E4-m3=", "P4"): "Bloom changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
-    ("ShimmerHall", "E4-m4=", "P4"): "Interval changes what enters the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
+    ("ShimmerHall", "E4-m4=", "P4"): "Interval runs the shifter's read position at another speed, so its splice phase lands elsewhere; putting it back would click (N2)",
     ("ShimmerHall", "E4-m6=", "P4"): "Size re-cuts the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
     ("ShimmerHall", "E4-m8=", "P4"): "Mix to 0 and back empties the hall, so it leaves the hall's tank off the control's for good (Reverb's E4 P4)",
-    ("ShimmerHall", "E5-", "P4"): "Mix to 0 and back empties the hall and restarts its modulation (as E1)",
-    ("ShimmerHall", "E6-", "P4"): "a patch move reaches the hall's input or its tank and leaves it off the control's for good (Reverb's E6 P4)",
-    ("ShimmerHall", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the hall (as E1)",
-    ("ShimmerHall", "E11-", "P4"): "moves that reach the hall or empty it leave its tank off the control's for good (Reverb's E11 P4)",
+    ("ShimmerHall", "E5-", "P4"): "Mix to 0 and back empties the hall and restarts its modulation and the shifter's splice (as E1; N2)",
+    ("ShimmerHall", "E6-", "P4"): "a patch move reaches the hall's input or its tank, or the shifter's interval and splice, and leaves them off the control's for good (Reverb's E6 P4; N2)",
+    ("ShimmerHall", "E9-", "P4"): "the E5 move: Mix to 0 and back empties the hall and restarts the shifter's splice (as E1; N2)",
+    ("ShimmerHall", "E11-", "P4"): "moves that reach the hall, empty it, or move the shifter's interval or splice leave them off the control's for good (Reverb's E11 P4; N2)",
     ("ShimmerHall", "E4-m0=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Character)",
     ("ShimmerHall", "E4-m3=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Bloom)",
     ("ShimmerHall", "E5-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
     ("ShimmerHall", "E6-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (a patch change)",
     ("ShimmerHall", "E9-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
     ("ShimmerHall", "E11-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (two or three moves before one pull)",
+    ("ShimmerHall", "E10-reset", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E10-mix0", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E10-macros", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E10-patch", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E12-p1", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E12-p2", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E12-mix64", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E12-mix127", "P4", "circuitpython"): _SHIMMER_CP,
 }
 
 #: A control that jumps steps the output (the family's ruled disclosure,
@@ -406,6 +430,16 @@
 #: wow table). A red PR cell of a class named here prints `decl`.
 FREE_PHASE = {}
 
+if sys.implementation.name == "circuitpython":
+    # CircuitPython only, so CPython and MicroPython keep PR live for the
+    # class: its own PitchShift keeps its positions through a clear, so a
+    # reset or a return from Mix 0 (each re-primes Bloom's shifter) sits at
+    # another splice phase than a fresh instance (E5-mix0 and E10-mix0 at
+    # patch 1, the Short Stagger).
+    FREE_PHASE["ShimmerHall"] = (
+        "the splice phase of CircuitPython's own PitchShift, which keeps"
+        " its positions through a clear (audiodsp#240)")
+
 SOURCE_KINDS = ("256", "100", "512", "1000", "raw")
 
 #: Every property a cell can print.
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 886d0e8..3a5ba92 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -983,6 +983,49 @@ def wrapped():
         finally:
             e.deinit()
 
+    def test_a_rack_holding_it_resets_to_a_fresh_racks_render(self):
+        # The rack puts the pedal back as it built it, through the pedal's
+        # own patch path: the exact constructor values come back, the dry
+        # plays from frame 0, and nothing of the knobs moved before the
+        # reset is left.
+        rack_class = rebuilt.module_class("Rack")
+        frames = 6144
+        off_grid = dict(character="rise", shimmer=0.37, rise=0.71,
+                        bloom_ms=33.3, interval=7, decay=7.7, size=1.2,
+                        damping_hz=2345.0, mix=1.6)
+        moves = (
+            ((CHARACTER_I, 127), (BLOOM_I, 10), (SHIMMER_I, 100),
+             (INTERVAL_I, 0), (MIX_I, 127)),
+            ((MIX_I, 0), (CHARACTER_I, 127), (SIZE_I, 20)),
+        )
+        for rate, channels in ((48000, 2), (22050, 1)):
+            rng = Lcg(5)
+            values = array("h", [rng.next() % 20001 - 10000
+                                 for _ in range(frames * channels)])
+            other = array("h", [-v // 2 for v in values])
+            for options in ({}, dict(mix=2.0), off_grid):
+                chain = ((ShimmerHall, options),)
+                fresh = rack_class.create(
+                    kc.feed(values, rate, channels).port, rate, chain=chain)
+                try:
+                    want = kc.render(fresh, frames)
+                finally:
+                    fresh.deinit()
+                for knobs in moves:
+                    feed = kc.feed(other, rate, channels)
+                    rack = rack_class.create(feed.port, rate, chain=chain)
+                    try:
+                        for index, midi in knobs:
+                            rack.effects[0].set_macro(index, midi)
+                        kc.render(rack, 3000)
+                        feed.point(kc.feed(values, rate, channels).mat)
+                        rack.reset()
+                        got = kc.render(rack, frames)
+                    finally:
+                        rack.deinit()
+                    self.assertEqual(got, want, (rate, channels, options,
+                                                 knobs))
+
     def test_an_output_taken_before_mix_moves_plays_the_old_level_at_first(
             self):
         # The limit the docstring discloses: a host that takes the output

From a1aaac05195817e43c2afcd9f574f5ef7e39e5c6 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 06:05:55 -0500
Subject: [PATCH 64/76] ShimmerHall tests: the get_buffer-hidden cases cover a
 reset from Mix 2, a return from Mix 0 to 127 and a Mix move before the first
 pull

---
 tests/test_cpython_effects_shimmerhall.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 3a5ba92..5a9ff03 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -606,6 +606,12 @@ def run(e):
      {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: (e.reset(), e.reset())}),
     ("a Character move and a reset in one block", ShimmerHall,
      {2: lambda e: (e.program_change(4), e.reset())}),
+    ("built at Mix 2, reset after playing",
+     lambda src: ShimmerHall(src, mix=2.0), {3: lambda e: e.reset()}),
+    ("Mix 0 after playing, back to 127", ShimmerHall,
+     {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: e.set_macro(MIX_I, 127)}),
+    ("Mix 127 before the first pull", ShimmerHall,
+     {0: lambda e: e.set_macro(MIX_I, 127)}),
 )
 
 

From 1eda46cb8efc0ed6435d5edc16b4a324c600ec40 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 06:09:56 -0500
Subject: [PATCH 65/76] Curve tables: the Octaver's comparator is a step by
 design; the exemption names it and is held to a table the scan finds

---
 tests/test_curve_tables.py | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/tests/test_curve_tables.py b/tests/test_curve_tables.py
index c00e0ea..42b43dc 100644
--- a/tests/test_curve_tables.py
+++ b/tests/test_curve_tables.py
@@ -119,12 +119,23 @@ def measure(points):
     }
 
 
+#: Tables that are comparators, not shapers: a step is the point of them, so
+#: the step bar does not apply. Monotone and fill still do. Each entry says
+#: why; `test_the_comparators_are_where_they_say` holds every entry to a
+#: table the scan really finds, so a stale entry cannot excuse a new one.
+COMPARATORS = {
+    "audioeffects.rebuilt.octaver._CURVE":
+        "the Octaver's comparator: a dead band, two small ticks, then the"
+        " rails, so its dividers count edges, not a waveform",
+}
+
+
 def verdict(name, reading):
     """The red lines for one table, empty if it meets every bar."""
     red = []
     if not reading["monotone"]:
         red.append("%s is not monotone" % name)
-    if reading["steps_over_bar"]:
+    if reading["steps_over_bar"] and name not in COMPARATORS:
         red.append("%s has %d adjacent steps over %d counts (worst %d, first"
                    " at index %d)"
                    % (name, reading["steps_over_bar"], STEP_BAR,
@@ -237,6 +248,22 @@ def test_every_table_meets_the_three_bars(self):
                 red = verdict(name, reading)
                 self.assertEqual(red, [], "%s: %s" % (name, "; ".join(red)))
 
+    def test_the_comparators_are_where_they_say(self):
+        """Every comparator entry names a table the scan finds, once the
+        class that builds it has been built."""
+        from audioeffects import rebuilt
+        import audiocore
+        from array import array as _array
+        src = audiocore.RawSample(_array("h", [0] * 512),
+                                  sample_rate=48000, channel_count=2)
+        rebuilt.module_class("Octaver")(src).deinit()
+        found = tables_by_value()
+        for name in COMPARATORS:
+            self.assertIn(name, found, "%s is not a table the scan finds"
+                          % name)
+            self.assertTrue(verdict(name, measure(found[name])) == [],
+                            "%s fails a bar the exemption keeps" % name)
+
     def test_the_scan_found_the_drive_tables(self):
         """Absence must not read as agreement.
 

From 3f3cf19188e582acf7171a8e7f810ebc190e4b0b Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 06:32:21 -0500
Subject: [PATCH 66/76] CHANGELOG: tidy the merge

---
 CHANGELOG.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f02124..e2e0639 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,7 +19,6 @@ there, and are recorded in its changelog.
   chamber's tail, and a Time move bends the repeats' pitch. The chamber is
   the rebuilt `Reverb`, and `reset()` renders exactly as a fresh instance.
   The old `rack.AirSpace` stays what the library serves until adoption.
-
 - **`StereoWidener` (rebuilt, Phase 6):** two characters on a Width, Delay
   and Character surface. Haas delays the right channel 1 to 40 ms behind the
   left, crossfading the right toward its late copy up to Width 1 and turning

From 2f25caeeef8bdebe014f1ea7060f807d4aa977c3 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 06:50:16 -0500
Subject: [PATCH 67/76] ShimmerHall: the fold-back and the splice's cancelled
 line told in a player's words, each with a test; a seventh patch, Octave
 Bloom - lean (Rise at Rise 0), for an S3; the lower-rate band claim struck

---
 CHANGELOG.md                              |   5 +-
 lib/audioeffects/rebuilt/shimmerhall.py   |  15 +-
 tests/test_cpython_effects_shimmerhall.py | 315 +++++++++++++++++++++-
 3 files changed, 325 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d75aad8..f7d19b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,9 @@ there, and are recorded in its changelog.
   after you play, on `audiodelays.PitchShift`; Rise puts the shift inside
   an `audioecho.FeedbackDelay` loop (`loop_semitones`), so each pass comes
   back shifted again until Damping darkens it away. Nine macros (Character,
-  Shimmer, Rise, Bloom, Interval, Decay, Size, Damping, Mix) and six
-  patches replace the old Shimmer / Echo / Space / Tone surface and its
+  Shimmer, Rise, Bloom, Interval, Decay, Size, Damping, Mix) and seven
+  patches (the last, "Octave Bloom - lean", is Rise at Rise 0, for a board
+  short of memory) replace the old Shimmer / Echo / Space / Tone surface and its
   constructor arguments. The hall is the rebuilt `Reverb`. The dry passes
   untouched up to Mix 1, Mix 0 is a byte-exact wire, and the input ceiling
   is -24 dBFS. It lives in `lib/audioeffects/rebuilt/shimmerhall.py`, beside
diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index 7da4dfd..8d20c8a 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -36,7 +36,8 @@
 your input stops: 82 s at Rise 0.9 and Bloom 800 ms. `reset()` empties the
 hall, the line and the shifter, and restores patch 0. The patches: Octave
 Bloom (the defaults), Short Stagger, Fifth Halo, Slow Rise, Rise Damped,
-Falling Octaves.
+Falling Octaves, Octave Bloom - lean. Octave Bloom - lean is Rise at Rise 0,
+for an S3: one octave, once, and the hall starts at once.
 
 **Limits**
 
@@ -47,9 +48,12 @@
 old level.
 
 Interval is a fixed shift in semitones, with no key awareness. Both
-shifters splice, so the shifted copy has a slight flutter. At a lower
-sample rate the band ends lower, so the climb reaches the top of it sooner.
-A mono source gets a mono rack. It needs a board with PSRAM.
+shifters splice, so the shifted copy has a slight flutter. In Rise, on some
+held notes the shimmer lands beside the octave rather than on it: a held G3
+at +12 is one. With Damping high and Rise near the top, or at the widest
+intervals, the highest octaves fold back down as tones outside the series;
+keep Damping lower for a clean climb. A mono source gets a mono rack. It
+needs a board with PSRAM.
 
 When your source ends, the tail rings out as it would on silence. On a
 CircuitPython board, stop the rack from the host if your source can run
@@ -279,6 +283,9 @@ class ShimmerHall(_component.Component):
         3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 102, 38)),
         4: ("Rise Damped", (127, 102, 113, 87, 96, 94, 64, 51, 32)),
         5: ("Falling Octaves", (127, 89, 85, 93, 0, 102, 64, 76, 32)),
+        # Patch 0 in Rise at Rise 0: the S3's fallback if Bloom's line and
+        # second shifter do not fit its memory.
+        6: ("Octave Bloom - lean", (127, 89, 0, 90, 96, 94, 64, 91, 32)),
     }
 
     def _build(self, character="bloom", shimmer=SHIMMER, rise=RISE,
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 5a9ff03..49ce0da 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -545,7 +545,162 @@ def t6_read(cls, rate, channels, patch, seed):
     return worst, loud
 
 
-T6_PATCHES = (0, 4)
+T6_PATCHES = (0, 4, 6)
+
+
+# --------------------------------------------------------------------------
+# F: the climb's highest octaves fold back past Nyquist, and the splice
+# can cancel the shifted line itself
+
+
+def fold_chain(f0, semitones, rate, count=8):
+    """Where the loop's passes land: (the in-band lines of the series, the
+    lines each later pass folds down to). A pass that reads past Nyquist
+    comes back reflected into the band, and the passes after it are shifted
+    from there. Lines within 2 % of a harmonic (1 to 6) of an in-band line
+    are dropped from the folds (2 %): the splice's own harmonics sit there."""
+    ratio = 2.0 ** (semitones / 12.0)
+    nyquist = 0.5 * rate
+    series = []
+    folds = []
+    over = False
+    x = f0
+    for _ in range(count):
+        x *= ratio
+        if x >= nyquist:
+            over = True
+        if over:
+            x = x % rate
+            if x > nyquist:
+                x = rate - x
+            folds.append(x)
+        else:
+            series.append(x)
+    kept = []
+    for hz in folds:
+        near = False
+        for line in series:
+            for n in range(1, 7):
+                if abs(hz - n * line) < 0.02 * n * line:
+                    near = True
+        if not near and hz > 30.0:
+            kept.append(hz)
+    return series, kept
+
+
+def fold_peak(values, hz, rate, start, stop, spread=0.0, step=0.0015):
+    """The peak band power near `hz` over frames `start` to `stop`: Hann
+    frames of 4096 frames at 48 kHz and 2048 at 22.05 kHz, a probe every
+    `step` of `hz` out to `spread` of it either side. A pass that folds
+    comes back a little off the line the arithmetic gives (the loop's read
+    is not exactly the interval, and the fold multiplies the error), so the
+    line is looked for, not read."""
+    size = 4096 if rate >= 44100 else 2048
+    window = hann(size)
+    best = 0.0
+    count = int(spread / step + 0.5)
+    stop = min(stop, len(values))
+    for j in range(-count, count + 1):
+        probe = hz * (1.0 + j * step)
+        for at in range(start, stop - size + 1, size // 2):
+            best = max(best, goertzel(values, at, size, probe, rate, window))
+    return best
+
+
+def fold_read(cls, rate, f0, offset, lines=1, **options):
+    """(each fold line's level in dB against the loudest line of the first
+    pass, the lines in Hz) of the shimmer alone: Shimmer 1 less Shimmer 0 at
+    Mix 2 with the shortest hall, so each pass is heard on its own. The
+    first `lines` lines of `fold_chain`, looked for from the pass that first
+    reads past Nyquist on."""
+    options = dict(options, mix=2.0, decay=0.3, size=0.5)
+    bloom = options["bloom_ms"]
+    frames = law_frames(100.0 + 9 * bloom + 400.0, rate) + offset
+    channels = card_channels(rate)
+    one = wet(cls, rate, channels, f0, offset, frames, shimmer=1.0, **options)
+    none = wet(cls, rate, channels, f0, offset, frames, shimmer=0.0,
+               **options)
+    only = [one[n] - none[n] for n in range(frames)]
+    series, folds = fold_chain(f0, options["interval"], rate)
+    folds = folds[:lines]
+    # The first pass is the loudest; the loop's short window moves it by up
+    # to 3.5 semitones, so it is looked for across a quarter-tone grid.
+    gap = law_frames(bloom, rate)
+    loudest = max(fold_peak(only, series[0] * 2.0 ** (q / 48.0), rate,
+                            offset, offset + 2 * gap)
+                  for q in range(-8, 9))
+    start = offset + law_frames((len(series) + 1) * bloom - 50.0, rate)
+    rel = [db(fold_peak(only, hz, rate, start, frames, 0.03)) - db(loudest)
+           for hz in folds]
+    return rel, folds
+
+
+#: Slow Rise's settings less Shimmer and Mix, which a read sets itself.
+def fold_shipped(patch):
+    options = patch_options(ShimmerHall, patch)
+    del options["shimmer"], options["mix"]
+    return options
+
+
+#: What the docstring names: Rise near the top with Damping high, and the
+#: widest interval.
+FOLD_EDGES = (
+    ("Rise 0.9, Damping 16 kHz", dict(rise=0.9, damping_hz=16000.0)),
+    ("+24", dict(interval=24)),
+)
+
+#: (rate, f0) cells, offset 41, where a pass folds clear of the series and
+#: of the splice's harmonics.
+FOLD_CELLS = ((48000, 240.0), (22050, 185.0))
+
+#: A fold line is loud when it stands within 30 dB of the loudest line of
+#: the first pass; the climb is clean when every fold line stays more than
+#: 40 dB under it.
+FOLD_LOUD = -30.0
+FOLD_CLEAN = -40.0
+
+
+#: Held notes in Rise at +12: G3 is one the splice cancels the shifted line
+#: of; E3 is one it does not.
+SPLICE_G3 = 196.0
+SPLICE_E3 = 165.0
+
+
+
+
+def splice_read(cls, rate, f0, character="rise"):
+    """The share of the shimmer's energy within half a semitone of the
+    note an interval above f0, for a note held 0.5 s."""
+    channels = card_channels(rate)
+    length = rate
+    values = array("h", bytes(2 * length * channels))
+    w = 2.0 * math.pi * f0 / rate
+    for n in range(1000, 1000 + rate // 2):
+        v = rint(3000.0 * math.sin(w * n))
+        for c in range(channels):
+            values[n * channels + c] = v
+    outs = []
+    for shimmer in (1.0, 0.0):
+        outs.append(left(render(
+            cls, values, rate, channels, length, character=character,
+            bloom_ms=200.0, shimmer=shimmer, rise=0.0, mix=2.0, interval=12,
+            decay=0.3, size=0.5, damping_hz=16000.0), channels))
+    shimmer = [outs[0][n] - outs[1][n] for n in range(length)]
+    start = law_frames(300.0, rate)
+    size = law_frames(300.0, rate)
+    window = hann(size)
+    # A probe every eighth of a semitone, out to a whole octave either way.
+    target = 2.0 * f0
+    near = total = 0.0
+    for q in range(-96, 97):
+        hz = target * 2.0 ** (q / 96.0)
+        if hz < 20.0 or hz >= 0.5 * rate:
+            continue
+        power = goertzel(shimmer, start, size, hz, rate, window)
+        total += power
+        if abs(q) <= 4:
+            near += power
+    return near / total
 
 
 # --------------------------------------------------------------------------
@@ -634,9 +789,11 @@ def test_macros_patches_tier_latency(self):
                          ("audioroute", "audioecho", "audioverb"))
         self.assertEqual(ShimmerHall.CAPABILITIES, ())
         self.assertEqual(ShimmerHall.LATENCY_SAMPLES, 0)
-        self.assertEqual([ShimmerHall.PATCHES[i][0] for i in range(6)],
+        self.assertEqual([ShimmerHall.PATCHES[i][0] for i in range(7)],
                          ["Octave Bloom", "Short Stagger", "Fifth Halo",
-                          "Slow Rise", "Rise Damped", "Falling Octaves"])
+                          "Slow Rise", "Rise Damped", "Falling Octaves",
+                          "Octave Bloom - lean"])
+        self.assertEqual(sorted(ShimmerHall.PATCHES), list(range(7)))
 
     def test_the_spans(self):
         e = ShimmerHall(_port())
@@ -1211,6 +1368,112 @@ def test_late_dry_is_red(self):
         self.assertGreater(worst, 1000)
 
 
+class TheEdges(TestCase):
+    def test_the_highest_octaves_fold_back_at_the_edges(self):
+        # The same note and the same patch but for the edge: a fold line
+        # stands within 30 dB of the first pass at Rise 0.9 with Damping at
+        # 16 kHz, and at +24, and stays under -40 dB at Slow Rise's and
+        # Rise Damped's own settings.
+        for rate, f0 in FOLD_CELLS:
+            for patch in (3, 4):
+                rel, folds = fold_read(ShimmerHall, rate, f0, 41,
+                                       **fold_shipped(patch))
+                self.assertTrue(folds, (rate, f0, patch))
+                self.assertLess(max(rel), FOLD_CLEAN, (rate, f0, patch, rel))
+            for name, edge in FOLD_EDGES:
+                options = dict(fold_shipped(3), **edge)
+                rel, folds = fold_read(ShimmerHall, rate, f0, 41, **options)
+                self.assertTrue(folds, (rate, f0, name))
+                self.assertGreater(max(rel), FOLD_LOUD,
+                                   (rate, f0, name, rel, folds))
+
+    def test_the_fold_chain_is_the_arithmetic(self):
+        # +12 from 240 Hz at 48 kHz stays in band to 15360, then 30720
+        # reflects to 17280; +24 from 240 Hz: 960, 3840, 15360, then 61440
+        # less 48000.
+        series, folds = fold_chain(240.0, 12, 48000, 8)
+        self.assertEqual([round(x) for x in series],
+                         [480, 960, 1920, 3840, 7680, 15360])
+        self.assertEqual(round(fold_chain(240.0, 24, 48000)[0][-1]), 15360)
+        self.assertEqual(round(fold_chain(240.0, 24, 48000)[1][0]), 13440)
+        self.assertEqual(fold_chain(240.0, -12, 48000)[1], [])
+
+    def test_a_held_note_can_land_beside_the_octave(self):
+        for rate in RATES:
+            beside = splice_read(ShimmerHall, rate, SPLICE_G3)
+            self.assertLess(beside, 0.10, (rate, "G3", beside))
+            on = splice_read(ShimmerHall, rate, SPLICE_E3)
+            self.assertGreater(on, 0.90, (rate, "E3", on))
+
+
+def lean_levels(rate, f0, offset, patch):
+    """(the first pass's loudest line, and the lines a second and a third
+    octave would stand on from their own passes, in dB against it) of the
+    shimmer alone at
+    `patch`, with the shortest hall."""
+    options = fold_shipped(patch)
+    options.update(mix=2.0, decay=0.3, size=0.5)
+    bloom = options["bloom_ms"]
+    frames = law_frames(100.0 + 6 * bloom + 400.0, rate) + offset
+    channels = card_channels(rate)
+    one = wet(ShimmerHall, rate, channels, f0, offset, frames, shimmer=1.0,
+              **options)
+    none = wet(ShimmerHall, rate, channels, f0, offset, frames, shimmer=0.0,
+               **options)
+    only = [one[n] - none[n] for n in range(frames)]
+    # Each octave is looked for from the pass that would carry it on: the
+    # first pass's own harmonics stand on the second octave, but earlier.
+    gap = law_frames(bloom, rate)
+    levels = []
+    for octave in (1, 2, 3):
+        start = offset + (octave - 1) * gap + (
+            0 if octave == 1 else gap - law_frames(50.0, rate))
+        levels.append(max(fold_peak(only, f0 * 2.0 ** (octave + q / 48.0),
+                                    rate, start, frames)
+                          for q in range(-8, 9)))
+    return [db(x) - db(levels[0]) for x in levels]
+
+
+class TheLeanPatch(TestCase):
+    def test_the_lean_patch_is_patch_0_in_rise_at_rise_0(self):
+        steps = list(ShimmerHall.PATCHES[0][1])
+        steps[CHARACTER_I] = 127
+        steps[RISE_I] = 0
+        self.assertEqual(ShimmerHall.PATCHES[6][1], tuple(steps))
+        self.assertEqual(ShimmerHall.PATCHES[6][0], "Octave Bloom - lean")
+        e = ShimmerHall(_port(), patch=6)
+        try:
+            self.assertEqual(e.macro(CHARACTER_I), 1.0)
+            self.assertEqual(e.macro(RISE_I), 0.0)
+            self.assertEqual(e.macro(INTERVAL_I), 12.0)
+        finally:
+            e.deinit()
+
+    def test_the_lean_patch_is_one_octave_once(self):
+        # Rise 0.9 climbs: the second and the third octave are in the
+        # shimmer within 30 dB of the first. At the lean patch only the
+        # first is there, and the others stand more than 40 dB under it.
+        for rate, f0 in ((48000, 247.0), (22050, 220.0)):
+            lean = lean_levels(rate, f0, 13, 6)
+            self.assertLess(max(lean[1:]), -40.0, (rate, lean))
+        climbing = lean_levels(48000, 247.0, 13, 3)
+        self.assertGreater(climbing[1], -30.0, climbing)
+
+    def test_the_lean_hall_starts_at_once(self):
+        # Patch 0 holds the whole hall for Bloom (273 ms); the lean patch
+        # plays the dry into it at once.
+        for rate in RATES:
+            channels = card_channels(rate)
+            frames = law_frames(150.0, rate)
+            heard = []
+            for patch in (0, 6):
+                out = wet(ShimmerHall, rate, channels, 247.0, 0, frames,
+                          **patch_options(ShimmerHall, patch, mix=2.0))
+                heard.append(max(abs(x) for x in out))
+            self.assertEqual(heard[0], 0, (rate, heard))
+            self.assertGreater(heard[1], 100, (rate, heard))
+
+
 #: Every claim sentence of the class docstring and the test that holds it.
 CLAIMS = (
     ("`ShimmerHall` - a hall that rings an octave above what you play.",
@@ -1290,8 +1553,24 @@ def test_late_dry_is_red(self):
      "the first 256 frames, 5 ms at 48 kHz, play at the old level.",
      ("test_an_output_taken_before_mix_moves_plays_the_old_level_at_first",
       "test_only_a_move_that_changes_a_voice_level_re_arms")),
+    ("The patches: Octave Bloom (the defaults), Short Stagger, Fifth Halo, "
+     "Slow Rise, Rise Damped, Falling Octaves, Octave Bloom - lean.",
+     "test_macros_patches_tier_latency"),
+    ("Octave Bloom - lean is Rise at Rise 0, for an S3: one octave, once, "
+     "and the hall starts at once.",
+     ("test_the_lean_patch_is_patch_0_in_rise_at_rise_0",
+      "test_the_lean_patch_is_one_octave_once",
+      "test_the_lean_hall_starts_at_once")),
     ("Interval is a fixed shift in semitones, with no key awareness.",
      "test_interval_has_five_zones"),
+    ("In Rise, on some held notes the shimmer lands beside the octave "
+     "rather than on it: a held G3 at +12 is one.",
+     "test_a_held_note_can_land_beside_the_octave"),
+    ("With Damping high and Rise near the top, or at the widest intervals, "
+     "the highest octaves fold back down as tones outside the series; keep "
+     "Damping lower for a clean climb.",
+     ("test_the_highest_octaves_fold_back_at_the_edges",
+      "test_the_fold_chain_is_the_arithmetic")),
     ("A value outside a macro's span clamps to the nearer stop, and NaN "
      "takes the default; an `interval` other than the five raises "
      "`ValueError`.", "test_the_constructor"),
@@ -1303,6 +1582,8 @@ def test_late_dry_is_red(self):
 
 
 def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
+    # "F" (the fold-back and splice rows) is asked for by name: it renders
+    # a few hundred seconds of audio.
     """Print each trait's numbers over every cell the card names, eight
     seed sets each: the evidence pack's rows."""
     name = sys.implementation.name
@@ -1392,6 +1673,32 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
         plant = t6_read(LateDry, 48000, 2, 0, 1)[0]
         print("%s|T6|runs %d|worst %d LSB|loudest %d|plant %d LSB" % (
             name, runs, worst, loud, plant))
+    if "F" in which:
+        for patch in (3, 4, 6):
+            options = fold_shipped(patch)
+            for rate in RATES:
+                worst = -999.0
+                for seed in SEEDS:
+                    f0, offset = seed_set(seed)
+                    rel, _folds = fold_read(ShimmerHall, rate, f0, offset,
+                                            lines=3, **options)
+                    for level in rel:
+                        worst = max(worst, level)
+                print("%s|F|patch %d %s|%d|worst fold line %.1f dB over "
+                      "%d notes|bar %.0f" % (
+                          name, patch, ShimmerHall.PATCHES[patch][0], rate,
+                          worst, len(SEEDS), FOLD_LOUD))
+        for rate, f0 in FOLD_CELLS:
+            for label, edge in FOLD_EDGES:
+                rel, _folds = fold_read(
+                    ShimmerHall, rate, f0, 41, **dict(fold_shipped(3), **edge))
+                print("%s|F|edge %s|%d|f0 %g|fold line %.1f dB|bar %.0f" % (
+                    name, label, rate, f0, max(rel), FOLD_LOUD))
+        for rate in RATES:
+            print("%s|F|splice|%d|G3 %.0f %%|E3 %.0f %%" % (
+                name, rate,
+                100.0 * splice_read(ShimmerHall, rate, SPLICE_G3),
+                100.0 * splice_read(ShimmerHall, rate, SPLICE_E3)))
     if "L" in which:
         for rate in (48000, 44100):
             for channels in (2, 1):
@@ -1419,6 +1726,6 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
         # By name, not as __main__: a plant reads VENDOR from the module
         # that defines it, and natively __main__ is not one it can find.
         import test_cpython_effects_shimmerhall as module
-        picked = [a for a in sys.argv[1:] if a[:1] in ("T", "L")]
+        picked = [a for a in sys.argv[1:] if a[:1] in ("T", "L", "F")]
         module.figures(tuple(picked)
                        or ("T1", "T2", "T3", "T4", "T5", "T6", "L"))

From 478ff1ba0fdfc996822fa52cdab7311cfc3ad50f Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 07:21:15 -0500
Subject: [PATCH 68/76] ShimmerHall tests: the fold-back figures sweep the note
 and name a silent pass

---
 tests/test_cpython_effects_shimmerhall.py | 24 ++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index 49ce0da..c8a77b8 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -1684,10 +1684,28 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
                                             lines=3, **options)
                     for level in rel:
                         worst = max(worst, level)
-                print("%s|F|patch %d %s|%d|worst fold line %.1f dB over "
-                      "%d notes|bar %.0f" % (
+                # Exact silence where the pass never comes (Rise damped to
+                # nothing, or the lean patch's loop).
+                print("%s|F|patch %d %s|%d|worst fold line %s over %d "
+                      "notes|bar %.0f" % (
                           name, patch, ShimmerHall.PATCHES[patch][0], rate,
-                          worst, len(SEEDS), FOLD_LOUD))
+                          "%.1f dB" % worst if worst > -200.0 else "silent",
+                          len(SEEDS), FOLD_LOUD))
+        # A finer sweep of the note: 165 to 330 Hz in 5 Hz steps, offset 41.
+        for patch in (3, 4):
+            options = fold_shipped(patch)
+            for rate in RATES:
+                worst = (-999.0, 0)
+                for f0 in range(165, 331, 5):
+                    rel, _folds = fold_read(ShimmerHall, rate, float(f0), 41,
+                                            lines=3, **options)
+                    for level in rel:
+                        worst = max(worst, (level, f0))
+                print("%s|F|sweep patch %d %s|%d|worst fold line %s at %d "
+                      "Hz|bar %.0f" % (
+                          name, patch, ShimmerHall.PATCHES[patch][0], rate,
+                          "%.1f dB" % worst[0] if worst[0] > -200.0
+                          else "silent", worst[1], FOLD_LOUD))
         for rate, f0 in FOLD_CELLS:
             for label, edge in FOLD_EDGES:
                 rel, _folds = fold_read(

From d147a0d498882b22038df198163e5626d39d8ee6 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 07:23:07 -0500
Subject: [PATCH 69/76] AirSpace: the input ceiling is -17 dBFS, measured at
 Mix 1 over 12 s

At -12 dBFS a square railed at Mix 1 with Feedback, Decay or Time at 127, on
Long Send and on Dark Loop. The worst peak gain over every patch, every other
macro at its stops, all macros open, six low squares and noise is 16.47 dB
(Decay 127, 220 Hz), so -17 leaves 0.51 dB under the rail. The ceiling test
renders the worst cells for 12 s.
---
 lib/audioeffects/rebuilt/airspace.py   |  4 +-
 tests/test_cpython_effects_airspace.py | 64 ++++++++++++++++++++++----
 2 files changed, 58 insertions(+), 10 deletions(-)

diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
index c833984..124ac0b 100644
--- a/lib/audioeffects/rebuilt/airspace.py
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -21,7 +21,7 @@
 a move across the whole Time range takes, so it sets how far they bend: 12 %
 at the default of 4 s.
 
-Keep your input at or under -12 dBFS: at Mix 1 the dry and the chamber are
+Keep your input at or under -17 dBFS: at Mix 1 the dry and the chamber are
 both at unity and add, so a hotter input can reach the rail. Latency is
 zero. `reset()` empties the tape and the chamber and restores patch 0, whose
 Time of 111 ms lands at once instead of gliding.
@@ -206,7 +206,7 @@ class _Chamber(_reverb.Reverb):
 
     CAPABILITIES = ()
     LATENCY_SAMPLES = 0
-    INPUT_CEILING_DBFS = -12.0
+    INPUT_CEILING_DBFS = -17.0
     TAIL_SAMPLES = None
 
     #: The exact-value flags, which a rack's reset puts back with the knobs.
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index 5b269d2..c5e740f 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -951,12 +951,58 @@ def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0,
     return longest
 
 
+#: The cells the ceiling was measured over: (label, patch, macros after the
+#: patch, material). They are the worst of the sweep over every patch, every
+#: other macro at its stops, all macros at 127, six low squares and noise,
+#: at Mix 1 and 12 s: the chamber needs that long to fill. Decay 127 is the
+#: worst (a 220 Hz square gains 16.47 dB); then Time 127 (15.18), Feedback
+#: 127 (14.83), Short Send (13.99), Long Send (13.77), Dark Loop (12.50) and
+#: the macros all open (12.39).
+CEILING_CELLS = (
+    ("Decay 127", None, ((DECAY_I, 127),), 220),
+    ("Time 127", None, ((TIME_I, 127),), 220),
+    ("Feedback 127", None, ((FEEDBACK_I, 127),), 147),
+    ("Short Send", 1, (), 220),
+    ("Long Send", 2, (), 220),
+    ("Dark Loop", 3, (), 147),
+    ("all macros 127", None, tuple((i, 127) for i in range(10)), "noise"),
+)
+CEILING_MARGIN_DB = 0.5
+
+
+def cell_peak(label, patch, macros, material, dbfs, seconds=12.0):
+    """The highest |sample| of a 48 kHz stereo render of one cell at Mix 1."""
+    rate, channels = 48000, 2
+    frames = int(seconds * rate)
+    peak = 32767.0 * 10.0 ** (dbfs / 20.0)
+    if material == "noise":
+        data = lcg_noise(frames, channels, peak / math.sqrt(3.0), 5)
+    else:
+        data = square(float(material), frames, rate, channels, peak)
+    effect = build(AirSpace, data, rate, channels, patch)
+    effect.set_macro(MIX_I, 64)
+    for index, midi in macros:
+        effect.set_macro(index, midi)
+    out = render(effect, frames)
+    effect.deinit()
+    return max(max(out), -min(out))
+
+
 class TheInputCeiling(unittest.TestCase):
 
-    def test_the_ceiling_is_minus_12_dbfs(self):
-        self.assertEqual(AirSpace.INPUT_CEILING_DBFS, -12.0)
+    def test_the_ceiling_is_minus_17_dbfs(self):
+        self.assertEqual(AirSpace.INPUT_CEILING_DBFS, -17.0)
 
-    def test_minus_12_dbfs_reaches_no_rail_at_mix_1_on_every_patch(self):
+    def test_the_ceiling_keeps_the_margin_to_the_rail_in_the_worst_cells(self):
+        ceiling = AirSpace.INPUT_CEILING_DBFS
+        limit = 32767.0 * 10.0 ** (-CEILING_MARGIN_DB / 20.0)
+        for label, patch, macros, material in CEILING_CELLS:
+            with self.subTest(cell=label, material=material):
+                self.assertLess(
+                    cell_peak(label, patch, macros, material, ceiling),
+                    limit)
+
+    def test_the_ceiling_reaches_no_rail_at_mix_1_on_every_patch(self):
         ceiling = AirSpace.INPUT_CEILING_DBFS
         for rate, channels in ((48000, 2), (22050, 1)):
             for patch in sorted(AirSpace.PATCHES):
@@ -964,7 +1010,7 @@ def test_minus_12_dbfs_reaches_no_rail_at_mix_1_on_every_patch(self):
                     self.assertLessEqual(
                         rail_run(AirSpace, rate, channels, ceiling, patch), 8)
 
-    def test_minus_12_dbfs_reaches_no_rail_with_each_macro_at_its_stops(self):
+    def test_the_ceiling_reaches_no_rail_with_each_macro_at_its_stops(self):
         ceiling = AirSpace.INPUT_CEILING_DBFS
         for index in range(11):
             if index == MIX_I:
@@ -1265,13 +1311,15 @@ def _pull(self):
      "takes, so it sets how far they bend: 12 % at the default of 4 s.",
      ("TheSurface.test_the_glide_law",
       "T5TimeBendsThePitch.test_the_bend_both_ways_at_every_glide")),
-    ("Keep your input at or under -12 dBFS: at Mix 1 the dry and the "
+    ("Keep your input at or under -17 dBFS: at Mix 1 the dry and the "
      "chamber are both at unity and add, so a hotter input can reach the "
      "rail.",
-     ("TheInputCeiling.test_the_ceiling_is_minus_12_dbfs",
-      "TheInputCeiling.test_minus_12_dbfs_reaches_no_rail_at_mix_1_on_every_"
+     ("TheInputCeiling.test_the_ceiling_is_minus_17_dbfs",
+      "TheInputCeiling.test_the_ceiling_keeps_the_margin_to_the_rail_in_the_"
+      "worst_cells",
+      "TheInputCeiling.test_the_ceiling_reaches_no_rail_at_mix_1_on_every_"
       "patch",
-      "TheInputCeiling.test_minus_12_dbfs_reaches_no_rail_with_each_macro_at_"
+      "TheInputCeiling.test_the_ceiling_reaches_no_rail_with_each_macro_at_"
       "its_stops",
       "TheInputCeiling.test_a_hotter_input_does")),
     ("Latency is zero.", "TheSurface.test_latency_is_zero"),

From 002f4c3e00d0dd3e517f47642b5777cd2b6da5cd Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 07:30:17 -0500
Subject: [PATCH 70/76] test_kit: write the fixture card and claims module as
 UTF-8, as the checks read them (Windows wrote cp1252)

---
 tests/test_kit.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/tests/test_kit.py b/tests/test_kit.py
index 18252f2..baa40ce 100644
--- a/tests/test_kit.py
+++ b/tests/test_kit.py
@@ -374,7 +374,7 @@ def run_claims(self, claims, doc=None):
         with tempfile.TemporaryDirectory() as scratch:
             name = "kitfixture_%d" % abs(hash((repr(claims), doc)))
             path = os.path.join(scratch, name + ".py")
-            with open(path, "w") as f:
+            with open(path, "w", encoding="utf-8") as f:
                 f.write(textwrap.dedent(FIXTURE_TESTS % repr(claims)))
             sys.path.insert(0, scratch)
             try:
@@ -517,7 +517,8 @@ def surface(self, card):
         pin = kit_paperwork.Pin(None, None)
         with tempfile.TemporaryDirectory() as cards:
             if card is not None:
-                with open(os.path.join(cards, "CondKit.md"), "w") as f:
+                with open(os.path.join(cards, "CondKit.md"), "w",
+                          encoding="utf-8") as f:
                     f.write(card)
             lines = []
             kit_paperwork.check("CondKit", "", "", pin, lines.append,

From 854c14ecb0e2b7084051f87e2ca63b5155e71cc8 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 07:32:02 -0500
Subject: [PATCH 71/76] AirSpace: the docstring names what the -17 dBFS ceiling
 covers, and the -26 dBFS for Feedback, Decay and Time open together

Pairs and triples of Feedback, Decay and Time at 127 on every patch, over 110,
147 and 220 Hz squares and 12 s, gain up to 24.71 dB (Short Send with Feedback
and Decay). One test pins that gain under the quoted 25 dB.
---
 lib/audioeffects/rebuilt/airspace.py   |  6 ++++--
 tests/test_cpython_effects_airspace.py | 30 ++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/lib/audioeffects/rebuilt/airspace.py b/lib/audioeffects/rebuilt/airspace.py
index 124ac0b..6bd5d23 100644
--- a/lib/audioeffects/rebuilt/airspace.py
+++ b/lib/audioeffects/rebuilt/airspace.py
@@ -22,8 +22,10 @@
 at the default of 4 s.
 
 Keep your input at or under -17 dBFS: at Mix 1 the dry and the chamber are
-both at unity and add, so a hotter input can reach the rail. Latency is
-zero. `reset()` empties the tape and the chamber and restores patch 0, whose
+both at unity and add, so a hotter input can reach the rail. That holds on
+every patch and with any one macro at either end. Open two or more of
+Feedback, Decay and Time together and the chamber builds further, by up to
+25 dB: keep your input at or under -26 dBFS there. Latency is zero. `reset()` empties the tape and the chamber and restores patch 0, whose
 Time of 111 ms lands at once instead of gliding.
 
 The patches: Chamber Send (the defaults), Short Send, Long Send, Dark Loop,
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index c5e740f..030746c 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -968,6 +968,9 @@ def rail_run(cls, rate, channels, dbfs, patch=None, seconds=2.0,
     ("all macros 127", None, tuple((i, 127) for i in range(10)), "noise"),
 )
 CEILING_MARGIN_DB = 0.5
+#: The gain the docstring quotes for two or more of Feedback, Decay and Time
+#: open together, and the level it says to keep the input under there.
+QUOTED_COMBINED_GAIN_DB = 25.0
 
 
 def cell_peak(label, patch, macros, material, dbfs, seconds=12.0):
@@ -1002,6 +1005,24 @@ def test_the_ceiling_keeps_the_margin_to_the_rail_in_the_worst_cells(self):
                     cell_peak(label, patch, macros, material, ceiling),
                     limit)
 
+    def test_feedback_and_decay_together_gain_under_25_db(self):
+        # The worst of the pairs and triples of Feedback, Decay and Time
+        # at 127 on every patch, over 110, 147 and 220 Hz squares and 12 s:
+        # Short Send with Feedback and Decay, 24.71 dB on a 220 Hz square.
+        # Read at -40 dBFS, where nothing rails and the chamber is linear.
+        rate, channels, frames = 48000, 2, 12 * 48000
+        peak = 32767.0 * 10.0 ** (-40.0 / 20.0)
+        data = square(220.0, frames, rate, channels, peak)
+        effect = build(AirSpace, data, rate, channels, 1)
+        effect.set_macro(MIX_I, 64)
+        effect.set_macro(FEEDBACK_I, 127)
+        effect.set_macro(DECAY_I, 127)
+        out = render(effect, frames)
+        effect.deinit()
+        gain = 20.0 * math.log10(max(max(out), -min(out)) / peak)
+        self.assertLess(gain, QUOTED_COMBINED_GAIN_DB)
+        self.assertGreater(gain, 24.0)
+
     def test_the_ceiling_reaches_no_rail_at_mix_1_on_every_patch(self):
         ceiling = AirSpace.INPUT_CEILING_DBFS
         for rate, channels in ((48000, 2), (22050, 1)):
@@ -1322,6 +1343,15 @@ def _pull(self):
       "TheInputCeiling.test_the_ceiling_reaches_no_rail_with_each_macro_at_"
       "its_stops",
       "TheInputCeiling.test_a_hotter_input_does")),
+    ("That holds on every patch and with any one macro at either end.",
+     ("TheInputCeiling.test_the_ceiling_reaches_no_rail_at_mix_1_on_every_"
+      "patch",
+      "TheInputCeiling.test_the_ceiling_reaches_no_rail_with_each_macro_at_"
+      "its_stops")),
+    ("Open two or more of Feedback, Decay and Time together and the chamber "
+     "builds further, by up to 25 dB: keep your input at or under -26 dBFS "
+     "there.",
+     "TheInputCeiling.test_feedback_and_decay_together_gain_under_25_db"),
     ("Latency is zero.", "TheSurface.test_latency_is_zero"),
     ("`reset()` empties the tape and the chamber and restores patch 0, "
      "whose Time of 111 ms lands at once instead of gliding.",

From 49dc74fd9664e6c4c2f89019ae43b3dc4d33b309 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 09:07:39 -0500
Subject: [PATCH 72/76] ShimmerHall: Slow Rise's Damping from step 102 to 86 so
 the climb stays clean at 22.05 kHz; a sweep of every upward patch, red on the
 card's Slow Rise

---
 lib/audioeffects/rebuilt/shimmerhall.py   |  4 ++-
 tests/test_cpython_effects_shimmerhall.py | 43 ++++++++++++++++++++---
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index 8d20c8a..14f2cfe 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -280,7 +280,9 @@ class ShimmerHall(_component.Component):
         0: ("Octave Bloom", DEFAULT_STEPS),
         1: ("Short Stagger", (0, 76, 85, 38, 96, 77, 38, 102, 25)),
         2: ("Fifth Halo", (0, 102, 85, 103, 64, 108, 89, 84, 38)),
-        3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 102, 38)),
+        # Damping step 86 (about 5.2 kHz), where the card had 102 (8 kHz):
+        # at 8 kHz the sixth pass folded back past -30 dB at 22.05 kHz.
+        3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 86, 38)),
         4: ("Rise Damped", (127, 102, 113, 87, 96, 94, 64, 51, 32)),
         5: ("Falling Octaves", (127, 89, 85, 93, 0, 102, 64, 76, 32)),
         # Patch 0 in Rise at Rise 0: the S3's fallback if Bloom's line and
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index c8a77b8..a6a2ab5 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -636,8 +636,8 @@ def fold_read(cls, rate, f0, offset, lines=1, **options):
 
 
 #: Slow Rise's settings less Shimmer and Mix, which a read sets itself.
-def fold_shipped(patch):
-    options = patch_options(ShimmerHall, patch)
+def fold_shipped(patch, cls=ShimmerHall):
+    options = patch_options(cls, patch)
     del options["shimmer"], options["mix"]
     return options
 
@@ -646,13 +646,21 @@ def fold_shipped(patch):
 #: widest interval.
 FOLD_EDGES = (
     ("Rise 0.9, Damping 16 kHz", dict(rise=0.9, damping_hz=16000.0)),
-    ("+24", dict(interval=24)),
+    ("+24, Damping 8 kHz", dict(interval=24, damping_hz=8000.0)),
 )
 
 #: (rate, f0) cells, offset 41, where a pass folds clear of the series and
 #: of the splice's harmonics.
 FOLD_CELLS = ((48000, 240.0), (22050, 185.0))
 
+class OldSlowRise(ShimmerHall):
+    """The card's Slow Rise, Damping at 8 kHz (step 102): the sweep of
+    `test_no_upward_patch_folds_back` is red on it."""
+
+    PATCHES = dict(ShimmerHall.PATCHES)
+    PATCHES[3] = ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 102, 38))
+
+
 #: A fold line is loud when it stands within 30 dB of the loudest line of
 #: the first pass; the climb is clean when every fold line stays more than
 #: 40 dB under it.
@@ -863,6 +871,11 @@ def test_patches_are_the_card_settings_on_the_grid(self):
                 else:
                     want.append(_component.macro_of(
                         ShimmerHall._MACRO_RANGES[i], row[i]))
+            if index == 3:
+                # Retuned from the card's 8 kHz: Damping step 86, where the
+                # sixth pass no longer folds back past -30 dB at 22.05 kHz.
+                self.assertEqual(want[DAMPING_I], 102)
+                want[DAMPING_I] = 86
             self.assertEqual(ShimmerHall.PATCHES[index][1], tuple(want),
                              index)
 
@@ -1372,8 +1385,8 @@ class TheEdges(TestCase):
     def test_the_highest_octaves_fold_back_at_the_edges(self):
         # The same note and the same patch but for the edge: a fold line
         # stands within 30 dB of the first pass at Rise 0.9 with Damping at
-        # 16 kHz, and at +24, and stays under -40 dB at Slow Rise's and
-        # Rise Damped's own settings.
+        # 16 kHz, and at +24 with Damping at 8 kHz, and stays under -40 dB
+        # at Slow Rise's and Rise Damped's own settings.
         for rate, f0 in FOLD_CELLS:
             for patch in (3, 4):
                 rel, folds = fold_read(ShimmerHall, rate, f0, 41,
@@ -1387,6 +1400,25 @@ def test_the_highest_octaves_fold_back_at_the_edges(self):
                 self.assertGreater(max(rel), FOLD_LOUD,
                                    (rate, f0, name, rel, folds))
 
+    def test_no_upward_patch_folds_back(self):
+        # Every shipped patch with an upward loop, at both rates, over the
+        # card's range of notes in 10 Hz steps: no fold line comes within 30
+        # dB of the first pass. The card's Slow Rise (Damping 8 kHz) is red
+        # at 22.05 kHz, on 240 and 320 Hz.
+        for patch in (3, 4):
+            options = fold_shipped(patch)
+            for rate in RATES:
+                for f0 in range(165, 331, 10):
+                    rel, _folds = fold_read(ShimmerHall, rate, float(f0), 41,
+                                            lines=3, **options)
+                    for level in rel:
+                        self.assertLess(level, FOLD_LOUD, (patch, rate, f0))
+        old = fold_shipped(3, OldSlowRise)
+        self.assertNotEqual(old, fold_shipped(3))
+        worst = max(max(fold_read(OldSlowRise, 22050, f0, 41, lines=3,
+                                  **old)[0]) for f0 in (240.0, 320.0))
+        self.assertGreater(worst, FOLD_LOUD)
+
     def test_the_fold_chain_is_the_arithmetic(self):
         # +12 from 240 Hz at 48 kHz stays in band to 15360, then 30720
         # reflects to 17280; +24 from 240 Hz: 960, 3840, 15360, then 61440
@@ -1570,6 +1602,7 @@ def test_the_lean_hall_starts_at_once(self):
      "the highest octaves fold back down as tones outside the series; keep "
      "Damping lower for a clean climb.",
      ("test_the_highest_octaves_fold_back_at_the_edges",
+      "test_no_upward_patch_folds_back",
       "test_the_fold_chain_is_the_arithmetic")),
     ("A value outside a macro's span clamps to the nearer stop, and NaN "
      "takes the default; an `interval` other than the five raises "

From 8886b310af1840bcb8991dc30be164c822af1680 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 10:43:41 -0500
Subject: [PATCH 73/76] ShimmerHall: say the Bloom patches cannot keep up on an
 ESP32-S3 and to play a Rise patch there, pinned to the patches in Bloom

---
 lib/audioeffects/rebuilt/shimmerhall.py   | 10 ++++++----
 tests/test_cpython_effects_shimmerhall.py | 22 ++++++++++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index 14f2cfe..f2ef6bb 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -36,8 +36,10 @@
 your input stops: 82 s at Rise 0.9 and Bloom 800 ms. `reset()` empties the
 hall, the line and the shifter, and restores patch 0. The patches: Octave
 Bloom (the defaults), Short Stagger, Fifth Halo, Slow Rise, Rise Damped,
-Falling Octaves, Octave Bloom - lean. Octave Bloom - lean is Rise at Rise 0,
-for an S3: one octave, once, and the hall starts at once.
+Falling Octaves, Octave Bloom - lean. On an ESP32-S3 the Bloom patches
+(the defaults, Octave Bloom, Short Stagger and Fifth Halo) take longer than
+a block and cannot keep up, so play a Rise patch there. Octave Bloom - lean
+is Rise at Rise 0, for an S3: one octave, once, and the hall starts at once.
 
 **Limits**
 
@@ -285,8 +287,8 @@ class ShimmerHall(_component.Component):
         3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 86, 38)),
         4: ("Rise Damped", (127, 102, 113, 87, 96, 94, 64, 51, 32)),
         5: ("Falling Octaves", (127, 89, 85, 93, 0, 102, 64, 76, 32)),
-        # Patch 0 in Rise at Rise 0: the S3's fallback if Bloom's line and
-        # second shifter do not fit its memory.
+        # Patch 0 in Rise at Rise 0: the S3's patch nearest the defaults,
+        # since every Bloom patch runs over a block there.
         6: ("Octave Bloom - lean", (127, 89, 0, 90, 96, 94, 64, 91, 32)),
     }
 
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index a6a2ab5..d244855 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -1467,6 +1467,24 @@ def lean_levels(rate, f0, offset, patch):
 
 
 class TheLeanPatch(TestCase):
+    def test_the_bloom_patches_are_the_ones_named_for_the_s3(self):
+        # The S3 cost is measured on the boards (the evidence's board
+        # table: every Bloom patch over the bar, every Rise patch under);
+        # this pins the sentence's list to the patches in Bloom.
+        bloom = [name for name, steps in ShimmerHall.PATCHES.values()
+                 if steps[CHARACTER_I] < 64]
+        self.assertEqual(bloom, ["Octave Bloom", "Short Stagger",
+                                 "Fifth Halo"])
+        e = ShimmerHall(_port())
+        try:
+            self.assertEqual(e.macro(CHARACTER_I), 0.0)     # the defaults
+        finally:
+            e.deinit()
+        doc = " ".join(sys.modules[ShimmerHall.__module__].__doc__.split())
+        self.assertIn("the Bloom patches (the defaults, Octave Bloom, Short"
+                      " Stagger and Fifth Halo) take longer than a block",
+                      doc)
+
     def test_the_lean_patch_is_patch_0_in_rise_at_rise_0(self):
         steps = list(ShimmerHall.PATCHES[0][1])
         steps[CHARACTER_I] = 127
@@ -1588,6 +1606,10 @@ def test_the_lean_hall_starts_at_once(self):
     ("The patches: Octave Bloom (the defaults), Short Stagger, Fifth Halo, "
      "Slow Rise, Rise Damped, Falling Octaves, Octave Bloom - lean.",
      "test_macros_patches_tier_latency"),
+    ("On an ESP32-S3 the Bloom patches (the defaults, Octave Bloom, Short "
+     "Stagger and Fifth Halo) take longer than a block and cannot keep up, "
+     "so play a Rise patch there.",
+     "test_the_bloom_patches_are_the_ones_named_for_the_s3"),
     ("Octave Bloom - lean is Rise at Rise 0, for an S3: one octave, once, "
      "and the hall starts at once.",
      ("test_the_lean_patch_is_patch_0_in_rise_at_rise_0",

From daf9bfa2971cd7d48aff90aecbbcc2319d49a875 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 11:11:06 -0500
Subject: [PATCH 74/76] ShimmerHall: the defaults become Octave Rise, Octave
 Bloom in Rise at Rise 0, which an ESP32-S3 keeps up with; Octave Bloom moves
 to patch 6

Patch 0 is now Rise at Rise 0 (steps 127, 89, 0, 90, 96, 94, 64, 91, 32),
and the old defaults are patch 6, Octave Bloom. The S3 sentence names the
Bloom patches as they now are. Tests that measured Bloom at the defaults
ask for it by name, so every trait is still held where it was.
---
 CHANGELOG.md                              |   8 +-
 lib/audioeffects/rebuilt/shimmerhall.py   |  24 +--
 tests/test_cpython_effects_shimmerhall.py | 170 ++++++++++++----------
 3 files changed, 112 insertions(+), 90 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7d19b7..de55fb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,9 +16,11 @@ there, and are recorded in its changelog.
   an `audioecho.FeedbackDelay` loop (`loop_semitones`), so each pass comes
   back shifted again until Damping darkens it away. Nine macros (Character,
   Shimmer, Rise, Bloom, Interval, Decay, Size, Damping, Mix) and seven
-  patches (the last, "Octave Bloom - lean", is Rise at Rise 0, for a board
-  short of memory) replace the old Shimmer / Echo / Space / Tone surface and its
-  constructor arguments. The hall is the rebuilt `Reverb`. The dry passes
+  patches replace the old Shimmer / Echo / Space / Tone surface and its
+  constructor arguments. The defaults, patch 0 "Octave Rise", are Rise at
+  Rise 0: one octave, once, with the hall starting at once, which an
+  ESP32-S3 keeps up with where the Bloom patches (Octave Bloom, Short
+  Stagger, Fifth Halo) do not. The hall is the rebuilt `Reverb`. The dry passes
   untouched up to Mix 1, Mix 0 is a byte-exact wire, and the input ceiling
   is -24 dBFS. It lives in `lib/audioeffects/rebuilt/shimmerhall.py`, beside
   the old class in `rack.py`, until it is promoted.
diff --git a/lib/audioeffects/rebuilt/shimmerhall.py b/lib/audioeffects/rebuilt/shimmerhall.py
index f2ef6bb..e858b5c 100644
--- a/lib/audioeffects/rebuilt/shimmerhall.py
+++ b/lib/audioeffects/rebuilt/shimmerhall.py
@@ -35,11 +35,11 @@
 `tail_samples` bounds how long the output takes to reach exact zero once
 your input stops: 82 s at Rise 0.9 and Bloom 800 ms. `reset()` empties the
 hall, the line and the shifter, and restores patch 0. The patches: Octave
-Bloom (the defaults), Short Stagger, Fifth Halo, Slow Rise, Rise Damped,
-Falling Octaves, Octave Bloom - lean. On an ESP32-S3 the Bloom patches
-(the defaults, Octave Bloom, Short Stagger and Fifth Halo) take longer than
-a block and cannot keep up, so play a Rise patch there. Octave Bloom - lean
-is Rise at Rise 0, for an S3: one octave, once, and the hall starts at once.
+Rise (the defaults), Short Stagger, Fifth Halo, Slow Rise, Rise Damped,
+Falling Octaves, Octave Bloom. Octave Rise is Octave Bloom in Rise at Rise
+0: one octave, once, and the hall starts at once. On an ESP32-S3 the Bloom
+patches (Octave Bloom, Short Stagger and Fifth Halo) take longer than a
+block and cannot keep up; the defaults and every Rise patch keep up.
 
 **Limits**
 
@@ -143,7 +143,7 @@
 
 #: Each macro's patch-0 step; the constructor defaults are these steps'
 #: values, so a fresh instance is patch 0.
-DEFAULT_STEPS = (0, 89, 85, 90, 96, 94, 64, 91, 32)
+DEFAULT_STEPS = (127, 89, 0, 90, 96, 94, 64, 91, 32)
 
 
 def _default(index, span):
@@ -160,7 +160,7 @@ def _default(index, span):
 SIZE = _default(6, (0.5, 1.5))
 DAMPING_HZ = _default(7, (500.0, 16000.0, "log"))
 MIX = _default(8, (0.0, 2.0))
-DEFAULTS = (0.0, SHIMMER, RISE, BLOOM_MS, _default(4, (0.0, 5.0)), DECAY,
+DEFAULTS = (1.0, SHIMMER, RISE, BLOOM_MS, _default(4, (0.0, 5.0)), DECAY,
             SIZE, DAMPING_HZ, MIX)
 
 #: The hall's macros the rack drives, by `Reverb`'s labels.
@@ -279,7 +279,7 @@ class ShimmerHall(_component.Component):
 
     #: `_component.macro_of` of the card's settings.
     PATCHES = {
-        0: ("Octave Bloom", DEFAULT_STEPS),
+        0: ("Octave Rise", DEFAULT_STEPS),
         1: ("Short Stagger", (0, 76, 85, 38, 96, 77, 38, 102, 25)),
         2: ("Fifth Halo", (0, 102, 85, 103, 64, 108, 89, 84, 38)),
         # Damping step 86 (about 5.2 kHz), where the card had 102 (8 kHz):
@@ -287,12 +287,12 @@ class ShimmerHall(_component.Component):
         3: ("Slow Rise", (127, 89, 85, 103, 96, 108, 89, 86, 38)),
         4: ("Rise Damped", (127, 102, 113, 87, 96, 94, 64, 51, 32)),
         5: ("Falling Octaves", (127, 89, 85, 93, 0, 102, 64, 76, 32)),
-        # Patch 0 in Rise at Rise 0: the S3's patch nearest the defaults,
-        # since every Bloom patch runs over a block there.
-        6: ("Octave Bloom - lean", (127, 89, 0, 90, 96, 94, 64, 91, 32)),
+        # Patch 0 in Bloom, at the card's Rise: every Bloom patch runs over
+        # a block on an ESP32-S3, so the defaults are its Rise twin.
+        6: ("Octave Bloom", (0, 89, 85, 90, 96, 94, 64, 91, 32)),
     }
 
-    def _build(self, character="bloom", shimmer=SHIMMER, rise=RISE,
+    def _build(self, character="rise", shimmer=SHIMMER, rise=RISE,
                bloom_ms=BLOOM_MS, interval=12, decay=DECAY, size=SIZE,
                damping_hz=DAMPING_HZ, mix=MIX, patch=None):
         if character not in CHARACTERS:
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index d244855..dfe6925 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -274,15 +274,16 @@ def _dry_source(self):
 
 
 #: The kit's plant table. A Rise plant is judged at a Rise patch, a Bloom
-#: plant at the Bloom patch its fault shows plainest at.
+#: plant at the Bloom patch its fault shows plainest at: the defaults are
+#: Rise, so a Bloom plant always names its patch.
 KIT_PLANTS = {
     "T1": (PinnedStagger, 1),
     "T2": (AlwaysOctave, 2),
     "T3": (PinnedLoop, 3),
     "T4": (HeldFeedback, 4),
-    "T4b": RiseInBloom,
+    "T4b": (RiseInBloom, 6),
     "T5": (UndampedLoop, 4),
-    "T6": LateDry,
+    "T6": (LateDry, 6),
 }
 
 
@@ -295,8 +296,10 @@ def _dry_source(self):
 
 def t1_onset(cls, rate, f0, offset, bloom):
     frames = law_frames(bloom + 400.0, rate) + offset
-    s1 = wet(cls, rate, card_channels(rate), f0, offset, frames, bloom_ms=bloom, shimmer=1.0)
-    s0 = wet(cls, rate, card_channels(rate), f0, offset, frames, bloom_ms=bloom, shimmer=0.0)
+    s1 = wet(cls, rate, card_channels(rate), f0, offset, frames,
+             character="bloom", bloom_ms=bloom, shimmer=1.0)
+    s0 = wet(cls, rate, card_channels(rate), f0, offset, frames,
+             character="bloom", bloom_ms=bloom, shimmer=0.0)
     hz = 2.0 * f0
     size = hann_size(rate)
     window = hann(size)
@@ -344,7 +347,7 @@ def t2_read(cls, rate, character, interval, seed):
     """The energy-weighted mean shift of d = (Shimmer 1) - (Shimmer 0), in
     semitones, over the 500 ms from Bloom."""
     f0, offset = seed_set(seed)
-    # The card's patch-0 Bloom, which a default-built instance plays.
+    # The defaults' Bloom, Octave Bloom's too.
     bloom = 20.0 * 40.0 ** (90.0 / 127.0)
     start = law_frames(bloom, rate) + offset
     span = law_frames(500.0, rate)
@@ -753,27 +756,32 @@ def run(e):
     return values, out
 
 
+def _bloom(src, **options):
+    """Built in Bloom: the defaults are Rise."""
+    return ShimmerHall(src, character="bloom", **options)
+
+
 GET_BUFFER_CASES = (
     ("built at the defaults", ShimmerHall, {}),
-    ("built in Rise", lambda src: ShimmerHall(src, character="rise"), {}),
-    ("reset before the first pull", ShimmerHall, {0: lambda e: e.reset()}),
-    ("reset twice before the first pull", ShimmerHall,
+    ("built in Bloom", _bloom, {}),
+    ("reset before the first pull", _bloom, {0: lambda e: e.reset()}),
+    ("reset twice before the first pull", _bloom,
      {0: lambda e: (e.reset(), e.reset())}),
-    ("built at Mix 0, then patch 0", lambda src: ShimmerHall(src, mix=0.0),
-     {3: lambda e: e.program_change(0)}),
-    ("built at Mix 0, reset", lambda src: ShimmerHall(src, mix=0.0),
+    ("built at Mix 0, then Octave Bloom",
+     lambda src: _bloom(src, mix=0.0), {3: lambda e: e.program_change(6)}),
+    ("built at Mix 0, reset", lambda src: _bloom(src, mix=0.0),
      {3: lambda e: e.reset()}),
-    ("Mix 0 before the first block, back", ShimmerHall,
+    ("Mix 0 before the first block, back", _bloom,
      {0: lambda e: e.set_macro(MIX_I, 0), 4: lambda e: e.set_macro(MIX_I, 32)}),
-    ("Mix 0 after playing, reset twice", ShimmerHall,
+    ("Mix 0 after playing, reset twice", _bloom,
      {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: (e.reset(), e.reset())}),
-    ("a Character move and a reset in one block", ShimmerHall,
+    ("a Character move and a reset in one block", _bloom,
      {2: lambda e: (e.program_change(4), e.reset())}),
     ("built at Mix 2, reset after playing",
-     lambda src: ShimmerHall(src, mix=2.0), {3: lambda e: e.reset()}),
-    ("Mix 0 after playing, back to 127", ShimmerHall,
+     lambda src: _bloom(src, mix=2.0), {3: lambda e: e.reset()}),
+    ("Mix 0 after playing, back to 127", _bloom,
      {2: lambda e: e.set_macro(MIX_I, 0), 6: lambda e: e.set_macro(MIX_I, 127)}),
-    ("Mix 127 before the first pull", ShimmerHall,
+    ("Mix 127 before the first pull", _bloom,
      {0: lambda e: e.set_macro(MIX_I, 127)}),
 )
 
@@ -798,9 +806,9 @@ def test_macros_patches_tier_latency(self):
         self.assertEqual(ShimmerHall.CAPABILITIES, ())
         self.assertEqual(ShimmerHall.LATENCY_SAMPLES, 0)
         self.assertEqual([ShimmerHall.PATCHES[i][0] for i in range(7)],
-                         ["Octave Bloom", "Short Stagger", "Fifth Halo",
+                         ["Octave Rise", "Short Stagger", "Fifth Halo",
                           "Slow Rise", "Rise Damped", "Falling Octaves",
-                          "Octave Bloom - lean"])
+                          "Octave Bloom"])
         self.assertEqual(sorted(ShimmerHall.PATCHES), list(range(7)))
 
     def test_the_spans(self):
@@ -854,13 +862,16 @@ def test_the_constructor(self):
             e.deinit()
 
     def test_patches_are_the_card_settings_on_the_grid(self):
+        # Patch 0 is the card's Octave Bloom in Rise at Rise 0 (ruled
+        # 2026-10-13); the card's own Octave Bloom is patch 6.
         card = {
-            0: ("bloom", 0.7, 0.6, 275, 12, 4.0, 1.0, 6000, 0.5),
+            0: ("rise", 0.7, 0.0, 275, 12, 4.0, 1.0, 6000, 0.5),
             1: ("bloom", 0.6, 0.6, 60, 12, 2.5, 0.8, 8000, 0.4),
             2: ("bloom", 0.8, 0.6, 400, 7, 6.0, 1.2, 5000, 0.6),
             3: ("rise", 0.7, 0.6, 400, 12, 6.0, 1.2, 8000, 0.6),
             4: ("rise", 0.8, 0.8, 250, 12, 4.0, 1.0, 2000, 0.5),
             5: ("rise", 0.7, 0.6, 300, -12, 5.0, 1.0, 4000, 0.5),
+            6: ("bloom", 0.7, 0.6, 275, 12, 4.0, 1.0, 6000, 0.5),
         }
         zones = dict(zip(INTERVALS, (0, 32, 64, 96, 127)))
         for index, row in card.items():
@@ -886,7 +897,7 @@ def test_a_fresh_instance_reads_patch_0(self):
                              ShimmerHall.PATCHES[0][1])
             self.assertEqual(e.patch_index, 0)
             values = [e.macro(i) for i in range(9)]
-            want = [0.0, 0.7008, 0.6024, 273.1, 12.0, 4.0206, 1.00394,
+            want = [1.0, 0.7008, 0.0, 273.1, 12.0, 4.0206, 1.00394,
                     5990.5, 0.5039]
             for got, card in zip(values, want):
                 self.assertAlmostEqual(got, card, delta=abs(card) * 1e-4)
@@ -904,7 +915,7 @@ def test_patches_play_the_same_whatever_the_constructor_said(self):
             # half-cycle would play at the constructor's Mix.
             for options in ({}, dict(shimmer=0.37, rise=0.71, bloom_ms=33.3,
                                      interval=-5, decay=7.7, size=0.61,
-                                     damping_hz=777.0, character="rise")):
+                                     damping_hz=777.0, character="bloom")):
                 feed = kc.feed(values, 48000, 2)
                 e = ShimmerHall(feed.port, **options)
                 e.program_change(patch)
@@ -945,7 +956,8 @@ def test_mix_0_is_the_input(self):
     def test_no_latency(self):
         values = array("h", bytes(2 * 2 * 4096))
         values[2000] = values[2001] = 12000
-        out = render(ShimmerHall, values, 48000, 2, 4096, mix=1.0)
+        out = render(ShimmerHall, values, 48000, 2, 4096, mix=1.0,
+                     character="bloom")
         self.assertEqual(out[2000], 12000)
         self.assertEqual(list(out[:2000]), [0] * 2000)
 
@@ -1015,7 +1027,7 @@ def test_a_character_move_recuts_the_wet_chain(self):
         # After a Character move, the wet path renders as a fresh
         # instance's in that character, and the dry carries on.
         values = t6_material(48000, 2, 2)
-        for start, end in (("bloom", 3), ("rise", 0)):
+        for start, end in (("bloom", 3), ("rise", 6)):
             fresh_wet = render(ShimmerHall, values[2 * 9728:], 48000, 2,
                                19200, patch=end)
             feed = kc.feed(values, 48000, 2)
@@ -1089,28 +1101,29 @@ def _same_as_fresh(self, build, moves, fresh_from, fresh_options,
 
     def test_a_reset_from_mix_2_plays_the_dry_from_frame_0(self):
         self._same_as_fresh(
-            lambda port: ShimmerHall(port, mix=2.0),
+            lambda port: _bloom(port, mix=2.0),
             {6: lambda e: e.reset()}, 6, {}, name="reset from Mix 2")
 
     def test_a_reset_before_the_first_pull_plays_the_dry_from_frame_0(self):
         self._same_as_fresh(
-            lambda port: ShimmerHall(port, mix=2.0),
+            lambda port: _bloom(port, mix=2.0),
             {0: lambda e: e.reset()}, 0, {}, name="reset before a pull")
 
     def test_a_return_from_mix_0_plays_the_dry_from_frame_0(self):
         self._same_as_fresh(
-            ShimmerHall,
+            _bloom,
             {2: lambda e: e.set_macro(MIX_I, 0),
-             6: lambda e: e.set_macro(MIX_I, 127)}, 6, dict(mix=2.0),
-            name="Mix 0 then 127")
+             6: lambda e: e.set_macro(MIX_I, 127)}, 6,
+            dict(mix=2.0, character="bloom"), name="Mix 0 then 127")
 
     def test_a_mix_move_before_the_first_pull_plays_the_dry_from_frame_0(
             self):
         self._same_as_fresh(
-            ShimmerHall, {0: lambda e: e.set_macro(MIX_I, 127)}, 0,
-            dict(mix=2.0), name="Mix 127 before the first pull")
+            _bloom, {0: lambda e: e.set_macro(MIX_I, 127)}, 0,
+            dict(mix=2.0, character="bloom"),
+            name="Mix 127 before the first pull")
         self._same_as_fresh(
-            ShimmerHall, {0: lambda e: e.program_change(1)}, 0,
+            _bloom, {0: lambda e: e.program_change(1)}, 0,
             dict(patch=1), name="patch 1 before the first pull")
 
     def test_a_reset_from_rise_plays_as_a_new_instance(self):
@@ -1136,7 +1149,7 @@ def wrapped():
                 ("interval", lambda e: e.set_macro(INTERVAL_I, 0), 0),
                 ("patch 2", lambda e: e.program_change(2), 1),
                 ("mix 127", lambda e: e.set_macro(MIX_I, 127), 1)):
-            e = ShimmerHall(_port())
+            e = _bloom(_port())
             try:
                 count = counted(e)
                 move(e)
@@ -1144,7 +1157,7 @@ def wrapped():
             finally:
                 e.deinit()
             self.assertEqual(count[0], rearms, name)
-        e = ShimmerHall(_port(), mix=2.0)
+        e = _bloom(_port(), mix=2.0)
         try:
             count = counted(e)
             e.output
@@ -1179,7 +1192,8 @@ def test_a_rack_holding_it_resets_to_a_fresh_racks_render(self):
             values = array("h", [rng.next() % 20001 - 10000
                                  for _ in range(frames * channels)])
             other = array("h", [-v // 2 for v in values])
-            for options in ({}, dict(mix=2.0), off_grid):
+            for options in ({}, dict(mix=2.0), dict(character="bloom"),
+                            dict(character="bloom", mix=2.0), off_grid):
                 chain = ((ShimmerHall, options),)
                 fresh = rack_class.create(
                     kc.feed(values, rate, channels).port, rate, chain=chain)
@@ -1211,10 +1225,12 @@ def test_an_output_taken_before_mix_moves_plays_the_old_level_at_first(
             blocks = 14
             values = self._dc(rate, channels, blocks)
             for name, options, move, fresh in (
-                    ("Mix 127", {}, lambda e: e.set_macro(MIX_I, 127),
-                     dict(mix=2.0)),
-                    ("patch 0 from Mix 2", dict(mix=2.0),
-                     lambda e: e.program_change(0), {})):
+                    ("Mix 127", dict(character="bloom"),
+                     lambda e: e.set_macro(MIX_I, 127),
+                     dict(mix=2.0, character="bloom")),
+                    ("Octave Bloom from Mix 2",
+                     dict(mix=2.0, character="bloom"),
+                     lambda e: e.program_change(6), dict(patch=6))):
                 e = ShimmerHall(kc.feed(values, rate, channels).port,
                                 **options)
                 try:
@@ -1377,7 +1393,7 @@ def test_the_dry_never_carries_the_shimmer(self):
                     self.assertLess(loud, 32767, (rate, channels, patch))
 
     def test_late_dry_is_red(self):
-        worst, _loud = t6_read(LateDry, 48000, 2, 0, 1)
+        worst, _loud = t6_read(LateDry, 48000, 2, 6, 1)
         self.assertGreater(worst, 1000)
 
 
@@ -1466,32 +1482,35 @@ def lean_levels(rate, f0, offset, patch):
     return [db(x) - db(levels[0]) for x in levels]
 
 
-class TheLeanPatch(TestCase):
+class TheDefaults(TestCase):
     def test_the_bloom_patches_are_the_ones_named_for_the_s3(self):
         # The S3 cost is measured on the boards (the evidence's board
         # table: every Bloom patch over the bar, every Rise patch under);
-        # this pins the sentence's list to the patches in Bloom.
+        # this pins the sentence's list to the patches in Bloom, and the
+        # defaults to Rise.
         bloom = [name for name, steps in ShimmerHall.PATCHES.values()
                  if steps[CHARACTER_I] < 64]
-        self.assertEqual(bloom, ["Octave Bloom", "Short Stagger",
-                                 "Fifth Halo"])
+        self.assertEqual(bloom, ["Short Stagger", "Fifth Halo",
+                                 "Octave Bloom"])
         e = ShimmerHall(_port())
         try:
-            self.assertEqual(e.macro(CHARACTER_I), 0.0)     # the defaults
+            self.assertEqual(e.macro(CHARACTER_I), 1.0)     # the defaults
         finally:
             e.deinit()
         doc = " ".join(sys.modules[ShimmerHall.__module__].__doc__.split())
-        self.assertIn("the Bloom patches (the defaults, Octave Bloom, Short"
-                      " Stagger and Fifth Halo) take longer than a block",
+        self.assertIn("the Bloom patches (Octave Bloom, Short Stagger and"
+                      " Fifth Halo) take longer than a block and cannot"
+                      " keep up; the defaults and every Rise patch keep up.",
                       doc)
 
-    def test_the_lean_patch_is_patch_0_in_rise_at_rise_0(self):
-        steps = list(ShimmerHall.PATCHES[0][1])
+    def test_the_defaults_are_octave_bloom_in_rise_at_rise_0(self):
+        steps = list(ShimmerHall.PATCHES[6][1])
         steps[CHARACTER_I] = 127
         steps[RISE_I] = 0
-        self.assertEqual(ShimmerHall.PATCHES[6][1], tuple(steps))
-        self.assertEqual(ShimmerHall.PATCHES[6][0], "Octave Bloom - lean")
-        e = ShimmerHall(_port(), patch=6)
+        self.assertEqual(ShimmerHall.PATCHES[0][1], tuple(steps))
+        self.assertEqual(ShimmerHall.PATCHES[0][0], "Octave Rise")
+        self.assertEqual(ShimmerHall.PATCHES[6][0], "Octave Bloom")
+        e = ShimmerHall(_port())
         try:
             self.assertEqual(e.macro(CHARACTER_I), 1.0)
             self.assertEqual(e.macro(RISE_I), 0.0)
@@ -1499,24 +1518,24 @@ def test_the_lean_patch_is_patch_0_in_rise_at_rise_0(self):
         finally:
             e.deinit()
 
-    def test_the_lean_patch_is_one_octave_once(self):
+    def test_the_defaults_are_one_octave_once(self):
         # Rise 0.9 climbs: the second and the third octave are in the
-        # shimmer within 30 dB of the first. At the lean patch only the
+        # shimmer within 30 dB of the first. At the defaults only the
         # first is there, and the others stand more than 40 dB under it.
         for rate, f0 in ((48000, 247.0), (22050, 220.0)):
-            lean = lean_levels(rate, f0, 13, 6)
+            lean = lean_levels(rate, f0, 13, 0)
             self.assertLess(max(lean[1:]), -40.0, (rate, lean))
         climbing = lean_levels(48000, 247.0, 13, 3)
         self.assertGreater(climbing[1], -30.0, climbing)
 
-    def test_the_lean_hall_starts_at_once(self):
-        # Patch 0 holds the whole hall for Bloom (273 ms); the lean patch
-        # plays the dry into it at once.
+    def test_the_defaults_hall_starts_at_once(self):
+        # Octave Bloom holds the whole hall for Bloom (273 ms); the
+        # defaults play the dry into it at once.
         for rate in RATES:
             channels = card_channels(rate)
             frames = law_frames(150.0, rate)
             heard = []
-            for patch in (0, 6):
+            for patch in (6, 0):
                 out = wet(ShimmerHall, rate, channels, 247.0, 0, frames,
                           **patch_options(ShimmerHall, patch, mix=2.0))
                 heard.append(max(abs(x) for x in out))
@@ -1603,18 +1622,19 @@ def test_the_lean_hall_starts_at_once(self):
      "the first 256 frames, 5 ms at 48 kHz, play at the old level.",
      ("test_an_output_taken_before_mix_moves_plays_the_old_level_at_first",
       "test_only_a_move_that_changes_a_voice_level_re_arms")),
-    ("The patches: Octave Bloom (the defaults), Short Stagger, Fifth Halo, "
-     "Slow Rise, Rise Damped, Falling Octaves, Octave Bloom - lean.",
-     "test_macros_patches_tier_latency"),
-    ("On an ESP32-S3 the Bloom patches (the defaults, Octave Bloom, Short "
-     "Stagger and Fifth Halo) take longer than a block and cannot keep up, "
-     "so play a Rise patch there.",
+    ("The patches: Octave Rise (the defaults), Short Stagger, Fifth Halo, "
+     "Slow Rise, Rise Damped, Falling Octaves, Octave Bloom.",
+     ("test_macros_patches_tier_latency",
+      "test_a_fresh_instance_reads_patch_0")),
+    ("Octave Rise is Octave Bloom in Rise at Rise 0: one octave, once, and "
+     "the hall starts at once.",
+     ("test_the_defaults_are_octave_bloom_in_rise_at_rise_0",
+      "test_the_defaults_are_one_octave_once",
+      "test_the_defaults_hall_starts_at_once")),
+    ("On an ESP32-S3 the Bloom patches (Octave Bloom, Short Stagger and "
+     "Fifth Halo) take longer than a block and cannot keep up; the defaults "
+     "and every Rise patch keep up.",
      "test_the_bloom_patches_are_the_ones_named_for_the_s3"),
-    ("Octave Bloom - lean is Rise at Rise 0, for an S3: one octave, once, "
-     "and the hall starts at once.",
-     ("test_the_lean_patch_is_patch_0_in_rise_at_rise_0",
-      "test_the_lean_patch_is_one_octave_once",
-      "test_the_lean_hall_starts_at_once")),
     ("Interval is a fixed shift in semitones, with no key awareness.",
      "test_interval_has_five_zones"),
     ("In Rise, on some held notes the shimmer lands beside the octave "
@@ -1725,11 +1745,11 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
                         worst = max(worst, w)
                         loud = max(loud, lo)
                         runs += 1
-        plant = t6_read(LateDry, 48000, 2, 0, 1)[0]
+        plant = t6_read(LateDry, 48000, 2, 6, 1)[0]
         print("%s|T6|runs %d|worst %d LSB|loudest %d|plant %d LSB" % (
             name, runs, worst, loud, plant))
     if "F" in which:
-        for patch in (3, 4, 6):
+        for patch in (3, 4, 0):
             options = fold_shipped(patch)
             for rate in RATES:
                 worst = -999.0
@@ -1740,7 +1760,7 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
                     for level in rel:
                         worst = max(worst, level)
                 # Exact silence where the pass never comes (Rise damped to
-                # nothing, or the lean patch's loop).
+                # nothing, or the defaults' loop at Rise 0).
                 print("%s|F|patch %d %s|%d|worst fold line %s over %d "
                       "notes|bar %.0f" % (
                           name, patch, ShimmerHall.PATCHES[patch][0], rate,
@@ -1779,7 +1799,7 @@ def figures(which=("T1", "T2", "T3", "T4", "T5", "T6", "L")):
                 for c in range(channels):
                     values[1000 * channels + c] = 12000
                 out = render(ShimmerHall, values, rate, channels, 4096,
-                             mix=1.0)
+                             mix=1.0, character="bloom")
                 first = None
                 for n in range(4096):
                     if out[n * channels]:

From 72a68a9489596eb42c397f28ea4e16ada3800565 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 11:31:25 -0500
Subject: [PATCH 75/76] StereoWidener, Rack, Octaver, PitchShifter, Harmonizer,
 AirSpace and ShimmerHall are adopted: Phase 6's seven

ADOPTED names all seven, so audioeffects.<Name> and create() serve the
rebuilds. They stay under rebuilt/, and pitch.py and rack.py keep the old
classes until the rebuilds are promoted.

The old ShimmerHall built its octave branch by NAME with the old Octaver's
down= and up=, which the rebuild refuses, so it now names pitch.Octaver
directly, as it already does for the tape delay and the reverb. Its render
and AirSpace's old rack are unchanged when built from rack.py.

Tests: each class gains an "adopted is what the package serves" test (create()
returns the rebuild), and the registry names all fifteen adopted classes; with
ADOPTED cut back to the first eight, all of them go red. The tests written
against the old classes by their served name now name them from their own
module: test_cpython_effects_pitch (the shifter-based Octaver's octave reach
and shifter count) and test_cpython_effects_racks (the old Rack, ShimmerHall
and AirSpace). Their assertions are unchanged.

The CHANGELOG entries for the seven say they are adopted (2026-10-13), and the
note on the soundtrack racks now includes the octaver.

Gates, this tree: validate_api 55 instruments / 45 effects; metadata valid;
flake8 clean; contract and the seven classes' scoped tests, the kit and the
registry OK; the library smoke 45 classes, 318 patches, 0 failures on
CPython, MicroPython and CircuitPython. The CPython digest census (burst plus
two seconds, every served class at the defaults and every patch) moves only
the six served names whose rebuilds differ from the old classes, onto the
rebuilds' own digests; Rack's default chain is a wire either way, and every
other class is byte-identical.
---
 CHANGELOG.md                                | 47 ++++++++++++---------
 lib/audioeffects/rack.py                    | 14 +++---
 lib/audioeffects/rebuilt/__init__.py        | 12 ++++++
 tests/test_cpython_effects_airspace.py      | 19 +++++++++
 tests/test_cpython_effects_harmonizer.py    | 19 +++++++++
 tests/test_cpython_effects_octaver.py       | 19 +++++++++
 tests/test_cpython_effects_pitch.py         | 13 +++---
 tests/test_cpython_effects_pitchshifter.py  | 19 +++++++++
 tests/test_cpython_effects_rack.py          | 19 +++++++++
 tests/test_cpython_effects_racks.py         | 40 ++++++++++--------
 tests/test_cpython_effects_shimmerhall.py   | 19 +++++++++
 tests/test_cpython_effects_stereowidener.py | 19 +++++++++
 tests/test_rebuilt_registry.py              |  6 ++-
 13 files changed, 213 insertions(+), 52 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f84fab6..6481d6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ there, and are recorded in its changelog.
 
 ### Added
 
-- **`ShimmerHall` (rebuilt, Phase 6):** a pitch shifter around a hall, in
+- **`ShimmerHall` (rebuilt, Phase 6; adopted 2026-10-13):** a pitch shifter around a hall, in
   two characters. Bloom sends the shifted copy into the hall once, Bloom
   after you play, on `audiodelays.PitchShift`; Rise puts the shift inside
   an `audioecho.FeedbackDelay` loop (`loop_semitones`), so each pass comes
@@ -20,9 +20,10 @@ there, and are recorded in its changelog.
   short of memory) replace the old Shimmer / Echo / Space / Tone surface and its
   constructor arguments. The hall is the rebuilt `Reverb`. The dry passes
   untouched up to Mix 1, Mix 0 is a byte-exact wire, and the input ceiling
-  is -24 dBFS. It lives in `lib/audioeffects/rebuilt/shimmerhall.py`, beside
-  the old class in `rack.py`, until it is promoted.
-- **`AirSpace` (rebuilt, Phase 6; not yet adopted):** a tape echo sent
+  is -24 dBFS. It is what `audioeffects.ShimmerHall` and `create()` now
+  serve. It lives in `lib/audioeffects/rebuilt/shimmerhall.py`, beside the
+  old class in `rack.py`, until it is promoted.
+- **`AirSpace` (rebuilt, Phase 6; adopted 2026-10-13):** a tape echo sent
   into a chamber, with the dry untouched beside it, in
   `audioeffects/rebuilt/airspace.py`. Eleven macros (Time, Feedback, Glide,
   Drive, Loop Top, Loop Bass, Top Cut, Low Cut, Decay, Damping, Mix) and
@@ -30,16 +31,18 @@ there, and are recorded in its changelog.
   darkens each repeat, Top Cut darkens the send once, Feedback stretches the
   chamber's tail, and a Time move bends the repeats' pitch. The chamber is
   the rebuilt `Reverb`, and `reset()` renders exactly as a fresh instance.
-  The old `rack.AirSpace` stays what the library serves until adoption.
-- **`Harmonizer` (rebuilt, Phase 6):** three pitch shifters at fixed
+  It is what `audioeffects.AirSpace` and `create()` now serve; the old
+  `rack.AirSpace` stays beside it until the rebuild is promoted.
+- **`Harmonizer` (rebuilt, Phase 6; adopted 2026-10-13):** three pitch shifters at fixed
   intervals under the dry, after three Eventide H910s played from one
   keyboard. Each voice is its own `audiodelays.PitchShift` on its own
   splitter tap and lands on the nearest step the shifter can play; a
   voice at its Level's bottom step is off and its shifter is not pulled.
   Ten controls (Pitch, Voice 1 to 3, Level 1 to 3, Detune, Spread, Mix),
   seven patches including a lean two-voice one, and a `window_ms` option.
-  It drops the old class's `intervals=` and `level=` options.
-- **`PitchShifter` (rebuilt, Phase 6):** a fixed-interval splice shifter
+  It drops the old class's `intervals=` and `level=` options, and is what
+  `audioeffects.Harmonizer` and `create()` now serve.
+- **`PitchShifter` (rebuilt, Phase 6; adopted 2026-10-13):** a fixed-interval splice shifter
   in the manner of the first harmonizers, on a Pitch, Fine, Mix, Delay and
   Feedback surface. Pitch moves in whole semitones an octave either way and
   Fine detunes by up to 50 cents; the dry passes untouched up to Mix 1;
@@ -47,17 +50,19 @@ there, and are recorded in its changelog.
   every repeat is shifted again, so a fifth climbs a fifth at a time.
   `window_ms` (15 to 60, 30 by default) sets the splice window at
   construction. The old `semitones=` option is gone: Pitch and Fine
-  replace it.
-- **`StereoWidener` (rebuilt, Phase 6):** two characters on a Width, Delay
+  replace it. It is what `audioeffects.PitchShifter` and `create()` now
+  serve.
+- **`StereoWidener` (rebuilt, Phase 6; adopted 2026-10-13):** two characters on a Width, Delay
   and Character surface. Haas delays the right channel 1 to 40 ms behind the
   left, crossfading the right toward its late copy up to Width 1 and turning
   the left down above it; Mid/Side scales the difference between the
   channels and leaves the sum alone. A mono source passes untouched, and a
   Delay move glides instead of clicking. The old `delay_ms=`/`width=`
-  options keep their names with these meanings.
-- **`Rack` (rebuilt, Phase 6):** the serial chain on the contract's base, in
+  options keep their names with these meanings. It is what
+  `audioeffects.StereoWidener` and `create()` now serve.
+- **`Rack` (rebuilt, Phase 6; adopted 2026-10-13):** the serial chain on the contract's base, in
   `rebuilt/rack.py` beside the old class, which stays until the rebuild is
-  promoted. `chain=` keeps its meaning and also takes a bare effect class. It
+  promoted. It is what `audioeffects.Rack` and `create()` now serve. `chain=` keeps its meaning and also takes a bare effect class. It
   renders exactly the same pedals patched by hand; `latency_samples` and
   `tail_samples` are live sums; `reset()` clears every pedal and puts each
   back to the settings the rack built it with; `deinit()` releases every
@@ -67,13 +72,14 @@ there, and are recorded in its changelog.
   and a rack's restore now share one private path in the base,
   `_apply_positions`, which the classes that did work once per patch moved
   onto.
-- **`Octaver` (rebuilt, Phase 6):** the analog octave-down, after the
+- **`Octaver` (rebuilt, Phase 6; adopted 2026-10-13):** the analog octave-down, after the
   Boss OC-2. The octave is your own note with every other cycle turned
   over, clocked from a low-passed copy and multiplied into an all-passed
   one, so it keeps your attack and decay and tracks from E2 to A4 at the
   default. Seven controls: Direct, Octave 1, Octave 2, Tracking, Tone 1,
   Tone 2 and Sensitivity, and six patches. It drops the shifter-based
-  class's octave up and its `down=`, `up=`, `down2=` and `up2=` options.
+  class's octave up and its `down=`, `up=`, `down2=` and `up2=` options,
+  and is what `audioeffects.Octaver` and `create()` now serve.
 - MultiTapDelay: the docstring says which patches need a P4-class board (patch 4 does, patch 3 may), from the boards' figures at audiodsp v0.6.3
 - **`DigitalDelay` (rebuilt, Phase 5; adopted 2026-09-28):** a clean
   interpolated line with the Boss DD-2's control law on one
@@ -289,11 +295,12 @@ there, and are recorded in its changelog.
 ### Changed
 
 - **`ShimmerHall` and `AirSpace` keep the classes they were ported
-  against.** With the Phase 5 `TapeDelay` and `Reverb` adopted, the two
-  racks name the old `delay.TapeDelay` and `reverb.Reverb` directly (a
-  `Rack` chain entry may now be a class in place of a `NAME`), so they
-  build and sound as before; moving them onto the rebuilds would re-voice
-  them. A chain that names `"Reverb"` gets the rebuild, which takes
+  against.** With the Phase 5 `TapeDelay` and `Reverb` and the Phase 6
+  `Octaver` adopted, the two old racks (`rack.ShimmerHall` and
+  `rack.AirSpace`) name the old `delay.TapeDelay`, `reverb.Reverb` and
+  `pitch.Octaver` directly (a `Rack` chain entry may now be a class in
+  place of a `NAME`), so they build and sound as before; moving them onto
+  the rebuilds would re-voice them. A chain that names `"Reverb"` gets the rebuild, which takes
   `character=` where the old class took `preset=`.
 - **The audiodsp pin moves to v0.6.3rc3.** The release carries the
   convolution node's two fixes (audiodsp#165: the block in flight kept
diff --git a/lib/audioeffects/rack.py b/lib/audioeffects/rack.py
index 9730114..fce6c78 100644
--- a/lib/audioeffects/rack.py
+++ b/lib/audioeffects/rack.py
@@ -21,11 +21,12 @@
 used by other racks: a `chain` entry may itself be a `("Rack", {...})`.
 
 Those two racks name the classes they were ported against, `delay.py`'s
-`TapeDelay` and `reverb.py`'s `Reverb`, directly rather than by NAME: the
-rebuilt classes the package serves under those names since their adoption
-on 2026-09-29 take different settings (no `preset`, no `wow`) and sound
-different, and moving a rack onto them is a re-voicing of the rack, not a
-part of the adoption.
+`TapeDelay`, `pitch.py`'s `Octaver` and `reverb.py`'s `Reverb`, directly
+rather than by NAME: the rebuilt classes the package serves under those
+names (since 2026-09-29 for the delay and reverb, 2026-10-13 for the
+octaver) take different settings (no `preset`, no `wow`, no `down` or `up`)
+and sound different, and moving a rack onto them is a re-voicing of the
+rack, not a part of the adoption.
 """
 
 VENDOR = "PyDevices"
@@ -35,6 +36,7 @@
 from ._component import midi_of_position as _midi_of_position
 from ._component import port_target as _port_target
 from .delay import TapeDelay as _OldTapeDelay
+from .pitch import Octaver as _OldOctaver
 from .reverb import Reverb as _OldReverb
 
 
@@ -192,7 +194,7 @@ def __init__(self, source, shimmer=0.55, echo=0.36, space=0.42,
         # macro moves the branch's mixer level, and a branch that was
         # skipped for starting at zero could never come back.
         Rack.__init__(self, source, chain=(
-            ("Octaver", {"down": 0.0, "up": 1.0}),
+            (_OldOctaver, {"down": 0.0, "up": 1.0}),
             (_OldTapeDelay, {"time_ms": 420.0, "feedback": 0.5,
                              "wow": 0.3, "drive": 0.2}),
             (_OldReverb, {"preset": "hall"}),
diff --git a/lib/audioeffects/rebuilt/__init__.py b/lib/audioeffects/rebuilt/__init__.py
index d3e7616..ad2e4c0 100644
--- a/lib/audioeffects/rebuilt/__init__.py
+++ b/lib/audioeffects/rebuilt/__init__.py
@@ -114,6 +114,11 @@ def _present():
 #: (audiocomponents#75); Reverb's patch 7 differs from that build by nine
 #: one-LSB samples of 65536 (audiodsp#183). They stay under this directory
 #: with the first two, for the same reason.
+#:
+#: Phase 6's seven, adopted 2026-10-13: `StereoWidener`, `Rack`, `Octaver`,
+#: `PitchShifter`, `Harmonizer`, `AirSpace` and `ShimmerHall`. They stay
+#: under this directory, and `pitch.py` and `rack.py` keep the old classes,
+#: until they come home.
 ADOPTED = (
     "DigitalDelay",
     "SlapbackDelay",
@@ -123,6 +128,13 @@ def _present():
     "MultiTapDelay",
     "Reverb",
     "ConvolutionReverb",
+    "StereoWidener",
+    "Rack",
+    "Octaver",
+    "PitchShifter",
+    "Harmonizer",
+    "AirSpace",
+    "ShimmerHall",
 )
 
 
diff --git a/tests/test_cpython_effects_airspace.py b/tests/test_cpython_effects_airspace.py
index 030746c..9bb7791 100644
--- a/tests/test_cpython_effects_airspace.py
+++ b/tests/test_cpython_effects_airspace.py
@@ -687,6 +687,25 @@ def fresh(rate=48000, channels=2, patch=None, **options):
     return build(AirSpace, data, rate, channels, patch, **options)
 
 
+class TheAdoption(unittest.TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("AirSpace", rebuilt.ADOPTED)
+        self.assertNotIn("AirSpace", rebuilt.parked())
+        self.assertIs(audioeffects.AirSpace, AirSpace)
+        served = audioeffects.create(
+            "AirSpace",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, AirSpace)
+        served.deinit()
+
+
 class TheSurface(unittest.TestCase):
 
     def test_the_spans(self):
diff --git a/tests/test_cpython_effects_harmonizer.py b/tests/test_cpython_effects_harmonizer.py
index 2ace555..b3120cf 100644
--- a/tests/test_cpython_effects_harmonizer.py
+++ b/tests/test_cpython_effects_harmonizer.py
@@ -1117,6 +1117,25 @@ def test_the_bare_tap_is_red(self):
 # The surface, the wire, the tail
 
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("Harmonizer", rebuilt.ADOPTED)
+        self.assertNotIn("Harmonizer", rebuilt.parked())
+        self.assertIs(audioeffects.Harmonizer, Harmonizer)
+        served = audioeffects.create(
+            "Harmonizer",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, Harmonizer)
+        served.deinit()
+
+
 class TheSurface(TestCase):
 
     def _fresh(self, rate=48000, channels=2, **options):
diff --git a/tests/test_cpython_effects_octaver.py b/tests/test_cpython_effects_octaver.py
index c8ebbe6..e0a2094 100644
--- a/tests/test_cpython_effects_octaver.py
+++ b/tests/test_cpython_effects_octaver.py
@@ -957,6 +957,25 @@ def test_tone_1_at_twice_its_hertz_is_red(self):
         self.assertGreater(max(misses), 0.25, misses)
 
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("Octaver", rebuilt.ADOPTED)
+        self.assertNotIn("Octaver", rebuilt.parked())
+        self.assertIs(audioeffects.Octaver, Octaver)
+        served = audioeffects.create(
+            "Octaver",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, Octaver)
+        served.deinit()
+
+
 class TheSurface(TestCase):
     """The controls, the wire, latency, tail, reset and tempo."""
 
diff --git a/tests/test_cpython_effects_pitch.py b/tests/test_cpython_effects_pitch.py
index 329b40b..bc270c5 100644
--- a/tests/test_cpython_effects_pitch.py
+++ b/tests/test_cpython_effects_pitch.py
@@ -18,7 +18,9 @@
 import sys
 import unittest
 
-import audioeffects
+# `pitch.Octaver` is the old class, which `audioeffects.Octaver` served until
+# the Phase 6 rebuild's adoption on 2026-10-13.
+from audioeffects import pitch
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "support"))
 from effects_measure import peak, source  # noqa: E402
@@ -26,11 +28,11 @@
 
 class PitchTest(unittest.TestCase):
     def test_an_octaver_reaches_two_octaves_either_way(self):
-        deep = audioeffects.Octaver(source(), down=0.4, down2=0.4)
+        deep = pitch.Octaver(source(), down=0.4, down2=0.4)
         self.assertEqual(deep.down2.semitones, -24.0)
         self.assertIsNone(deep.up)
         self.assertGreater(peak(deep.output, 12), 0.001)
-        high = audioeffects.Octaver(source(), down=0.0, up=0.4, up2=0.4)
+        high = pitch.Octaver(source(), down=0.0, up=0.4, up2=0.4)
         self.assertEqual(high.up2.semitones, 24.0)
         self.assertIsNone(high.down)
 
@@ -38,11 +40,10 @@ def test_an_octaver_builds_only_the_octaves_it_was_asked_for(self):
         # A Splitter fans out to four taps, so the dry signal plus three
         # octaves is the ceiling - and the default, one octave down, should
         # cost one shifter rather than four.
-        one = audioeffects.Octaver(source())
+        one = pitch.Octaver(source())
         self.assertEqual(len(one.mixer.voice), 2)
         with self.assertRaises(ValueError):
-            audioeffects.Octaver(source(), down=0.3, down2=0.3, up=0.3,
-                                 up2=0.3)
+            pitch.Octaver(source(), down=0.3, down2=0.3, up=0.3, up2=0.3)
 
 
 if __name__ == "__main__":
diff --git a/tests/test_cpython_effects_pitchshifter.py b/tests/test_cpython_effects_pitchshifter.py
index 597a7df..53b9b42 100644
--- a/tests/test_cpython_effects_pitchshifter.py
+++ b/tests/test_cpython_effects_pitchshifter.py
@@ -622,6 +622,25 @@ def run(e):
 # The tests
 
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("PitchShifter", rebuilt.ADOPTED)
+        self.assertNotIn("PitchShifter", rebuilt.parked())
+        self.assertIs(audioeffects.PitchShifter, PitchShifter)
+        served = audioeffects.create(
+            "PitchShifter",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, PitchShifter)
+        served.deinit()
+
+
 class TheSurface(TestCase):
     def test_macros_patches_tier_latency(self):
         self.assertEqual(PitchShifter.MACRO_LABELS,
diff --git a/tests/test_cpython_effects_rack.py b/tests/test_cpython_effects_rack.py
index f9de48f..0c3b938 100644
--- a/tests/test_cpython_effects_rack.py
+++ b/tests/test_cpython_effects_rack.py
@@ -1240,6 +1240,25 @@ def _native_binaries():
         found[family] = path if path and os.path.isfile(path) else None
     return found, root
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("Rack", rebuilt.ADOPTED)
+        self.assertNotIn("Rack", rebuilt.parked())
+        self.assertIs(audioeffects.Rack, Rack)
+        served = audioeffects.create(
+            "Rack",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, Rack)
+        served.deinit()
+
+
 class TestEmptyRack(TestCase):
     """T1. With nothing in it, a rack is a patch cable."""
 
diff --git a/tests/test_cpython_effects_racks.py b/tests/test_cpython_effects_racks.py
index b711b96..88baad8 100644
--- a/tests/test_cpython_effects_racks.py
+++ b/tests/test_cpython_effects_racks.py
@@ -13,7 +13,6 @@
 import sys
 import unittest
 
-import audioeffects
 from tools.validate_metadata import validate_component
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "support"))
@@ -25,12 +24,18 @@
 # how `ShimmerHall` and `AirSpace` keep it; these tests do the same.
 from audioeffects import reverb  # noqa: E402
 
+# `rack.Rack`, `rack.ShimmerHall` and `rack.AirSpace` are the old classes,
+# which `audioeffects.Rack` and the other two served until the Phase 6
+# rebuilds' adoption on 2026-10-13. These tests are about the old kind, so
+# they name it from its module.
+from audioeffects import rack as rack_module  # noqa: E402
+
 
 class RackTest(unittest.TestCase):
     """The rack kind: one component whose graph is several effects.
 
     Ported from micropython-vst3's soundtrack racks; the mechanism is
-    `audioeffects.Rack` and the two shared presets are `ShimmerHall` and
+    `rack.Rack` and the two shared presets are `ShimmerHall` and
     `AirSpace`. A rack has exactly the effect shape, so everything the
     catalogue-wide tests assert already covers these three classes - what
     is here is the rack-specific behavior.
@@ -40,8 +45,8 @@ class RackTest(unittest.TestCase):
              (reverb.Reverb, {"preset": "plate", "mix": 0.25}))
 
     def test_a_chain_spec_builds_children_in_order_and_renders(self):
-        rack = audioeffects.create("Rack", source(), SAMPLE_RATE,
-                                   chain=self.CHAIN)
+        rack = rack_module.Rack.create(source(), SAMPLE_RATE,
+                                       chain=self.CHAIN)
         self.assertEqual([type(child).__name__ for child in rack.effects],
                          ["Overdrive", "Reverb"])
         # Each child is fed the previous one's output, and the rack's
@@ -51,13 +56,13 @@ def test_a_chain_spec_builds_children_in_order_and_renders(self):
         self.assertGreater(peak(rack.output, 8), 0.001)
 
     def test_a_bare_name_is_a_valid_chain_entry(self):
-        rack = audioeffects.Rack(source(), chain=("Saturation", "Reverb"))
+        rack = rack_module.Rack(source(), chain=("Saturation", "Reverb"))
         self.assertEqual(len(rack.effects), 2)
         self.assertGreater(peak(rack.output, 8), 0.001)
 
     def test_an_empty_rack_is_a_wire(self):
         src = source()
-        rack = audioeffects.create("Rack", src, SAMPLE_RATE)
+        rack = rack_module.Rack.create(src, SAMPLE_RATE)
         self.assertIs(rack.output, src)
         self.assertEqual(rack.latency_samples, 0)
         self.assertEqual(rack.tail_samples, 0)
@@ -65,20 +70,20 @@ def test_an_empty_rack_is_a_wire(self):
 
     def test_a_malformed_chain_entry_is_refused(self):
         with self.assertRaises(ValueError):
-            audioeffects.Rack(source(), chain=(42,))
+            rack_module.Rack(source(), chain=(42,))
         with self.assertRaises(ImportError):
-            audioeffects.Rack(source(), chain=("NoSuchEffect",))
+            rack_module.Rack(source(), chain=("NoSuchEffect",))
 
     def test_racks_nest(self):
         # "Racks may contain and be used by other racks" - both directions.
-        inner = ("Rack", {"chain": (("Saturation", {"drive_db": 6.0}),)})
-        outer = audioeffects.Rack(source(), chain=(
+        inner = (rack_module.Rack, {"chain": (("Saturation", {"drive_db": 6.0}),)})
+        outer = rack_module.Rack(source(), chain=(
             inner, (reverb.Reverb, {"preset": "room", "mix": 0.2})))
         self.assertEqual(type(outer.effects[0]).__name__, "Rack")
         self.assertGreater(peak(outer.output, 8), 0.001)
 
     def test_latency_and_tail_are_the_whole_graph(self):
-        rack = audioeffects.Rack(source(), chain=self.CHAIN)
+        rack = rack_module.Rack(source(), chain=self.CHAIN)
         self.assertEqual(rack.latency_samples,
                          sum(child.latency_samples
                              for child in rack.effects))
@@ -89,7 +94,7 @@ def test_latency_and_tail_are_the_whole_graph(self):
 
     def test_deinit_releases_the_children_but_not_the_source(self):
         src = source()
-        rack = audioeffects.Rack(src, chain=self.CHAIN)
+        rack = rack_module.Rack(src, chain=self.CHAIN)
         children = list(rack.effects)
         rack.deinit()
         rack.deinit()
@@ -102,15 +107,14 @@ def test_deinit_releases_the_children_but_not_the_source(self):
         self.assertGreater(peak(src, 2), 0.001)
 
     def test_rack_metadata_is_valid_component_metadata(self):
-        from audioeffects import rack as module
-        for cls in (audioeffects.Rack, audioeffects.ShimmerHall,
-                    audioeffects.AirSpace):
+        for cls in (rack_module.Rack, rack_module.ShimmerHall,
+                    rack_module.AirSpace):
             validate_component(cls, kind="effect",
                                expected_name=cls.__name__,
-                               vendor_owner=module)
+                               vendor_owner=rack_module)
 
     def test_a_preset_rack_macro_moves_its_child(self):
-        rack = audioeffects.ShimmerHall(source())
+        rack = rack_module.ShimmerHall(source())
         self.assertEqual(rack.patch_index, 0)
         rack.set_macro(0, 0)
         self.assertEqual(rack.octave.mixer.voice[1].level, 0.0)
@@ -124,7 +128,7 @@ def test_a_preset_rack_macro_moves_its_child(self):
 
     def test_the_preset_racks_chain_audio_through_their_children(self):
         for name in ("ShimmerHall", "AirSpace"):
-            rack = getattr(audioeffects, name)(source())
+            rack = getattr(rack_module, name)(source())
             self.assertGreaterEqual(len(rack.effects), 3)
             self.assertGreater(peak(rack.output, 8), 0.001, name)
 
diff --git a/tests/test_cpython_effects_shimmerhall.py b/tests/test_cpython_effects_shimmerhall.py
index d244855..af3650d 100644
--- a/tests/test_cpython_effects_shimmerhall.py
+++ b/tests/test_cpython_effects_shimmerhall.py
@@ -786,6 +786,25 @@ def _port(rate=48000, channels=2):
     return kc.feed(array("h", bytes(4 * channels)), rate, channels).port
 
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("ShimmerHall", rebuilt.ADOPTED)
+        self.assertNotIn("ShimmerHall", rebuilt.parked())
+        self.assertIs(audioeffects.ShimmerHall, ShimmerHall)
+        served = audioeffects.create(
+            "ShimmerHall",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, ShimmerHall)
+        served.deinit()
+
+
 class TheSurface(TestCase):
     def test_macros_patches_tier_latency(self):
         self.assertEqual(ShimmerHall.MACRO_LABELS,
diff --git a/tests/test_cpython_effects_stereowidener.py b/tests/test_cpython_effects_stereowidener.py
index bb0d56c..cf1ffe7 100644
--- a/tests/test_cpython_effects_stereowidener.py
+++ b/tests/test_cpython_effects_stereowidener.py
@@ -513,6 +513,25 @@ def _same_after(a, b):
     return sum(1 for i in range(len(a)) if a[i] != b[i])
 
 
+class TheAdoption(TestCase):
+    def test_adopted_is_what_the_package_serves(self):
+        """Adopted on 2026-10-13, so `create()` serves this one. Revert
+        `rebuilt.ADOPTED` and this goes red."""
+        import audiocore
+        import audioeffects
+        from array import array
+        self.assertIn("StereoWidener", rebuilt.ADOPTED)
+        self.assertNotIn("StereoWidener", rebuilt.parked())
+        self.assertIs(audioeffects.StereoWidener, StereoWidener)
+        served = audioeffects.create(
+            "StereoWidener",
+            audiocore.RawSample(array("h", [0, 0] * 64), sample_rate=48000,
+                                channel_count=2),
+            48000)
+        self.assertIsInstance(served, StereoWidener)
+        served.deinit()
+
+
 class TheSurface(TestCase):
     def test_macros_patches_tier_latency(self):
         self.assertEqual(StereoWidener.MACRO_LABELS,
diff --git a/tests/test_rebuilt_registry.py b/tests/test_rebuilt_registry.py
index 77d5920..2d50394 100644
--- a/tests/test_rebuilt_registry.py
+++ b/tests/test_rebuilt_registry.py
@@ -866,10 +866,12 @@ def test_phase2_names_have_left_adopted(self):
         # `DigitalDelay` and `SlapbackDelay`, were adopted on 2026-09-28 on
         # rulings of that day, and are served from here until they come home.
         # Phase 5's last six followed on 2026-09-29, on the board session
-        # at audiodsp v0.6.3.
+        # at audiodsp v0.6.3. Phase 6's seven were adopted on 2026-10-13.
         self.assertEqual(rebuilt.ADOPTED, (
             "DigitalDelay", "SlapbackDelay", "TapeDelay", "AnalogDelay",
-            "PingPongDelay", "MultiTapDelay", "Reverb", "ConvolutionReverb"))
+            "PingPongDelay", "MultiTapDelay", "Reverb", "ConvolutionReverb",
+            "StereoWidener", "Rack", "Octaver", "PitchShifter",
+            "Harmonizer", "AirSpace", "ShimmerHall"))
         self.assertEqual(rebuilt.adopted(), rebuilt.ADOPTED)
         for name in rebuilt.ADOPTED:
             self.assertIs(rebuilt.load(name), rebuilt.module_class(name))

From d529f3bb80742ee679efeb9cac1cbd64c33625c0 Mon Sep 17 00:00:00 2001
From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com>
Date: Tue, 13 Oct 2026 14:28:51 -0500
Subject: [PATCH 76/76] Lifecycle: ShimmerHall's rows for the Rise defaults

At the Rise defaults the hall sounds at once, so a Size or Mix jump early in
the render lands on sound and steps the output: the disclosed family limit
(a control that jumps makes the output step; moving Size empties the hall).
On CircuitPython, Octave Bloom loaded before the first pull now re-arms
Bloom's shifter from the defaults, and CircuitPython's own PitchShift keeps
its positions through a clear, as for the other Bloom patches.
---
 tests/support/lifecycle.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tests/support/lifecycle.py b/tests/support/lifecycle.py
index 80b339d..5390a2e 100644
--- a/tests/support/lifecycle.py
+++ b/tests/support/lifecycle.py
@@ -361,6 +361,8 @@
     ("ShimmerHall", "E11-", "P4"): "moves that reach the hall, empty it, or move the shifter's interval or splice leave them off the control's for good (Reverb's E11 P4; N2)",
     ("ShimmerHall", "E4-m0=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Character)",
     ("ShimmerHall", "E4-m3=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Bloom)",
+    ("ShimmerHall", "E4-m6=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Size, which also empties the hall, as the docstring says); at the Rise defaults the hall sounds at once, so the jump lands on sound",
+    ("ShimmerHall", "E4-m8=", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix); at the Rise defaults the hall sounds at once, so the jump lands on sound",
     ("ShimmerHall", "E5-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
     ("ShimmerHall", "E6-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (a patch change)",
     ("ShimmerHall", "E9-", "P5"): "family limit, disclosed (N1): a control that jumps makes the output step (Mix)",
@@ -371,6 +373,7 @@
     ("ShimmerHall", "E10-patch", "P4", "circuitpython"): _SHIMMER_CP,
     ("ShimmerHall", "E12-p1", "P4", "circuitpython"): _SHIMMER_CP,
     ("ShimmerHall", "E12-p2", "P4", "circuitpython"): _SHIMMER_CP,
+    ("ShimmerHall", "E12-p6", "P4", "circuitpython"): _SHIMMER_CP,
     ("ShimmerHall", "E12-mix64", "P4", "circuitpython"): _SHIMMER_CP,
     ("ShimmerHall", "E12-mix127", "P4", "circuitpython"): _SHIMMER_CP,
 }