[Zac-Kyoti]

Related to #1175. @repeat98: option 3 from #1175, as agreed. #1098 is in, and main is merged (not rebased).

What was wrong

FM Synth + Sidechain Compressor + Mute Modes, with the stock FX2 effects kept, ran 8 bytes short of menu cave (PERSONALIZE setters: 68 bytes needed, 60 left), so the build fell back to the module-only FX2 chooser: COMPRESSOR alone (#1175). Your fix for the silent fallback is separate; this one frees the space.

What this changes

A shared placement rule, in both builders (owner review):

• A stock-DSP effect may list ColdFire units in modules/<id>/placement.json. They link into the DRAM runtime only when another selected module already carries one, and into the menu cave otherwise. The runtime is a fixed ~10 MB sample-memory reserve, so this never makes a set start paying it.
• Native: tools/build/runtime_join.py, which build_bus.py applies right after compose_map. tools/remix/ is untouched, so the pins over it (standalone recipes, table declarations) don't move. build_bus.py also resolves raw descriptor words after the platform runtime link (stage 1e), so a joined unit is named like a ROM one.
• Configurator: createStaticColdFireRuntime links joining units at their module's place in native placement order. A module that replaces a stock effect in place leads while the stock FX2 rows stay; leadingModules is shared with composeChoosers. module-menus.ts resolves the descriptor's raw pointers and detours from the runtime. With Fix: the configurator's DRAM link takes the ROM units' symbols, as the native builder does (#1312) #1343's rom parameter, leading is the eighth parameter, so Fix: the configurator's DRAM link takes the ROM units' symbols, as the native builder does (#1312) #1343's callers are unchanged.
• Packages: build-module-packages.py emits the joining units for the runtime's ISA into coldfire-packages.json (joinRuntime: true). Both builders refuse the rule for anything but a stock-DSP effect's descriptor units.

Sidechain Compressor 0.2.2, its first user:

• placement.json names sc_cf and sc_ui (1,314 B). The code is 0.2.1's.
• Source pin: Zac-Kyoti/octatrack-kyoti-fw ad7ecd2 (sdk/imports/sidechain-compressor-ad7ecd2.json).
• The USB package stays 0.2.1 (lagsBehind, card placement only), as you asked.
• README, TESTING.md and the hardware evidence keep main's text, with the 0.2.2 lines on top.

How I checked it

• Builder record sdk/infrastructure-verification/runtime-join-builder.json, with its test and chain entry. Two fresh native builds of the dram-rom-symbols record's 128 selections: one with the base commit's build_bus.py, one with this and runtime_join.py. Everything else is the base commit's, including Sidechain's folder without placement.json, so the builder is the only difference. Every image (98) and every refusal (30) is identical.
• Analog BD proofs re-exported natively (8 shards). Exactly the 28 built Analog BD + Sidechain selections change: Sidechain's units now join Analog BD's DRAM runtime. Every refusal (66) is identical, and nothing else moves.
• Packages: rebuilt in the isolated toolchain after the merge. The two joining objects are byte-identical to the ones flashed. Tape Echo's and Euclid's recipes are re-pinned.
• module:verify -- sidechain-compressor:
  • The committed record is the 0.2.2 run from before the merge: 162 selections, 64 images and 98 refusals matching, 0 mismatches.
  • Re-run on current main: 190 selections, 72 images and 110 refusals matching, 8 mismatches, every one a selection with Track Solo.
  • This is not this PR: on main, without it, npm run module:verify -- track-solo has 81 mismatches of 190 (sidechain-compressor+track-solo among them). Track Solo is USB-only, so the configurator leaves it out of card builds, while native octabam still builds its DRAM units and detours into the card image. Every module's coverage set now contains Track Solo selections, so every re-run hits it. Details below.
• New tests:
  • src/engine/runtime-join.test.ts: placement, native order, no reserve without another runtime.
  • sdk/tests/test_runtime_join.py: native rule.
  • Sidechain's two pin tests now pin the new import record and the 0.2.2 hardware image.
• Emulator (capture-module-ui.py, MKI panel): the [sidechain-compressor] compressor only fx available on fx2 #1175 image and the module alone show identical pixels on the FX1 chooser, COMPRESSOR's main page and page 2 with KEY selected. The [sidechain-compressor] compressor only fx available on fx2 #1175 image's FX2 chooser lists the stock effects.
• Hardware, MKI, 3 November 2026 (Zac Kyoti). Sidechain beside Direct Jump (units in DRAM) and the six modules of [sidechain-compressor] compressor only fx available on fx2 #1175, all tests passing: the FX2 chooser, page 2 on FX1 and FX2, same-core and cross-core keys, MON/KEY/KBAS/KWID, a direct jump, reload and power cycle.
  • Beside Direct Jump: the release image differs from the flashed one only in the core logger's identity text (137 bytes); every OS write and runtime unit is the same.
  • The [sidechain-compressor] compressor only fx available on fx2 #1175 set: it also carries Mute Modes 0.2.2, released after the run. Sidechain's part is unchanged. TESTING.md has the exact comparison.
• npm run pr:ready: Ready.

Not run: the USB beta base (Sidechain's USB package is unchanged, still 0.2.1) and Sidechain Ringmod on a unit.

Track Solo in card comparisons (found here, not fixed here)

Track Solo 0.2.4 is usbOnly, so cardBuildError refuses it and the configurator's static runtime never links it. Its native manifest still declares three Linked(..., dram=True) units and seven detours, so export-composition-proofs.py builds them into the card image, and every selection with Track Solo differs "outside the platform writes". It's in comparisonPool (availableModules(true)), so any module's module:verify now reports these.

Two possible fixes: leave USB-only modules out of the card comparison pool, or have native refuse a USB-only module in a card build so both sides match as refusals. Which do you prefer? I'm happy to send it as its own Fix:. This PR keeps its pre-merge Sidechain record until then.

What the guides lacked

The effects guide had nothing on where a module's ColdFire units go. A "ColdFire units that may move" bullet is in docs/module-guides/effects.md (Declare), and there's an SDK changelog entry.

• I read the guide for its category in docs/module-guides/, and TESTING.md lists what I did not test. An effect module holds one effect.
• Source and media are mine or properly licensed, with authors and full licence texts kept. Nothing comes from Elektron firmware.
• Screenshots are real captures of the current module UI. Hardware results are what a named person saw on this exact build; emulator results are labelled as emulator results.

🤖 Generated with Claude Code

[repeat98]

Thanks, Zac, this is a good way to do option 3. No need to split it. The placement rule has one user and its tests are built on Sidechain, so I'll review the builder part here.

One thing before it's ready: src/engine/assets/octatrack-module-packages.json still lists Sidechain Compressor at 0.2.1 with no lagsBehind, and npm run octatrack:module-packages -- --check refuses a USB package that is behind the catalogue. 0.2.2 changes nothing over USB, so please declare the lag ("lagsBehind": "0.2.2-experimental" and a lagReason saying it's the card placement only) instead of shipping a new USB package that does nothing. Then, once #1098 is in, merge main, run npm run pr:ready until it says Ready and mark this ready for review.

[Zac-Kyoti]

Thanks, Jannik. Both points are pushed (head b9ea7000):

• USB lag: Sidechain Compressor's row in octatrack-module-packages.json now has "lagsBehind": "0.2.2-experimental", with a lagReason saying 0.2.2 changes only the card build's placement and the USB package and controller are 0.2.1's. npm run octatrack:module-packages -- --check passes: "sidechain-compressor kept at 0.2.1-experimental".
• One change while doing that: the native join rule moved out of tools/remix/machine_composition.py into tools/build/runtime_join.py, which build_bus.py applies right after compose_map. tools/remix/ is the base's byte for byte again. Otherwise this PR would have moved the hashes that the standalone recipes and Mute Modes' table declaration (Mute Modes 0.2.2-experimental: SHADOW out of the stock timestretch task's SRAM (owner review) #1007) pin over tools/remix/*.py. Now only the asset files move, and Tape Echo's and Euclid's recipes are re-pinned to them as usual. Same behaviour; the two SC objects are byte-identical.

Once #1098 is in, I'll merge main, regenerate, re-export Analog BD's proofs, re-run module:verify, run pr:ready until it says Ready and mark this ready.

[repeat98]

Hi Zac, #1098 is merged, so this one can move again. It conflicts with main now, mostly in Sidechain's own README, TESTING.md and hardware evidence, which #1098 changed for the MON words. Please merge main (no rebase), keep main's side in those files and add your 0.2.2 lines on top, relink the packages, and run pr:ready until it says Ready. Then mark it ready for review once the checks are green.

[Zac-Kyoti]

@repeat98 Done: main merged (no rebase), Sidechain's README, TESTING.md and hardware evidence on main's text with the 0.2.2 lines on top, packages relinked, pr:ready Ready, checks green. Marked ready for review.

One thing for you in the description, under Track Solo in card comparisons: Track Solo is USB-only, but native octabam still builds its DRAM units into card images, so every module's module:verify now mismatches on Track Solo selections. On main, Track Solo's own comparison has 81 of 190. Sidechain's re-run hits it 8 times, all with Track Solo, so this PR keeps its pre-merge record. Tell me which fix you'd like and I'll send it as a Fix: PR.

[repeat98]

Hi Zac, sorry, two of my merges this morning (Analog BD 0.1.7 and the new base) conflicted with yours again. Every conflict was a generated file, so I merged main into your branch myself and pushed: packages from the isolated build (only provenance moved), Tape Echo and Euclid re-pinned, and Analog BD's proofs re-exported. The same 28 Analog BD + Sidechain selections change as in your run, and every menu and refusal is identical. I'll merge once the checks are green.

On Track Solo: please send the Fix: that leaves USB-only modules out of the card comparison pool. That matches what the configurator offers and leaves native as it is. Thanks for the quick turnaround yesterday.