memlnaut-nisps/docs/redesign/upstream-firmware-survey.md

Upstream Firmware Survey — git archaeology of the MusicallyEmbodiedML ecosystem

Dated 2026-06-27. Author: research agent (read-only). All SHAs from a fresh git fetch --all + memllib submodule-gitdir fetch (incl. operator's memllib fork monkey-w1n5t0n/memllib).

TL;DR — the divergence headline

origin/main and upstream/main are two different codebases sharing one ancestor. They forked at 6efbe9c ("voicing", 2026-04-14) and have NOT touched a common file since. origin/main is the complete C++20 + SolidJS clean rewrite (nisps/, playground/, firmware/, schemas/codegen). upstream/main is the original Arduino .ino + modes/*.hpp firmware tree, which the lab kept developing in parallel. The 49 commits upstream has that origin lacks are real firmware features on an architecture origin deliberately abandoned — they are ports, not merges. There is no clean fast-forward or 3-way merge path; every integration is a re-implementation against the new core.

                6efbe9c "voicing" (2026-04-14)  ← merge-base, last shared tree
                /                         \
   origin/main (193 ahead)            upstream/main (49 ahead)
   C++20/SolidJS rewrite              old .ino/modes firmware tree
   pins memllib 4733ca0 (orphan)      pins memllib e291192 (+62 vs origin's line)

---

1. Branch map

1.1 Superproject — origin (operator fork) and upstream (lab)

Branch	Remote	Last push	Author	vs its main¹	Purpose	Judgment
main	origin	2026-06-16	monkey-w1n5t0n	—	The C++20/SolidJS rewrite.	canonical
feat/feedback-explore-modes	origin	2026-06-08	w1n5t0n	+42 / −193	Pins memllib abe93ec = the FEEDBACK_MODE (avoid / randomise-outputs / randomise-MLP) commit. Source material for docs/redesign/feedback-modes-port-spec.md.	real RL work to port (already spec'd, not yet in main)
feat/useq-celium-opus46	origin	2026-06-14	w1n5t0n	+2 / −36	MEMLCelium useq experiment (Opus-4.6 session).	experiment — superseded by opus47
useq-celium-opus47	origin	2026-04-20	w1n5t0n	+6 / −36	Later MEMLCelium useq iteration.	experiment
feat/unified-preset-system	origin	2026-04-16	w1n5t0n	+46 / −55	Preset-system spike; heavily diverged, stale.	abandoned/spike
port-solidjs	origin	2026-06-14	w1n5t0n	+31 / −66	Early SolidJS port scaffolding; main has moved well past it.	superseded by main
main	upstream	2026-06-22	chriskiefer	—	Old firmware tree; LiveFX/VerbFX/DJFX/staticmlp/jolts/noise.	real firmware to port
SB2026	upstream	2026-05-15	chriskiefer	+0 / −30²	Superbooth-2026 build: mode sample-rate, DISLIKES, screen layout, sample player. Fully merged into upstream/main.	merged — port via memllib
SaxFX	upstream	2026-05-05	chriskiefer	+0 / −42²	Sax FX app. Fully merged into upstream/main.	merged — historical
bettysax	upstream	2026-02-21	chriskiefer	+1 / −72²	Bettysax; 1 extra commit c5f0314 "demo" not in main.	novelty/demo

¹ "+X / −Y" = (commits the branch is ahead of its own main) / (commits behind). For git rev-list --left-right --count main...branch the left count is main-only (= how far the branch is behind) and the right count is branch-only (= ahead) — read them in that order. For upstream branches, main = upstream/main. ² SB2026 / SaxFX show ahead=0 because they are contained in upstream/main (git rev-list upstream/main..branch = 0). The "−30/−42" is just how far main has advanced past their tip.

1.2 Submodule — src/memllib (lab origin = MusicallyEmbodiedML/memllib; w1n5t0n = operator fork)

memllib is where the RL interface (InterfaceRL) and the DISLIKES/feedback logic actually live — the superproject only pins it. Two pins matter:

• origin/main superproject pins memllib 4733ca0 — an orphaned commit: not reachable from any ref in the lab repo or the operator's fork. Likely a rebased/abandoned tip. Cannot be diffed by SHA; treat origin/main's memllib as "stale, off-graph."
• upstream/main superproject pins memllib e291192 ("l r input swap", 2026-06-22) — current lab tip, and it already contains the SB2026 dislikes/rlview work (80420d1 "rlview and dislike", d9bdcd6 "remove dislike opts screen").
• origin/feat/feedback-explore-modes pins memllib abe93ec ("InterfaceRL: add FEEDBACK_MODE setting", 2026-06-08, authored by w1n5t0n on the operator's fork). This is the operator's own RL feedback commit, branched off lab 616b8e7 ("cc select"); it is +1/−6 vs e291192.

memllib branch	Last push	Author	ahead of main³	Purpose	Judgment
main (e291192)	2026-06-22	chriskiefer	—	Current lab RL lib (incl. dislikes).	canonical lib
SB2026 (1997699)	2026-05-15	chriskiefer	+0 / −20	Superbooth dislikes/rlview. Fully merged into main.	merged
w1n5t0n/feat/feedback-explore-modes (abe93ec)	2026-06-08	w1n5t0n	+1 / −6	Operator's FEEDBACK_MODE 3-mode enum.	real — already spec'd to port
maincandidate	2025-11-06	chriskiefer	+54	Pre-2026 staging.	historical
displayview	2025-10-13	chriskiefer	+82 / −11	Display work.	historical
bettysaxanalysis	2025-09-03	A. Martelloni	+124	Sax analysis.	historical
display2, pafcarl, pafsynth, bunty_new, studiofx, xiasri, rlversion, sdcard, superbooth, display, imlzoom, tomchris, iceland, chris, features	2025-05…08	chris / Martelloni	+120…+243	2025 app/feature branches.	historical/abandoned

³ git rev-list --left-right --count main...branch inside the memllib gitdir.

1.3 Tags

Tag	Points at	Date	In upstream/main?	In origin/main?	Notes
LiveFX_1.0.0	701f2d9	2026-06-22	yes	no	Newest firmware release; old tree.
VerbFX_1.1.0	a18d9c6	2026-06-16	yes	no	Large-verb FX release.
DJFX_TR6S_MICROQ	ed4ac6d	2026-05-25	yes	no	DJFX + TR-6S + MicroQ firmware.
MEMLCelium_0_1_alpha	1e441cb	2026-04-20	yes	no	MEMLCelium alpha; old tree.
PAF_1_1_0	bae80fb	2026-03-29	yes	yes	Pre-fork; in both.
VerbFX	bae80fb	2026-03-29	yes	yes	Same commit as PAF_1_1_0; pre-fork.

Only the two pre-fork tags (bae80fb) exist in origin/main. Every release tag from MEMLCelium_0_1_alpha onward marks old-tree firmware origin/main never received.

1.4 Sibling org repos (gh repo list MusicallyEmbodiedML, 70 repos)

Active / firmware-relevant:

• memlp (2026-06-24) — the underlying NN library for microcontrollers; memllib's dependency. Recently active.
• memllib (2026-06-22) — the RL/interface lib (the submodule). The live one.
• MEMLNaut (2025-11-13) — the hardware/board repo.
• memlp_tests / memlp_test / RLTests — test harnesses for the NN/RL libs; relevant if porting RL behavior and wanting reference vectors.
• musicallyembodiedml.github.io (2026-06-22) — the docs site referenced by CLAUDE.md.

Everything else is a 2024–2025 per-app fork (PAF, Xiasri, studioFX, euclidean, FM, subtractive, XMOS-era boards, etc.) — historical context, not integration targets. The whole "one repo per app" pattern is exactly what the nisps/ rewrite consolidates; these forks are the museum.

---

2. Dated timeline

Date	Event
2026-03-29	bae80fb — PAF_1_1_0 / VerbFX tags. Last point both trees share a tag.
2026-04-14	6efbe9c "voicing" — fork point (merge-base of origin/main & upstream/main).
2026-04-20	MEMLCelium_0_1_alpha (1e441cb); memllib psram. First upstream-only release.
2026-05-05	upstream SaxFX branch tip (33b6542 "memlib sub"). (NB: fcef420 "sax fx ftw" is a 2026-05-15 commit on upstream/main, not the SaxFX tip — earlier draft conflated them.)
2026-05-15	upstream SB2026 tip (c617fcc "mode sample rate, dislikes, screen layout, sample player"). memllib SB2026 (1997699).
2026-05-25	DJFX_TR6S_MICROQ (ed4ac6d).
2026-06-08	origin feat/feedback-explore-modes — operator's FEEDBACK_MODE work; memllib fork abe93ec.
2026-06-16	origin/main HEAD (f256217, AudioWorklet fix). VerbFX_1.1.0 (a18d9c6) on upstream.
2026-06-22	upstream/main HEAD (701f2d9 "livefx"); LiveFX_1.0.0. memllib main e291192.
2026-06-27	This survey.

---

3. Git relationships

• Merge-base (superproject): 6efbe9c ("voicing", 2026-04-14).
• origin/main vs upstream/main: git rev-list --left-right --count = 193 / 49 (origin 193 ahead = the entire rewrite; upstream 49 ahead = continued old-tree firmware). The trees are disjoint above the base: upstream/main's top-level is *.ino, modes/, voicespaces/, *AudioApp.hpp; origin/main's is nisps/, playground/, firmware/, schemas/, codegen/. Correction (verified): it is not true that "no file is co-modified." A git merge-tree/name-status comparison above the base shows ~20 paths the two sides both touched — but for nearly all of them the relationship is delete-on-origin / modify-on-upstream (the old .ino, modes/*.hpp, voicespaces/VerbFX/basic.hpp, src/memlp), i.e. delete/modify conflicts, not content overlaps. The one genuine both-sides-M conflict is the src/memllib gitlink (origin → 4733ca0, upstream → e291192). So the practical conclusion stands — every path resolves to a conflict (delete/modify or submodule-pin) with nothing cleanly 3-way-mergeable; upstream commits must be hand-ported — but the literal "no file is co-modified" was wrong.
• What origin/main is behind on (the 49): the upstream-only firmware features — newest first: 701f2d9 livefx, a18d9c6 verbfx, 0538eb9 staticmlp, 99bd9b1 jolts, 7ceac18 noise / a6e7af1 explore noise update, 75e0f44 large verb, 414590b tr8s home mapping / be6eac7 fx, tr8s / 5a34a4a djfx single-cc fix, d1182f1 djfx alpha, 24c2ad8 d50, sysex, 1436250 midi output select, 98c7449 input selection, fcef420 sax fx, c617fcc SB dislikes/sample-rate/sample-player, ee2814e focus targets memlcelium, 47fc77b/2429bcc geo push rlview, d301cc7 rlview and dislike.
• What origin/main is ahead on (the 193): the whole platform — nisps/ core, 8 engines as concepts, CRTP modes, WASM bridge, SolidJS playground, schemas/codegen, verification harness (golden+parity+lint+CI), a-immersive feature parity. None of this exists upstream.
• memllib pin divergence: origin/main → 4733ca0 (orphaned, off-graph); upstream/main → e291192 (current, +62 commits on the lab main line, includes dislikes). origin's memllib pin is effectively abandoned and should be re-pinned regardless of what else is ported.
• SB2026 / SaxFX are dead branches (fully folded into upstream/main); the content worth taking is reachable from upstream/main and from memllib main. bettysax has one stray c5f0314 "demo" commit — ignorable.

---

4. Ranked integration recommendations

Because the architectures are disjoint, "integrate" means port the behavior into nisps/ + playground/, not git merge. Ranked by mission impact (RL/feedback richness and firmware-feature parity).

Rank 1 — Land the FEEDBACK / DISLIKES port (origin already did the hard part)

• Source commits: memllib abe93ec (operator's FEEDBACK_MODE 3-mode enum) on origin/feat/feedback-explore-modes; cross-checked against memllib main 80420d1/d9bdcd6 (SB2026 dislikes in InterfaceRL) which upstream/main pins via e291192.
• Why first: This is the negative-feedback / RL core of the whole project, and the work is already written up as an implementation-ready spec at docs/redesign/feedback-modes-port-spec.md (new nisps::ml::FeedbackController<MLP_T>, WASM C API, 11 ctest cases, parity Stage 5). The branch feat/feedback-explore-modes and the half-present nisps/ml/feedback.hpp + tests/cpp/test_mlp_feedback.cpp in the working tree show this is mid-flight. Finish it and merge to main. The spec's AVOID reconciliation decision (route to existing move_weights, skip the firmware-only k-NN geometric centroid push) is sound and should be recorded in ALIGNMENT.md.
• Action: complete nisps/ml/feedback.hpp, wire WASM bindings + mode-runtime.ts, land the tests, re-pin memllib off the orphan. Do not try to port the old ReplayMemory geometric push now (out of scope per spec).

Rank 2 — Re-pin memllib off the orphaned 4733ca0

• Source: memllib main e291192 (or abe93ec if you want the feedback commit pinned directly).
• Why: origin/main pins an off-graph commit nothing can resolve; this is a latent footgun (a fresh submodule update cannot check it out cleanly from the canonical remote). Pin to a real, reachable commit as part of Rank 1. Low effort, removes a trap.

Rank 3 — Port the new upstream firmware engines as nisps/ engines (selective)

The 49 upstream commits are firmware apps on the old tree. Port the ones with mission value, highest-value first:

• a18d9c6 verbfx / 75e0f44 large verb (→ VerbFX_1.1.0): origin already has verb_fx; diff the upstream large-verb params and bring improvements into the engine. Medium effort, high audio value.
• d1182f1 djfx alpha + ed4ac6d (→ DJFX_TR6S_MICROQ) + 5a34a4a single-CC fix: DJFX is a new engine not in origin's 8. Port as a new nisps/engines/ engine + mode + schema if DJFX is wanted in the playground. Higher effort (new engine).
• 701f2d9/adbc058 livefx (→ LiveFX_1.0.0): newest app; evaluate whether it subsumes existing FX modes before porting.
• 0538eb9 staticmlp + 99bd9b1 jolts + 7ceac18 noise/a6e7af1 explore-noise: these are RL/exploration changes (static-MLP hold, jolts, explore-noise) that overlap conceptually with the Rank-1 feedback work and with origin's existing spread/noise model. Review them alongside the feedback port — some may already be covered by RandomiseMlp/RandomiseOutputs; "explore noise" likely maps to the existing spread/OU-noise knobs. Audit before porting to avoid duplicating behavior.
• 414590b tr8s home mapping / be6eac7 fx, tr8s / 10b8fca dynamic focus for TR8S / 296bec6 target selection: the TR-8S focus-mask / dynamic-focus work is the firmware analogue of the activeDims_ focus feature the feedback spec already accounts for. Useful reference for the focus-mask UI; port the mask semantics, not the firmware display code.

Rank 4 — Take SB2026 sample-rate / sample-player only if needed

• Source: c617fcc (SB2026, already in upstream/main). Per-mode sample rate and a sample player are firmware-platform features; the playground runs through an AudioWorklet, so most of this is N/A. Port only the per-mode sample-rate concept if a mode genuinely needs it. Low priority.

Do NOT integrate

• port-solidjs, feat/unified-preset-system, feat/useq-celium-opus46, useq-celium-opus47 (origin): superseded/abandoned spikes — main has moved past them.
• upstream SaxFX, bettysax (incl. c5f0314 "demo"): app-specific / demo, no mission value to the rewrite.
• All 2024–2025 memllib feature branches and per-app org forks: historical museum.

---

5. Surprises

1. upstream/main is the old tree, not "main ahead of the fork." The naming invites the assumption that upstream advanced the same codebase; it didn't — the lab kept shipping the pre-rewrite .ino firmware. The 49 commits are a parallel line, never to be fast-forwarded.
2. origin/main pins an orphaned memllib commit (4733ca0) that exists in neither the lab repo nor the operator's own memllib fork — an off-graph gitlink that a clean checkout cannot resolve.
3. The dislikes/RL feedback work the task flagged as "to find" is already (a) merged into upstream via SB2026 → memllib e291192, AND (b) re-implemented by the operator on feat/feedback-explore-modes (memllib abe93ec), AND (c) fully spec'd for the new core in docs/redesign/feedback-modes-port-spec.md — with nisps/ml/feedback.hpp and tests/cpp/test_mlp_feedback.cpp already present (untracked) in the working tree. The feedback integration is not a research question; it's a half-finished implementation to land.

---

Verification (checked against source)

Adversarial re-check, 2026-06-27, independent of the original author. Re-ran the git/gh commands and a fresh bare clone of lab + operator-fork memllib.

Confirmed correct:

• Merge-base 6efbe9c "voicing" 2026-04-14 (git merge-base origin/main upstream/main).
• origin/main HEAD f256217 2026-06-16; upstream/main HEAD 701f2d9 "livefx" 2026-06-22.
• origin 193 ahead / upstream 49 ahead (git rev-list --left-right --count origin/main...upstream/main); the 49 upstream-only commits and the specific SHAs cited in §3 (701f2d9, a18d9c6, 0538eb9, 99bd9b1, 7ceac18, a6e7af1, 75e0f44, 414590b, be6eac7, 5a34a4a, d1182f1, 24c2ad8, 1436250, 98c7449, fcef420, c617fcc, ee2814e, 47fc77b, 2429bcc, d301cc7) all resolve with matching messages.
• memllib 4733ca0 is genuinely orphaned — git cat-file fails for it even after fetching BOTH MusicallyEmbodiedML/memllib and monkey-w1n5t0n/memllib into a bare clone. The survey's headline surprise holds.
• memllib main = e291192 and contains 80420d1 "rlview and dislike" + d9bdcd6 "remove dislike opts screen".
• memllib abe93ec "InterfaceRL: add FEEDBACK_MODE setting" 2026-06-08 by w1n5t0n, branched off 616b8e7 "cc select", +1/−6 vs main; superproject feat/feedback-explore-modes pins it.
• All six tags (LiveFX_1.0.0 701f2d9, VerbFX_1.1.0 a18d9c6, DJFX_TR6S_MICROQ ed4ac6d, MEMLCelium_0_1_alpha 1e441cb, PAF_1_1_0/VerbFX bae80fb) — SHAs, dates, and origin/upstream containment all match.
• Upstream branch ahead/behind: SB2026 c617fcc +0/−30, SaxFX +0/−42, bettysax +1/−72 with stray c5f0314 "demo"; memllib SB2026 = 1997699.

Corrected (real errors found):

1. Origin-branch ahead/behind columns were inverted in table 1.1 (the author read the --left-right left/right columns the wrong way round). Real values: feat/feedback-explore-modes +42/−193 (was +193/−42); feat/useq-celium-opus46 +2/−36; useq-celium-opus47 +6/−36; feat/unified-preset-system +46/−55; port-solidjs +31/−66. Fixed in table 1.1 and footnote ¹. (These branches are all behind main by ~the full rewrite, which is the opposite of what the original numbers implied.)
2. SaxFX timeline tip was wrong (§2): the SaxFX branch tip is 33b6542 "memlib sub" (2026-05-05), not fcef420 "sax fx ftw" — fcef420 is a 2026-05-15 upstream/main commit, not on SaxFX. Date was right, SHA/message wrong. Fixed.
3. "No file is co-modified" (§3) was literally false. ~20 paths are touched on both sides; for almost all the relation is delete-on-origin/modify-on-upstream (a conflict), and src/memllib is a genuine both-M submodule-pin conflict. The downstream conclusion (no clean 3-way merge; hand-port required) is unaffected. Fixed in §3.

The substance of the survey — disjoint trees, hand-port-only integration, orphaned memllib pin, feedback work already spec'd/half-implemented, ranked recommendations — survives verification. The errors are in the branch-delta bookkeeping, one timeline SHA, and one overstated absolute.

---

Correction (2026-06-27, from the RL judge-panel skeptic, verified against source)

The latest upstream InterfaceRL tip is 0a541cc "highlighting" (990 lines; optimise() at :601, kCentroidK=4 at the hpp :296, decay 0.0025f at :664, negLRRatio at :742) — NOT e291192/abe93ec, which are older. Mode 1 "Geometric dislike" must be ported to 0a541cc parity. Note: the in-tree submodule gitdir resolves none of 4733ca0/e291192/abe93ec/0a541cc — only the separate -upstream memllib checkout has them; the orphaned-pin footgun stands and 0a541cc is the re-pin/port target. See docs/redesign/rl-feedback-design.md §1 for the verified-ground-truth list.