Move the shared code out, and the bots with it

.gitignore

@@ -76,6 +76,24 @@ Testing/
 .claude/
 .gemini/
 
+# Operating-system detritus.
+#
+# .DS_Store is Finder's per-folder metadata -- icon positions, window size,
+# view mode -- written into any directory macOS opens. It is machine-local by
+# definition and means nothing on anybody else's disk. One reached the tree in
+# 3a1193b; the rest of these are its siblings, listed now rather than after
+# each one has had its own turn.
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
 # Editor and Python detritus
 *~
 .vimsupport/

.gitmodules

@@ -18,3 +18,15 @@
 [submodule "modules/vorbis"]
 	path = modules/vorbis
 	url = https://github.com/xiph/vorbis.git
+[submodule "libs/music"]
+	path = libs/music
+	url = https://github.com/chalkwalk/chalkwalk-music.git
+[submodule "libs/dsp"]
+	path = libs/dsp
+	url = https://github.com/chalkwalk/chalkwalk-dsp.git
+[submodule "libs/ninjam"]
+	path = libs/ninjam
+	url = https://github.com/chalkwalk/chalkwalk-ninjam.git
+[submodule "libs/jambot"]
+	path = libs/jambot
+	url = https://github.com/chalkwalk/chalkwalk-jambot.git

AGENTS.md

@@ -28,6 +28,10 @@ Authoritative docs (read these before designing anything new):
 - **`docs/PARITY.md`** -- what has been verified against the reference client,
   with the measured numbers.
 - **`docs/ACCESSIBILITY.md`** -- the accessibility story, honestly.
+- **`libs/jambot/docs/BOT-CHAT.md`** -- what the practice room's bots would say
+  and what they would never say. It lives with the bots now; this repository
+  hosts them and does not design them.
+
 - **`test/README.md`** -- how to run every test layer.
 
 Ordering for any new work: **PRINCIPLES -> DESIGN -> ROADMAP**. If a proposal
@@ -58,7 +62,33 @@ changes. As of 2026-08-10:
 ## Layout map
 
 ```
-CMakeLists.txt              # root: JUCE patching, submodules, src/, test/
+CMakeLists.txt              # root: JUCE patching, submodules, libs/, src/, test/
+libs/music/                 # SUBMODULE: chalkwalk-music (MIT, JUCE-free).
+                            #   github.com/chalkwalk/chalkwalk-music. Euclidean
+                            #   lives there now, not in src/. Builds and tests
+                            #   standalone; its Catch2 suite runs in our ctest.
+libs/dsp/                   # SUBMODULE: chalkwalk-dsp (MIT, JUCE-free). Two
+                            #   targets: `chalkwalk::dsp` is header-only
+                            #   primitives (Svf, PolyBlep, SoftClip, Hermite,
+                            #   Denormal) and the plugin links it;
+                            #   `chalkwalk::dsp::measure` is the instruments --
+                            #   what `AudioMeasure` used to be -- and carries
+                            #   libebur128, so only test and tool targets link
+                            #   it.
+libs/jambot/                # SUBMODULE: chalkwalk-jambot (MIT, JUCE-free). The
+                            #   BAND, and the chat they answer. Was src/jambot/
+                            #   until it earned its own repository; what stays
+                            #   here is the hosting a practice room needs and a
+                            #   command-line bot does not. Its suite runs in our
+                            #   ctest, so we verify the bots rather than assume
+                            #   them. Corpora and BotDictionary.h live there
+                            #   now, and so do scripts/make_wordlist.py and
+                            #   lexicon_gaps.py.
+libs/ninjam/                # SUBMODULE: chalkwalk-ninjam (MIT, JUCE-free). The
+                            #   wire protocol, and the room conventions in
+                            #   RoomConventions.h. Vendors its own ogg/vorbis,
+                            #   guarded, so whichever project adds them first
+                            #   wins.
 patches/*.patch             # applied to the JUCE submodule at configure time
 assets/fonts/               # Inter (OFL-1.1), embedded as binary data
 src/
@@ -78,12 +108,31 @@ src/
   Shortcuts.h               # Ctrl+Alt shortcut mapping; matches key code, not text
   AudioDeviceStartup.h      # 4-state standalone device-open policy, with a budget
   ChannelMix.h              # mono/pan/gain: one home for three rules that drifted
-  MusicalKey.h              # key and mode: parse, display, scale notes
+  MusicalKey.h              # three inline functions composing the envelope
+                            #   (chalkwalk::ninjam::conventions) with the key
+                            #   (chalkwalk::music::Notation), under the name
+                            #   every call site here already uses
+  Harmony.h                 # one line: an alias to chalkwalk::music::Harmony
   ClipsortLog.{h,cpp}       # session archive manifest: read and write
   StemRender.h              # one clip into one interval, resampled and aligned
   GainUtils.h               # dB<->linear, fader and meter scales, formatting
   IntervalProbe.h           # shared test signal: plugin Test Tone and the tests
+  AudioMeasure.h            # one line: an alias to chalkwalk::dsp::measure.
+                            #   The instruments moved -- `peak` and `rms` had
+                            #   three copies across the ecosystem and
+                            #   `fundamentalHz` two, and an uncalibrated
+                            #   detector is how measurement error passes for a
+                            #   bug. libebur128 went with them.
   ChatFormat.{h,cpp}        # chat rendering: vote lines, chord progressions
+  RoomHarmony.h             # WHICH of the two a chat line is, and nothing else.
+                            #   What each MEANS is Harmony::Session in
+                            #   chalkwalk-music; how a key travels is
+                            #   chalkwalk::ninjam::conventions
+  # --- the practice room's HOSTING, which stays here ---
+  PracticeRoom.{h,cpp}      # the room: seeds, band settings, the bots in it
+  PracticeServer.{h,cpp}    # a Ninjam server on loopback, so a room needs none
+  NinjamBotClient.h         # that interface over Antiphon's client. The whole of
+                            #   what ties the band to this plugin's transport
   # --- UI ---
   LocalChannelStrip.{h,cpp} # 90px vertical strip per local input channel
   RemoteUserStrip.{h,cpp}   # card per remote player, channels arranged horizontally
@@ -106,9 +155,13 @@ test/
   fixtures/testserver.cfg   # config for the local ninjamsrv
 tools/
   StemsMain.cpp             # antiphon-stems: session archive -> WAV stems
+  PracticeRoomMain.cpp      # antiphon-practice: hosts a practice room; join it
+                            #   with the standalone. The only way to meet the
+                            #   band today -- nothing in src/ starts a room.
 scripts/
   testserver.sh             # fetches, builds and runs a local ninjamsrv out of tree
   analyze_archive.py        # measures a server session archive
+  trim_soundfont.py         # cuts an SF2/SF3 down to the presets we would use
 docs/references/            # what was read to write this, and at which revision
 modules/                    # ogg, vorbis, clap-juce-extensions submodules
 ```
