The oracle moves to a path no build script writes, and is re-pinned at 977ef26 (#89)

`cmods/bin/circuitpython` was two things at once: the oracle every parity
golden here is measured against, and what `cmods/build_interpreters.sh`'s
`cp-unix` target installs. So refreshing the workspace interpreters replaced
the oracle with the coverage variant's own 14-voice build, twice in eight days,
and the only thing that noticed either time was this hash pin.

The oracle is `cmods/bin/circuitpython-oracle-10.3.0` now, beside the 10.2.1
one it succeeds, and the opt-in `cp-oracle` target added in cmods d4b08aa is
the only thing that writes it. `bin/circuitpython` stays the installer's, at
14 voices, which is what the effects program's briefs pass as their
CircuitPython leg and what the rest of the workspace runs.

The bytes moved as well as the path, and they were due to: PR #86 gave
`src/shared/` its fp-contract header, and `apply_cp_patches.sh` relinks those
nine kernels into the CP tree, so our own arithmetic moved under CircuitPython's
untouched sources. (PR #93's SpeedChanger fix is ours alone; the CP tree keeps
upstream's, which is why `speedchanger_hold_probe.py` skips CircuitPython.)

Built from CircuitPython 10.3.0 with
`-UCIRCUITPY_SYNTHIO_MAX_CHANNELS -DCIRCUITPY_SYNTHIO_MAX_CHANNELS=64`,
audioif at 977ef26. Verified the way this header says a re-pin is verified:
it answers 64 voices; CircuitPython's own modules are byte-identical across
the rebuild, with `synthtools_acceptance` (8 lines) and `mixdown_knee`'s
stored `circuitpython_stdout` (10 lines) both reproducing exactly; and
`verify_dsp` agrees three ways across 45 comparisons, 0 failures, 0 pending,
with no skip beyond the three already written down. The pin still catches a
swap: aimed at `bin/circuitpython` it goes red on the spot.

Two stale records fixed while here. `mixdown_knee.json`'s
`circuitpython_binary_sha256` now names the file that produced its lines --
the capture itself is untouched, which the re-record proves by changing that
one field and nothing else -- and its `circuitpython_stdout_note` still said
"10.2.1 at N=14" although 4ec5718 re-captured it at 10.3.0 and N=64 on
2026-09-09.

Author: bdbarnett

AGENTS.md

@@ -74,7 +74,7 @@ Both are expected as siblings in the parent workspace (`cmods/` in
   `.venv/bin/python tests/parity/verify_dsp.py --micropython ../cmods/micropython/ports/unix/build-standard/micropython`
   is the first. There is **no stored digest** — the gate is the comparison, and
   it **refuses a run with fewer than two interpreters** rather than passing one
-  that cannot fail. Add `--circuitpython ../cmods/bin/circuitpython-effects-10.3.0`
+  that cannot fail. Add `--circuitpython ../cmods/bin/circuitpython-oracle-10.3.0`
   for the three-way. The arithmetic is all in `src/shared/`, so two
   interpreters disagreeing is never a difference of intent: it is a width, an
   undefined shift, a compiler's choice or an architecture.
@@ -173,6 +173,14 @@ Both are expected as siblings in the parent workspace (`cmods/` in
 **oracle** every parity golden is measured against. The rule, for any agent
 working here:
 
+- **The oracle binary is `cmods/bin/circuitpython-oracle-<version>`**, built
+  only by `cmods/build_interpreters.sh --only cp-oracle` (CircuitPython's unix
+  coverage variant at `CIRCUITPY_SYNTHIO_MAX_CHANNELS=64`) and re-pinned in
+  `tests/test_voice_ceiling_consistency.py` in the same change that builds it.
+  **`cmods/bin/circuitpython` is not the oracle** — it is what that script's
+  `cp-unix` target installs, at the coverage variant's own 14-voice ceiling,
+  and it changes under you whenever anyone refreshes the interpreters
+  (audioif#89, twice in eight days).
 - **Never edit files in `cmods/circuitpython` directly.** A modified oracle
   silently redefines what "parity" means and invalidates every golden without
   failing anything. Its *pin* is a different matter: it moves when this port

docs/correctness-standard.md

@@ -127,7 +127,12 @@ is the checklist, not a report.
   for the ceiling override, which must be `-U` then `-D` because `-Werror` makes
   a conflicting redefinition an error. `tests/test_voice_ceiling_consistency.py`
   still compares the binary's bytes against a pin — that check is about noticing
-  an *undeclared* rebuild and is not retired.
+  an *undeclared* rebuild and is not retired. The oracle moved to
+  `cmods/bin/circuitpython-oracle-10.3.0` on 2026-09-17 (audioif#89): the old
+  path is what `build_interpreters.sh`'s `cp-unix` target installs, so a
+  routine interpreter refresh replaced the oracle with a 14-voice build twice.
+  The opt-in `cp-oracle` target builds and installs the oracle now, and
+  nothing else writes that path.
 
   The rebuild earned itself immediately: it found two behaviour changes
   CircuitPython 10.3.0 made to `synthio` and `audiomixer` that this port had not

tests/parity/golden/mixdown_knee.json

@@ -1,6 +1,6 @@
 {
- "circuitpython_binary_sha256": "447e3ee88a143e1db1605590a395e7b8f7335cf5d7f5fa3e768e10ecf44c047e",
- "circuitpython_binary_sha256_note": "The sha256 of cmods/bin/circuitpython AS IT WAS ON DISK when this capture was taken (2026-09-09), and the build pinned in tests/test_voice_ceiling_consistency.py -- the two now agree, which they did not before. This is CircuitPython 10.3.0 built at CIRCUITPY_SYNTHIO_MAX_CHANNELS=64: the same version and the same ceiling this port ships, which is the only configuration that can answer whether we render CircuitPython's bytes in the same situation. The previous capture was 10.2.1 at 14 (b3063621c72a085b, kept at cmods/bin/circuitpython-oracle-10.2.1); at that ceiling no material could be both above the knee and oracle-identical, and the above-knee half of this gate was advisory. It is not any more -- ours and the oracle are now byte-identical on every line of this probe, above the knee and below. See docs/correctness-standard.md.",
+ "circuitpython_binary_sha256": "d6635dec6bf6c210b5934c779dd812974f5ac2083f3a46d4ba1f93435ff4fa92",
+ "circuitpython_binary_sha256_note": "The sha256 of the pinned oracle binary AS IT WAS ON DISK when this capture was last recorded: cmods/bin/circuitpython-oracle-10.3.0, 2026-09-17. The oracle moved off cmods/bin/circuitpython that day because that path is what cmods/build_interpreters.sh's cp-unix target installs, at the coverage variant's own 14-voice ceiling, and it overwrote the oracle twice (audioif#89); the lines below are unchanged from 2026-09-09 and reproduce on the new binary byte for byte. This is the build pinned in tests/test_voice_ceiling_consistency.py -- the two agree. It is CircuitPython 10.3.0 built at CIRCUITPY_SYNTHIO_MAX_CHANNELS=64: the same version and the same ceiling this port ships, which is the only configuration that can answer whether we render CircuitPython's bytes in the same situation. The previous capture was 10.2.1 at 14 (b3063621c72a085b, kept at cmods/bin/circuitpython-oracle-10.2.1); at that ceiling no material could be both above the knee and oracle-identical, and the above-knee half of this gate was advisory. It is not any more -- ours and the oracle are byte-identical on every line of this probe, above the knee and below. See docs/correctness-standard.md.",
  "circuitpython_stdout": [
   "below_knee 1 0 512 52264 556885117 16382",
   "below_knee 1 1 512 63440 3941643029 16382",
@@ -13,7 +13,7 @@
   "above_knee 10 0 512 52758 1118287133 28268",
   "above_knee 10 1 512 66496 3802209405 28268"
  ],
- "circuitpython_stdout_note": "The pinned CircuitPython 10.2.1 oracle's own answer at N=14, captured 2026-09-06 with --capture-reference. ADVISORY except for the below_knee lines, which the gate does enforce -- below the knee the port and the oracle are byte-identical (measured on all three runtimes), so that check cannot fail while `stdout` matches. Its one real job is as an anti-launder tripwire: re-capture `stdout` under a changed ceiling and the full-stdout check goes green again while this one goes red, because the oracle field was not re-captured.",
+ "circuitpython_stdout_note": "The pinned CircuitPython 10.3.0 oracle's own answer at N=64, captured 2026-09-09 with --capture-reference (4ec5718 took 10.3.0's synthio and audiomixer behaviour; the first capture, 2026-09-06, was 10.2.1 at N=14). ADVISORY except for the below_knee lines, which the gate does enforce -- below the knee the port and the oracle are byte-identical (measured on all three runtimes), so that check cannot fail while `stdout` matches. Its one real job is as an anti-launder tripwire: re-capture `stdout` under a changed ceiling and the full-stdout check goes green again while this one goes red, because the oracle field was not re-captured.",
  "micropython_binary_sha256": "e28afe76337a1776229b966eccf4cdbe9e742f79941b4a05dea1cc0c9450c84c",
  "micropython_stdout": [
   "below_knee 1 0 512 68008 2566268345 16383",

tests/test_voice_ceiling_consistency.py

@@ -55,6 +55,35 @@
 #: gitignored binary in place. Every existing check would pass on a silently
 #: different oracle. Comparing the bytes is the only thing that notices.
 #:
+#: Re-pinned and MOVED 2026-09-17 for audioif#89. Two things changed. The
+#: **path**: `cmods/bin/circuitpython` is what `cmods/build_interpreters.sh`'s
+#: `cp-unix` target installs, so anyone refreshing the workspace interpreters
+#: silently replaced the oracle with a coverage build at the variant's own
+#: 14-voice ceiling. That happened twice in eight days, and it is the whole of
+#: #89. The oracle now lives where no build script writes it by accident: the
+#: opt-in `cp-oracle` target, added to `build_interpreters.sh` in the same
+#: change, builds at 64 and installs only to `bin/circuitpython-oracle-<ver>`.
+#: `bin/circuitpython` belongs to the installer and may change under you.
+#: The **bytes**: PR #86 gave `src/shared/` an fp-contract header, and
+#: `src/shared/` is relinked into this binary by `apply_cp_patches.sh`, so our
+#: own kernels moved under CircuitPython's untouched sources again. (PR #93's
+#: `audiospeed` fix is ours alone -- the CP tree keeps upstream's SpeedChanger,
+#: which is why `speedchanger_hold_probe.py` skips CircuitPython.) Built from
+#: CircuitPython 10.3.0 at `CIRCUITPY_SYNTHIO_MAX_CHANNELS=64` with audioif at
+#: 977ef26. Verified: it answers 64 voices; CircuitPython's own modules are
+#: byte-identical across the rebuild (`synthtools_acceptance` and
+#: `mixdown_knee`'s stored `circuitpython_stdout` both reproduce exactly); and
+#: `verify_dsp` agrees three ways across 45 comparisons, with no skip beyond
+#: the three already written down. Previous: 447e3ee88a143e1d, still on disk
+#: as `cmods/bin/circuitpython-effects-10.3.0`.
+#:
+#: A coverage build is not byte-reproducible, which is the other reason this
+#: pins a file and not a recipe. Two builds of the same tree with the same
+#: flags differ in 1476 of 27,831,104 bytes: the 20-byte GNU build-id, and one
+#: 4-byte gcov stamp per translation unit in `.data`. `.text` and every other
+#: section are identical. So rebuilding and comparing hashes cannot verify this
+#: pin -- reproducing the stored captures on the binary is what does.
+#:
 #: Re-pinned again 2026-09-09, later the same day, for audioif#64: the
 #: `audiobiquad` float biquad moved to transposed direct form II, and
 #: `audiobiquad` is one of the nine modules `apply_cp_patches.sh` adds to the CP
@@ -81,9 +110,9 @@
 #: this note as the provenance the relink never recorded. A future mismatch
 #: means what it meant then: find what rebuilt it, ask it the ceiling, and
 #: re-pin with the reason written down.
-ORACLE = ROOT.parent / "cmods" / "bin" / "circuitpython"
+ORACLE = ROOT.parent / "cmods" / "bin" / "circuitpython-oracle-10.3.0"
 ORACLE_SHA256 = (
-    "447e3ee88a143e1db1605590a395e7b8f7335cf5d7f5fa3e768e10ecf44c047e")
+    "d6635dec6bf6c210b5934c779dd812974f5ac2083f3a46d4ba1f93435ff4fa92")
 
 
 def _search(relative, pattern):
@@ -179,6 +208,11 @@ def test_oracle_binary_is_the_pinned_one(self):
             "means while leaving every tracked file untouched and every git "
             "tree clean. That is why this compares bytes and not a commit."
             "\n"
+            "\n    Nothing but `build_interpreters.sh --only cp-oracle` "
+            "should ever write this path, and that target exists so no "
+            "routine interpreter refresh can. `cmods/bin/circuitpython` is "
+            "the installer's coverage build at 14 voices and is NOT this."
+            "\n"
             "\n    If you rebuilt it deliberately, that is a decision for "
             "Brad and it needs its own commit saying why, with this hash "
             "updated in the same change." % (ORACLE_SHA256, digest))