AMYboard: phase-lock sketch loop() to the sequencer downbeat

[bwhitman]

Fixes the "loop() sounds out of phase with AMYSequence" problem (e.g. dx7_groove_128_bpm on AMYboard World: the AMY-sequenced drums are locked to the absolute tick grid, but the sketch's local step counter starts at 0 whenever the sketch loads — some arbitrary 32nd note inside the bar — so the bass/piano/arp play at a constant phase offset from the drums).

loop() callbacks already fire on the AMY sequencer's absolute tick grid (tick % 6 == 0 at 48 PPQ), and tulip_amy_sequencer_hook already hands the tick to the callback — _guarded_loop was just discarding it. Two changes in _start_sketch_loop:

1. Downbeat-aligned start: the first loop() call is held until the next bar boundary (tick % 192 == 0, 4/4 at 48 PPQ). Existing sketches' internal counters now start on the downbeat, in phase with AMYSequence bars, with no sketch changes. (Costs up to one bar of startup delay — ~1.9s at 128 bpm — which for music sketches means "starts on the one".)
2. loop(step) signature: sketches can declare def loop(step): and get the global 32nd-note index on the bar-locked grid (step % 32 == 0 is always a downbeat). Deriving bar position from step instead of a local counter also can't drift if a callback is ever dropped (mp_sched_schedule queue full under heavy UI). Detection is a one-time TypeError fallback, so plain loop() sketches are unchanged.

The default sketch template (canonical copy in amyboard.py, both fallback copies in spss.js) now uses loop(step) and documents the grid. Verified the three template copies are byte-identical and simulated the dispatch logic for both signatures (step-aware first call lands on step % 32 == 0; plain first call lands on tick % 192 == 0).

Note: the server-side sketch-generator prompt (railway) still teaches the old def loop(): convention — worth updating it to loop(step) so generated sketches are phase-locked by construction.

🤖 Generated with Claude Code

[bwhitman]

Added a commit bumping the amy submodule to latest amy main (3a7c176, 1.2.43), so merging this PR brings both the loop() downbeat sync and current AMY in one go. Note this is amy main — it does not include shorepine/amy#854 (sequencer-in-render-loop), which is still open; #1120 remains the test pin for that.

[bwhitman]

Two more commits, per Brian:

• loop(step) is now taught everywhere: AMY_AGENTS.md (read at request time by the sketch generator), the generator's base system prompt in tulip/server/amyboardworld_db_api.py (OUTPUT CONTRACT + all four example sketches — the arpeggio example also drops its wall-clock BPM math for the step grid), and docs/amyboard/online.md. Zero-arg loop() is documented as legacy.
• Refreshed tulip/server/refdocs/amy/ for the 1.2.43 pin per AGENTS.md (content identical, marker SHA updated).

Also: the amy 1.2.43 pin in this PR includes shorepine/amy#854 (merged as 1.2.42), so merging this brings the render-loop sequencer, the downbeat sync, and the guidance in one go. Closed the #1120 test pin as obsolete.

[github-actions]

🔌 AMYboard PR preview

Editor + flasher: https://amyboard-pr-1123.vercel.app/editor/

This preview bundles this PR's firmware — its flasher only flashes this build (not the release). Rebuilt on every push; removed when the PR closes.

The hardware CI has been kicked off and should return within a few minutes, stand by!

[github-actions]

🌷 Tulip Web PR preview

Tulip Web: https://tulip-pr-1123.vercel.app/run/

Flash a Tulip to this build: on-device run tulip.upgrade(pr=1123).

Rebuilt on every push; removed when the PR closes.

[github-actions]

🎛️ HW CI (physical bench)

AMYboard (USB-MIDI + AMY zP → audio; built-in tones + AMYboard World sketches acid/house/woodpiano over the SysEx control API): ❌ FAIL — a check did not match, or the run errored. See the log/artifacts.

Tulip (TULIP4_R11; serial-REPL audio + WiFi screenshot): ✅ PASS — flashed this PR’s firmware; all checks matched the references.

⬇️ Artifacts: recordings · screenshot · serial logs · run logs

_{Self-hosted bench. Audio spectral-compared to ref/hwci_basic.wav, the AMYboard World sketch refs (ref/{acid_generator,house_generator,woodpiano}.wav) + ref/tulip_basic.wav; Tulip screenshot pixel-compared to ref/tulip_screenshot.png. Both analog outs share one capture card, so the tests run sequentially.}