@@ -119,6 +172,21 @@ The single source of truth for how this repo is built and tested.
 
 First-time clone: `git submodule update --init --recursive`
 
+**Testing a change to a shared library without pushing it.** Point at a working
+checkout instead of the submodule; the library's own suite and Antiphon's both
+run against it:
+
+```bash
+cmake -B build -DCHALKWALK_MUSIC_DIR=$HOME/Programming/chalkwalk-music
+```
+
+`CHALKWALK_DSP_DIR`, `CHALKWALK_NINJAM_DIR` and `CHALKWALK_JAMBOT_DIR` likewise, as cache variables or
+environment variables. Configure prints `OVERRIDE` when one is in use, because
+**the submodule SHA no longer describes what you built** -- so CI must not use
+them, and neither should anything meant to be attributable, `docs/PARITY.md`
+above all. Iterate with an override; bump the submodule and re-verify before
+calling anything done. Same shape as Anvil's `CHALKWALK_PHYSICAL_DIR`.
+
 ```bash
 # Configure (once, or after CMakeLists changes). No generator flag -- use
 # whatever CMake picks.
@@ -133,8 +201,23 @@ ctest --test-dir build --output-on-failure
 # count, and the report goes to stdout. Runs headless, no display needed --
 # but NOT in CI, where it is excluded on every platform. See ROADMAP.md.
 ./build/test/AntiphonAudit_artefacts/AntiphonAudit
+# Host a practice room and join it with the standalone on the port it prints.
+# The band is not reachable from the plugin yet; this is how you hear it.
+./build/tools/AntiphonPractice_artefacts/AntiphonPractice --key "D minor"
 # Offline: turn a session archive into WAV stems.
 ./build/tools/AntiphonStems_artefacts/AntiphonStems <session-dir> -o stems/
+# Tuning the band's synthesis: render one voice and measure it. The numbers it
+# prints come from chalkwalk::dsp::measure, which is what the unit tests assert
+# against, so tuning by ear and setting a threshold use one instrument.
+./build/tools/AntiphonVoiceLab_artefacts/AntiphonVoiceLab kick --seconds 0.6
+./build/tools/AntiphonVoiceLab_artefacts/AntiphonVoiceLab band --seed 12345
+# Comparing two renders for timbre rather than for level: --lufs normalises to
+# an integrated loudness. It warns when a target would clip a sparse voice.
+./build/tools/AntiphonVoiceLab_artefacts/AntiphonVoiceLab hat --lufs -27
+# Comparing renders from builds you can no longer reproduce: measure the WAVs,
+# and write copies matched to one loudness so the A/B is about the sound.
+./build/tools/AntiphonVoiceLab_artefacts/AntiphonVoiceLab file a.wav b.wav
+./build/tools/AntiphonVoiceLab_artefacts/AntiphonVoiceLab file a.wav --lufs -20 -o a-matched.wav
 ```
 
 Targets: `Antiphon_Standalone` (easiest for iteration), `Antiphon_VST3`. CLAP is
