Read the kit off the card, so a kit no longer means a rebuild

.github/workflows/ci.yml

@@ -17,17 +17,18 @@ jobs:
         # engine/ and sound/ must compile anywhere: no Arduino, Teensy, SDL or hal/ includes (D-029).
         run: |
           ! grep -rnE '#include[[:space:]]*[<"](Arduino|SDL|hal/|WProgram|core_pins|imxrt|usb_|EEPROM|SD\.h|Wire|SPI|Audio)' firmware/src/engine firmware/src/sound
-      - name: Generated kit headers match spec/kits (PRD §12 rule 6)
-        # Kits are data: the engine compiles a header generated from each kit.json.
-        # Regenerate every kit and diff, so an edit to either side cannot hide; the
-        # intent-to-add makes a header that was never committed show up too.
+      - name: Generated kit files match spec/kits (PRD §12 rule 6)
+        # Kits are data: from each kit.json the builder writes the header the engine
+        # compiles in and the kit.txt the device reads off the card (D-109). Regenerate
+        # every kit and diff both, so an edit to any side cannot hide; the intent-to-add
+        # makes a file that was never committed show up too.
         run: |
           for kit in spec/kits/*/kit.json; do
             id="$(basename "$(dirname "$kit")")"
             python3 tools/kit_builder.py "$kit" "firmware/src/engine/kits/$id.h"
           done
-          git add -N firmware/src/engine/kits
-          git diff --exit-code -- firmware/src/engine/kits
+          git add -N firmware/src/engine/kits spec/kits
+          git diff --exit-code -- firmware/src/engine/kits spec/kits
       - name: Python tools (T-76)
         # The sample generator and the kit builder's WAV checks, tested where they live.
         run: python3 -m unittest discover -s tests -p 'tools_test.py' -v

DECISIONS.md

@@ -112,3 +112,4 @@ What was decided, why, and when to look again. One row per decision. IDs are seq
 | D-106 | The share-code size cap (T-62) lives in `engine::decode` and `decode_song`, not at each path the bytes arrive on: 512 characters for a section and 2048 for a song, NUL not counted, scanning at most one past the limit so a missing terminator costs a bounded read. | 2026-09-03. The engine's decoder is linear and allocates nothing, so the cap is about refusing a code rather than about safety; putting it where the knowledge is means the card, `tools/render`, and the SysEx, USB and paste-box paths still to come are all covered without each remembering to. Twice the canonical worst case (238 and 988) rather than the buffer sizes, because T-16 says a decoder skips the fields a later version adds and a cap at the buffer would leave almost no room for them. Rejected: a cap at each arriving path (three places to forget, and nothing to write today since none of those paths exists yet). | If a later version's fields need more than the canonical code's length again. |
 | D-107 | A song slot whose file will not parse (§9.6, T-97): a tap refuses it and says `hold to replace song 2`; a hold on that pad copies the song on screen over it and says `song 2 replaced`. The hold is live only on a slot the device already knows it cannot read, so no hold can destroy a song the player could still open, and a hold anywhere else in the song view still does nothing. | 2026-09-03. D-104 made a file that will not parse a slot rather than a gap, which stopped a pick from silently copying over somebody's song but left the slot unreachable: the only thing that replaced it was the player already being on it, so recovery meant a computer or a factory reset — a dead pad on an instrument that ships with no manual. Press-then-hold is already this device's idiom for a destructive thing, in `hold dice to clear` and `hold play to reset`, and §9.6 said the pads' hold gestures were inactive in the song view, so the gesture was free and consistent rather than new; PRD §9.6 gains the exception. Rejected: a second tap inside the arming timeout (a double tap is easy by accident, and every other confirmation here is a hold); quarantining the file at boot (needs a HAL rename or delete, and silently moves a player's file aside); a settings row to clear a slot (a sub-menu for a rare failure, against §9.6's one screen). | If usability round 1 shows nobody finds the hold, or if a fourth tile state would say it better than the status line. |
 | D-108 | A kit's samples come off the card, not the firmware image: `io::load_samples` reads `kits/<kit id>/<the pad's source>` into the PSRAM `hal::sample_memory()` hands it — 1.5 MB, the eight pads of two seconds D-081 allows each — and fills a `sound::SampleBank` with what it found. Each WAV is read straight into the room left in that memory and parsed where it lands, then moved down over its own header, so nothing is ever staged twice. A file that is missing or is not 16-bit 48 kHz mono PCM costs its own pad its sound and no more. The simulator does the same thing with the same code: `host/CMakeLists.txt` seeds `out/sdcard/kits/` from `spec/kits/` at configure time. | 2026-09-03. §7.5 puts the samples in PSRAM and the kits on the card, and until now the device passed `app::init` an empty bank, so the drum pads were silent on hardware and the simulator used the render tool's host-only loader — two paths, one of them not the product's. Reading in place rather than through a staging buffer because a sample is up to 192 KB and the device has 63 KB of ordinary RAM free; there is nowhere to put a copy. `hal::sample_memory()` answers with nothing when no PSRAM is fitted, which is every board until bring-up, because writing to a section that is not backed would fault rather than fail. Rejected: samples in the firmware image (a kit could never be changed without a rebuild, which is what §12 rule 6 is against); streaming from the card at play time (file I/O in the audio path, forbidden by §12 rule 4). | At bring-up, when a real PSRAM chip says whether reads from it keep up with sixteen voices; or if a kit needs more than eight samples of two seconds. |
+| D-109 | A kit is readable text on the card: `tools/kit_builder.py` writes `kits/<id>/kit.txt` beside the header it already generates, both from the one `kit.json`, and `io::load_kit` reads it. One line a field, the five progressions in mode order, the eight pads in the order share-format §2 fixes with each pad's tap templates under it, and a step spelled exactly as a share code spells one — `engine::read_step` is now the only implementation of that table. Fractions are whole hundredths, so the device needs no float parser. `engine::Kit` holds its strings in fixed arrays rather than pointers, so a card kit and a compiled kit are one type, and `settings.txt`'s `kit=` line says which folder to play, falling back to the built-in kit when the card has no such kit. | 2026-09-03. §12 rule 6 asks for an open format so the community can make kits, and a kit that only exists as a C++ header can only be made by rebuilding the firmware. Text because §7.6 shows the card over USB and because the songs and settings are already text (D-104): one habit, not three. Rejected: parsing `kit.json` on the device (a JSON parser is a few hundred lines of firmware at a boundary that reads whatever a card holds, against the rule about reaching for the standard library first) and a packed binary (smaller and faster, but then only the tool can make a kit, which is the opposite of open). An unknown line fails the whole file rather than being skipped as an unknown settings row is: a setting the device ignores costs one row, a kit field it ignores would be an instrument quietly playing something other than what the kit says, and a field left out entirely fails for the same reason — the zero it would leave behind is not this kit — as does a single-valued field said twice, since which of the two the kit meant is not a question this firmware gets to answer. Every card string that reaches a path is checked against the grammar rather than trusted: a kit id is share-format §2's `[a-z0-9]{1,12}`, a pad's source is a plain file name, and a kit whose id is not the folder it was found in is refused, because its samples are looked for by its own id and would be hunted for somewhere else. The test that the card kit equals the compiled kit is what holds the builder's two outputs together, and CI diffs both. | If a kit needs a field that is not a number, a name or a share code; or when kits can be chosen from the settings view, which needs the samples reloaded rather than just the file re-read. |

firmware/src/app/app.cpp

@@ -11,6 +11,7 @@
 #include "engine/kits/lofi.h"
 #include "engine/share.h"
 #include "hal/hal.h"
+#include "io/kit.h"
 #include "io/share.h"
 #include "ui/color.h"
 #include "ui/draw.h"
@@ -46,14 +47,17 @@ constexpr int kLineCapacity = 320;
 constexpr int kFooterCapacity = 32;
 const char* const kTapMarker = "tap";  // the top row while tap tempo waits (§8.2, D-102)
 
-const engine::Kit& kit = engine::kits::kLofi;
+// The card may replace it at init; the scheduler and controller hold its address,
+// so it is filled in place rather than swapped.
+engine::Kit the_kit = engine::kits::kLofi;
+sound::SampleBank the_samples;
 
 // The engine (207 KB) and the model (85 KB) go to the platform's bulk memory; the
 // scheduler's 30 KB event list and the queues stay with the ordinary statics.
 HAL_BULK_MEMORY sound::Engine sound_engine;
-HAL_BULK_MEMORY Model the_model(kit);
-Scheduler scheduler(kit);
-Controller controller(kit);
+HAL_BULK_MEMORY Model the_model(the_kit);
+Scheduler scheduler(the_kit);
+Controller controller(the_kit);
 AudioPath audio;
 FiredLog the_fired_log;
 uint64_t last_frame_us = 0;
@@ -196,7 +200,7 @@ void draw_song(uint16_t* framebuffer) {
 // milliseconds, a frame is not. The code carries the loop's own id, not the id of
 // the loop it came from, which stays in the state for the footer (§10.2, D-105).
 void draw_share(uint16_t* framebuffer, int bottom) {
-  const engine::SectionCode code = io::shared_code(frame_state, kit);
+  const engine::SectionCode code = io::shared_code(frame_state, the_kit);
   if (std::strcmp(code.text, shown_code.text) != 0) {
     shown_code = code;
     ui::encode_share_qr(shown_code.text, qr);
@@ -206,7 +210,7 @@ void draw_share(uint16_t* framebuffer, int bottom) {
 
 void draw_settings(uint16_t* framebuffer) {
   const io::Settings& settings = frame.settings;
-  const ui::SettingsModel model{frame_state.key,      frame_state.swing,      kit.id,           settings.brightness,
+  const ui::SettingsModel model{frame_state.key,      frame_state.swing,      the_kit.id,           settings.brightness,
                                 settings.sleep_minutes, settings.midi_clock_in, settings.midi_clock_out, settings.sync_in,
                                 settings.sync_out,      kFirmwareVersion,       frame.settings_cursor};
   ui::draw_settings_view(framebuffer, model);
@@ -259,7 +263,7 @@ void draw(uint64_t now_us) {
       draw_ring(framebuffer, position, bottom);
       break;
     case View::text:
-      ui::draw_text_view(framebuffer, frame_state, kit, bottom);
+      ui::draw_text_view(framebuffer, frame_state, the_kit, bottom);
       break;
     case View::song:
       draw_song(framebuffer);
@@ -322,14 +326,16 @@ bool tutorial_done() {
 // Builds everything afresh, so the tests can start over as often as they like; on
 // the device it runs once. Placement new is construction in place, not heap
 // allocation, and it keeps an 85 KB model off the stack.
-void init(const sound::SampleBank& samples) {
+void init() {
   const bool first_run = !tutorial_done();
-  read_card(kit);  // both reads happen before the lock: a card takes milliseconds (D-104)
+  // Everything the card has to say, before the lock: a card takes milliseconds (D-104).
+  read_card(the_kit);
+  io::load_samples(the_kit, the_samples);
   hal::lock();  // a timer already ticking (the harness re-initialises) cannot see the app half made
   new (&sound_engine) sound::Engine();
-  new (&the_model) Model(kit);
-  new (&scheduler) Scheduler(kit);
-  new (&controller) Controller(kit);
+  new (&the_model) Model(the_kit);
+  new (&scheduler) Scheduler(the_kit);
+  new (&controller) Controller(the_kit);
   audio.reset();
   the_fired_log = FiredLog{};
   last_frame_us = 0;
@@ -339,11 +345,11 @@ void init(const sound::SampleBank& samples) {
   applied_brightness = -1;
   the_model.tutorial = Tutorial{first_run, 0, false};
   apply_card(the_model);  // the settings and the song the device was left on
-  audio.init(sound_engine, kit, samples);
+  audio.init(sound_engine, the_kit, the_samples);
   const uint32_t seed = static_cast<uint32_t>(hal::now_us());
   scheduler.set_seed(seed);
   controller.set_seed(seed);
-  audio.params.publish(params_of(the_model.sections[0].state(), kit, the_model.master_volume));
+  audio.params.publish(params_of(the_model.sections[0].state(), the_kit, the_model.master_volume));
   hal::unlock();
   hal::start_audio(&render);
   hal::start_timer(kTimerPeriodUs, &on_timer);
@@ -370,13 +376,14 @@ void tick() {
   draw(now_us);
   hal::present();
   light_leds(frame_position, frame_state);
-  keep_card(now_us, the_model, kit);
+  keep_card(now_us, the_model, the_kit);
   if (frame.settings.brightness != applied_brightness) {
     applied_brightness = frame.settings.brightness;
     hal::set_brightness(applied_brightness);
   }
 }
 
+const engine::Kit& kit() { return the_kit; }
 const Model& model() { return the_model; }
 const FiredLog& fired_log() { return the_fired_log; }
 int64_t audio_position() {

firmware/src/app/app.h

@@ -12,11 +12,14 @@
 // audio and timer callbacks are registered with the HAL by init.
 namespace app {
 
-// `samples` holds the kit's WAVs, or empty samples: the platform entry point
-// provides them (the host reads spec/kits/, the device waits for io/). Once at
-// start-up on a platform; the test harness calls it again between cases, which
-// is safe because its audio callback runs only when the test calls it.
-void init(const sound::SampleBank& samples);
+// Brings the app up on whatever the card holds: the kit the settings name and its
+// samples, the songs, the settings themselves. Once at start-up on a platform; the
+// test harness calls it again between cases, which is safe because its audio callback
+// runs only when the test calls it.
+void init();
+
+// The kit being played, which is the card's or the one built in (D-109).
+const engine::Kit& kit();
 
 // Input, holds and timeouts, the fired log, a frame when one is due.
 void tick();

firmware/src/app/card.cpp

@@ -4,6 +4,8 @@
 
 #include "engine/state.h"
 #include "hal/hal.h"
+#include "engine/kits/lofi.h"
+#include "io/kit.h"
 #include "io/store.h"
 
 namespace app {
@@ -186,8 +188,11 @@ bool due(bool differs, uint64_t now_us, bool& dirty, uint64_t& changed_us) {
 
 }  // namespace
 
-void read_card(const engine::Kit& kit) {
+void read_card(engine::Kit& kit) {
   io::load_settings(boot_settings);
+  // The kit the settings name, or the one built in when the card has no such kit —
+  // a device with an unreadable kit folder still plays (D-109).
+  if (!io::load_kit(boot_settings.kit, kit)) kit = engine::kits::kLofi;
   io::LoadResult current = io::LoadResult::missing;
   for (int slot = io::kFirstSlot; slot <= io::kLastSlot; ++slot) {
     const bool is_current = slot == boot_settings.song;

firmware/src/app/card.h

@@ -12,9 +12,10 @@
 namespace app {
 
 // Boot, in two halves so that holds at start-up too: read_card takes the settings,
-// the song they name and which slots hold a song off the card, and apply_card puts
-// them into a model the caller has just built, under the lock.
-void read_card(const engine::Kit& kit);
+// the kit they name, the song they name and which slots hold a song off the card, and
+// apply_card puts them into a model the caller has just built, under the lock. The
+// kit is read before the songs, since a song's code is decoded against it.
+void read_card(engine::Kit& kit);
 void apply_card(Model& model);
 
 // Every frame: the pick the song view made, the erase a factory reset asked for,

firmware/src/engine/kit.cpp

@@ -0,0 +1,51 @@
+#include "engine/kit.h"
+
+#include <cstring>
+
+namespace engine {
+
+namespace {
+
+bool same(const DegreeList& a, const DegreeList& b) {
+  return a.length == b.length && std::memcmp(a.degrees, b.degrees, a.length) == 0;
+}
+
+bool same(const TapTemplate& a, const TapTemplate& b) {
+  if (a.step_count != b.step_count) return false;
+  for (int i = 0; i < a.step_count; ++i) {
+    if (a.steps[i] != b.steps[i]) return false;
+  }
+  return true;
+}
+
+bool same(const KitPad& a, const KitPad& b) {
+  if (std::strcmp(a.name, b.name) != 0 || a.voice != b.voice || std::strcmp(a.source, b.source) != 0) return false;
+  if (a.pitch_semitones != b.pitch_semitones || a.start != b.start || a.decay != b.decay) return false;
+  if (a.octave != b.octave || a.send != b.send || a.template_count != b.template_count) return false;
+  for (int i = 0; i < a.template_count; ++i) {
+    if (!same(a.templates[i], b.templates[i])) return false;
+  }
+  return true;
+}
+
+}  // namespace
+
+bool operator==(const Kit& a, const Kit& b) {
+  if (std::strcmp(a.id, b.id) != 0) return false;
+  for (int i = 0; i < kTrackCount; ++i) {
+    if (!same(a.pads[i], b.pads[i])) return false;
+  }
+  for (int i = 0; i < kModeCount; ++i) {
+    if (!same(a.progressions[i], b.progressions[i])) return false;
+  }
+  if (!same(a.pluck_sequence, b.pluck_sequence)) return false;
+  if (a.dice_loop_count != b.dice_loop_count) return false;
+  for (int i = 0; i < a.dice_loop_count; ++i) {
+    if (std::strcmp(a.dice_loops[i], b.dice_loops[i]) != 0) return false;
+  }
+  return a.swing_hundredths == b.swing_hundredths && a.filter == b.filter && a.fx == b.fx &&
+         a.sidechain.on == b.sidechain.on && a.sidechain.duck_db == b.sidechain.duck_db &&
+         a.sidechain.release_ms == b.sidechain.release_ms;
+}
+
+}  // namespace engine

firmware/src/engine/kit.h

@@ -9,6 +9,9 @@
 // is the source and tools/kit_builder.py generates engine/kits/<id>.h from it. The
 // engine reads sends, templates, progressions, the pluck sequence, dice loops and
 // the swing/filter/fx defaults; the voice fields are for sound/.
+//
+// Every string here is a fixed array rather than a pointer, so a kit read off the
+// card owns its own words and is the same type as the one compiled in (D-109).
 namespace engine {
 
 enum class Voice : uint8_t { sample, synth };
@@ -20,9 +23,9 @@ struct TapTemplate {
 };
 
 struct KitPad {
-  const char* name;
+  char name[kPadNameLength + 1];
   Voice voice;
-  const char* source;      // sample pads: the wav file; synth pads: the preset name
+  char source[kPadSourceLength + 1];  // sample pads: the wav file; synth pads: the preset name
   int8_t pitch_semitones;  // sample pads
   float start;             // sample pads: start point as a fraction of the sample
   float decay;             // sample pads: 1.0 = full length
@@ -47,18 +50,23 @@ struct Sidechain {
 };
 
 struct Kit {
-  const char* id;
+  char id[kKitIdLength + 1];
   KitPad pads[kTrackCount];
   DegreeList progressions[kModeCount];  // indexed by Mode
   DegreeList pluck_sequence;
   uint8_t dice_loop_count;
-  const char* dice_loops[kMaxDiceLoops];  // share codes; only their tracks are used (D-028)
+  char dice_loops[kMaxDiceLoops][kSectionCodeCapacity];  // share codes; only their tracks are used (D-028)
   uint8_t swing_hundredths;
   Tenths filter;
   Tenths fx;
   Sidechain sidechain;
 };
 
+// A kit read off a card and the one compiled in are the same kit or they are not:
+// the test that says so is what keeps tools/kit_builder.py's two outputs in step.
+bool operator==(const Kit& a, const Kit& b);
+inline bool operator!=(const Kit& a, const Kit& b) { return !(a == b); }
+
 inline const KitPad& pad_of(const Kit& kit, Pad pad) { return kit.pads[index_of(pad)]; }
 
 // The scale degree a melodic step's position selects; a position past the end