@@ -147,9 +230,9 @@ is the only thing that compiles it.
 AU's identity in the plugin registry. JUCE's defaults are the placeholder
 `'Manu'` and a `string(RANDOM)` plugin code regenerated on every configure, so
 dropping them would mint a new Audio Unit per build tree and break every saved
-Logic session. `Chlk` is shared with arps-euclidya, which uses plugin code
-`ArpE`; a new Chalkwalk plugin needs its own plugin code, not its own
-manufacturer code.
+Logic session. `Chlk` is the shared Chalkwalk manufacturer code; a plugin needs its own
+plugin code, not its own manufacturer code. Allocated codes are tracked in the
+ecosystem plan.
 
 Sanitiser builds -- keep them around, they are worth more than gdb here:
 
@@ -245,6 +328,7 @@ reading past a buffer. Assume your change has the same failure mode.
 | Mixing, routing, playback delay | `test/AudioLoopbackTests.cpp` | Drives the real path end to end. |
 | Accessibility naming rules | `test/AccessibilityAuditTests.cpp` | Synthetic node tree; the real UI cannot be compiled into the test target. |
 | A new control, or a new UI state | `test/AuditMain.cpp` | The `AntiphonAudit` target links the plugin's own library and audits the **real** editor across five states. Add a state when you add a surface -- an unaudited state is how the connect dialog stayed unchecked for its whole life. |
+| What a bot understands or says | **`chalkwalk-jambot`, not here** | The bots left. Corpora, suites and the generator scripts went with them; iterate there with `-DCHALKWALK_JAMBOT_DIR=...` and bump the submodule when done. |
 | Server-visible behaviour | `test/RealServerTests.cpp` | Opt-in via `NINJAM_TEST_SERVER`; keep the default suite hermetic. |
 
 ### Rules that are easy to get wrong
@@ -257,7 +341,8 @@ reading past a buffer. Assume your change has the same failure mode.
   (`test/TestSignal.h`). Vorbis is lossy and has codec delay; sample-by-sample
   comparison against the input will never hold.
 - **A new `src/*.cpp` must be added to BOTH `src/CMakeLists.txt` and
-  `test/CMakeLists.txt`.** The test target deliberately re-lists production
+  `test/CMakeLists.txt`** -- and to `tools/CMakeLists.txt` if a tool uses it,
+  which is a third list and the one most often forgotten.** The test target deliberately re-lists production
   sources rather than sharing them -- `juce_generate_juce_header` only works on
   `juce_add_*` targets, and each target needs its own `JuceHeader.h`. See the
   comment at the top of `test/CMakeLists.txt`.

CMakeLists.txt

@@ -7,6 +7,22 @@ project(Antiphon VERSION 0.1.0)
 # enable_testing() must be called at the top level for ctest to work
 enable_testing()
 
+# C++20 -- applies to every target in the tree, including the format-specific
+# plugin wrappers (Antiphon_Standalone / _VST3 / _CLAP) that juce_add_plugin
+# creates. A per-target PUBLIC cxx_std_20 does NOT reach those wrappers,
+# because JUCE compiles their sources independently with its own cxx_std_17
+# floor (see JUCEUtils.cmake).
+#
+# It is a single standard across the build rather than a preference: JUCE has
+# inlines gated on __cpp_char8_t, so a tree that compiles some translation
+# units at 17 and some at 20 is an ODR hazard, not merely an inconsistent one.
+# Same reasoning and same lines as Anvil and the sequencer.
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS ON)
+
+include(cmake/JuceSource.cmake)
+
 # Submodule patches, applied at configure time.
 #
 # Each entry is "<submodule dir>|<patch file>". Each patch is idempotent:
@@ -28,7 +44,13 @@ if(GIT_FOUND)
         list(GET patch_parts 0 patch_submodule)
         list(GET patch_parts 1 patch_relative)
         set(patch_file "${CMAKE_CURRENT_SOURCE_DIR}/${patch_relative}")
-        set(patch_dir "${CMAKE_CURRENT_SOURCE_DIR}/${patch_submodule}")
+        # JUCE may be this repository's submodule or the shared checkout that
+        # CHALKWALK_JUCE_DIR names; everything else is always local.
+        if(patch_submodule STREQUAL "JUCE")
+            set(patch_dir "${CHALKWALK_JUCE_ROOT}")
+        else()
+            set(patch_dir "${CMAKE_CURRENT_SOURCE_DIR}/${patch_submodule}")
+        endif()
 
         if(NOT EXISTS "${patch_file}")
             continue()
@@ -58,8 +80,7 @@ if(GIT_FOUND)
     endforeach()
 endif()
 
-# Configure JUCE
-add_subdirectory(JUCE)
+add_subdirectory("${CHALKWALK_JUCE_ROOT}" "${CMAKE_BINARY_DIR}/juce-build")
 
 # Configure CLAP JUCE extension
 add_subdirectory(modules/clap-juce-extensions EXCLUDE_FROM_ALL)
@@ -70,7 +91,71 @@ set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
 add_subdirectory(modules/ogg EXCLUDE_FROM_ALL)
 add_subdirectory(modules/vorbis EXCLUDE_FROM_ALL)
 
-# Add the sources subdirectory
+# ---------------------------------------------------------------------------
+# chalkwalk-music -- shared, JUCE-free music theory.
+# Submodule: https://github.com/chalkwalk/chalkwalk-music (MIT).
+#
+# It builds and tests standalone, with no JUCE and no parent, which is the test
+# of the boundary. Its own Catch2 suite is turned on here so this project
+# verifies its dependency rather than assuming it.
+# ---------------------------------------------------------------------------
+include(cmake/ChalkwalkLibrary.cmake)
+chalkwalk_add_library(music libs/music)
+
+# ---------------------------------------------------------------------------
+# chalkwalk-dsp -- shared, JUCE-free DSP primitives.
+# Submodule: https://github.com/chalkwalk/chalkwalk-dsp (MIT).
+#
+# Same arrangement and the same reasoning as chalkwalk-music above. The filter,
+# the polyBLEP oscillators, the soft clipper and the Hermite reader lived here
+# and in a sibling project, and the two copies had diverged; the shared
+# versions take both halves.
+#
+# It also owns MEASUREMENT now -- `chalkwalk::dsp::measure`, what `AudioMeasure`
+# used to be -- and with it the libebur128 dependency that used to be vendored
+# in this repository. That is a second target rather than part of the first, so
+# the plugin links the primitives without linking a loudness meter; only the
+# test and tool targets ask for `measure`. The move was for the usual reason:
+# `peak` and `rms` existed three times over across these repositories and
+# `fundamentalHz` twice, and a detector nobody has calibrated is how a
+# measurement error gets mistaken for a bug (`PRINCIPLES §5`).
+# ---------------------------------------------------------------------------
+chalkwalk_add_library(dsp libs/dsp)
+
+# ---------------------------------------------------------------------------
+# chalkwalk-ninjam -- the NINJAM wire protocol, JUCE-free.
+# Submodule: https://github.com/chalkwalk/chalkwalk-ninjam (MIT).
+#
+# Added after modules/ogg and modules/vorbis above, and not by accident: this
+# library vendors its own copies of both, guarded by `if(NOT TARGET ogg)`, so
+# whichever project adds them first wins and the second reuses them. Adding
+# them twice is not a version conflict -- it is a duplicate CMake target name,
+# which fails the configure outright.
+#
+# The protocol left this repository under MIT while antiphon stays GPLv3. The
+# provenance note in its README is the record of why that is defensible: the
+# GPLv2 reference sources were read, never vendored, and never entered any
+# published history. See PRINCIPLES.md section 6.
+# ---------------------------------------------------------------------------
+chalkwalk_add_library(ninjam libs/ninjam)
+
+# ---------------------------------------------------------------------------
+# chalkwalk-jambot -- the practice room's band, and the chat they answer.
+# Submodule: https://github.com/chalkwalk/chalkwalk-jambot (MIT).
+#
+# These were `src/jambot/` here until they earned their own repository. What
+# stays is the HOSTING a practice room needs and a command-line bot does not:
+# the loopback server, the room that puts a server and a band together, and
+# `NinjamBotClient`, which is the whole of what ties the band to this plugin's
+# transport.
+#
+# The direction of the dependency is the point. Antiphon uses the bots; the
+# bots know nothing about Antiphon, and their suite runs without it -- which is
+# what the `jambot-boundary` check was guarding towards and why that check is
+# gone. A boundary a build enforces does not need a test to describe it.
+# ---------------------------------------------------------------------------
+chalkwalk_add_library(jambot libs/jambot)
+
 add_subdirectory(src)
 
 # Offline tools. Kept out of src/ because nothing here is part of the plugin --