songhash 0.1.0__tar.gz

songhash-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.claude/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+*.wav
+*.mid
+*.flac
+*.sf2
+*.sf3
+assets/v1/sf2/
+showcase/
+cross-mood/

songhash-0.1.0/AESTHETICS.md

@@ -0,0 +1,73 @@
+# Mood aesthetics
+
+Per-mood design intent. Useful for understanding what a mhash is *trying* to do, separate from any one render's particular output.
+
+| Mood | Intent | Tempo | Modes | Groove pool | Form pool | FX chain |
+|---|---|---|---|---|---|---|
+| **M0 Ambient** | floating, no goal, pad-led | 54-80 | ionian / aeolian / dorian / lydian / phrygian | ambient_drift / neo_soul / straight_4_4 | through_composed / A_Aprime / theme_var / ostinato_layer / pulse_only | big plate reverb + chorus + low-shelf cut |
+| **M1 Ballad** | warm, hopeful, song-form | 64-80 | ionian / aeolian / dorian | straight_4_4 / neo_soul / gospel_12_8 | A_Aprime / ABA / intro_A_fill_A_out / A_outro / AABA / two_arches | medium hall + low-shelf boost + air shelf |
+| **M2 Hip-hop** | boom-bap, head-nod, dusty | 70-94 | aeolian / dorian / phrygian / jazz_minor | boom_bap_60 / dilla_feel / mpc60_swing | AB_simple / ABAB / theme_var / AABA / ABCA | short room + tape high-cut + light drive |
+| **M3 Downtempo** | meditative groove, off-beat-comfortable | 90-105 | ionian / aeolian / dorian / lydian / jazz_minor | neo_soul / mpc60_swing / dilla_feel / straight_4_4 | through_composed / A_Aprime / theme_var / ostinato_layer / two_arches | wide chorus + dotted-eighth delay + warm room |
+| **M4 Latin** | percussive, dance-leaning, modal | 92-112 | ionian / phrygian / mixolydian / aeolian | latin_clave_pocket / dembow_pocket / mpc60_swing | ABAB / AABA / ABCA / theme_var | dry room + presence shelf |
+| **M5 Synthwave** | nostalgic glow, neon dusk | 100-120 | ionian / aeolian / lydian | synthwave_tight / straight_4_4 | ABAB / A_build_drop_A / AABA / ABCA / late_drop | chorus + dotted-eighth delay + plate |
+| **M6 House** | groove pump, club-shaped | 120-128 | ionian / aeolian / mixolydian | house_pocket / amapiano_pocket / straight_4_4 | ABAB / ABCA / breakdown_form / late_drop / riser_drop_loop | glue compressor → tight room |
+| **M7 Techno** | hypnotic loop, dark drive | 128-138 | aeolian / phrygian / dorian | techno_push / straight_4_4 | breakdown_form / riser_drop_loop / late_drop / pyramid / pulse_only | short room + light delay + dark high-shelf |
+| **M8 DnB** | snappy break, half-time-feel possible | 85 / 130 / 170-176 | aeolian / dorian / phrygian | dnb_amen_lean / straight_4_4 | ABAB / A_build_drop_A / riser_drop_loop / late_drop | snappy comp + tight room |
+| **M9 Glitch / IDM** | broken grid, dissonance-friendly | 90-135 | dorian / phrygian / aeolian / locrian | trap_triplet_hat / straight_4_4 | theme_var / two_arches / pyramid / medley | phaser + ping-pong delay + small room |
+| **M10 Cinematic** | breath, build, score-like | 54-110 | aeolian / dorian / lydian / phrygian | straight_4_4 / gospel_12_8 / ambient_drift | ABA / intro_A_fill_A_out / AABA / ABCA / two_arches / plateau_fall | large hall + sub shelf + air shelf |
+| **M11 Lofi** | vinyl warmth, jazzy | 70-92 | ionian / aeolian / dorian / jazz_minor / lydian | dilla_feel / boom_bap_60 / mpc60_swing / neo_soul | A_Aprime / ABA / theme_var / ostinato_layer / AABA | tape sat + high-cut + slow chorus + small room |
+| **M12 Chillout** | smooth, ambient-leaning, minor-key-comfort | 80-100 | ionian / lydian / aeolian / dorian | ambient_drift / neo_soul / straight_4_4 | through_composed / A_Aprime / ABA / theme_var | wide chorus + 0.45 s delay + plate + air shelf |
+| **M13 Simple** | stripped, song-shape, kid-piano | 70-110 | ionian / aeolian | straight_4_4 | A_Aprime / ABA / AABA / pulse_only | barely-there room |
+| **M14 Gameboy** | chiptune approximation (LSDj-flavor) | 110-150 | ionian / aeolian / dorian / mixolydian | straight_4_4 | ABAB / AABA / ABCA / ABA / pyramid | dark high-shelf cut + light drive + tiny room |
+
+## Per-mood layer programs (from `_GM_PALETTE`)
+
+| Mood | bass | comp | lead candidates | pad |
+|---|---|---|---|---|
+| M0 Ambient | 32 (Acoustic Bass) | 88 / 89 / 91 (pads) | 54 / 75 / 73 / 91 / 11 / 70 | 88 / 89 / 94 |
+| M1 Ballad | 32 / 33 | 0 (Piano) / 4 (EP1) / 24 (Nylon) | 73 (Flute) / 71 (Clarinet) / 56 (Trumpet) / 68 (Oboe) / 41 (Viola) / 11 (Vibes) | 89 / 91 / 95 |
+| M2 Hip-hop | 33 / 34 / 36 | 4 / 5 / 11 | 80 / 81 / 28 / 4 / 5 / 6 | 89 / 95 / 91 |
+| M3 Downtempo | 33 / 36 | 4 / 5 / 88 / 89 | 80 / 73 / 78 / 4 / 5 / 11 | 89 / 91 / 94 |
+| M4 Latin | 32 / 35 | 24 / 25 / 32 (steel-string family) | 56 / 11 / 24 / 73 / 12 / 25 | 89 / 91 / 94 |
+| M5 Synthwave | 38 / 39 / 33 | 81 / 89 / 80 | 81 / 80 / 84 / 87 / 88 / 89 | 90 / 89 / 94 |
+| M6 House | 38 / 39 / 36 | 16 / 17 / 81 (organ + lead) | 80 / 81 / 53 / 87 / 89 / 84 | 90 / 89 / 95 |
+| M7 Techno | 38 / 39 | 81 / 89 / 90 | 80 / 81 / 87 / 88 / 89 / 90 | 90 / 94 / 89 |
+| M8 DnB | 38 / 39 / 36 | 89 / 88 / 91 | 81 / 80 / 88 / 84 / 90 / 87 | 89 / 91 / 94 |
+| M9 Glitch | 38 / 39 / 87 | 90 / 91 / 102 | 88 / 81 / 102 / 87 / 100 / 99 | 95 / 91 / 94 |
+| M10 Cinematic | 32 / 43 (cello) / 44 (tremolo strings) | 48 / 49 / 50 / 89 (string ensembles) | 60 (French Horn) / 73 / 71 / 11 / 49 / 91 | 49 / 51 / 94 |
+| M11 Lofi | 33 / 32 / 35 | 4 / 5 / 0 / 24 (Rhodes / EP / Piano / Nylon) | 4 / 5 / 11 / 73 / 71 / 26 (Jazz Guitar) | 89 / 91 / 94 |
+| M12 Chillout | 32 / 33 / 38 | 88 / 89 / 91 / 4 | 73 / 71 / 75 / 91 / 89 / 11 | 89 / 91 / 95 |
+| M13 Simple | 32 / 33 | 0 (Piano) / 4 / 24 | 0 / 73 / 11 / 24 / 71 / 25 | 89 / 88 |
+| M14 Gameboy | 38 / 39 / 80 | 80 / 81 / 71 (Square / Saw / Clarinet-triangle) | 80 / 81 / 88 / 84 / 99 / 38 | 90 / 88 / 95 |
+
+GM program references: 0 piano, 4 EP1, 11 vibes, 24 nylon, 32 acoustic bass, 33 fingered bass, 38 synth bass 1, 39 synth bass 2, 49/50 strings, 80 square lead, 81 saw lead, 88-95 pads.
+
+## Drum kits per mood
+
+| Mood | Eligible kits |
+|---|---|
+| M0 Ambient | acoustic-studio / brushes / lo-fi-tape / hand-perc / mallets / music-box-tick / kalimba-tick |
+| M1 Ballad | acoustic-studio / brushes / jazz-kit / mallets / music-box-tick |
+| M2 Hip-hop | trap-808 / lo-fi-tape |
+| M3 Downtempo | jazz-kit / lo-fi-tape / hand-perc / latin-conga / kalimba-tick |
+| M4 Latin | hand-perc / latin-conga |
+| M5 Synthwave | acoustic-studio / house-909 |
+| M6 House | house-909 |
+| M7 Techno | house-909 |
+| M8 DnB | trap-808 / dnb-breakbeat |
+| M9 Glitch | dnb-breakbeat |
+| M10 Cinematic | acoustic-studio / brushes / jazz-kit / hand-perc / mallets / latin-conga / music-box-tick / kalimba-tick |
+| M11 Lofi | (inherits from M0/M2 fallbacks — no exclusive kit yet) |
+| M12 Chillout | (inherits from M0 fallbacks) |
+| M13 Simple | (inherits — minimal_pad activation matrix often silences drums) |
+| M14 Gameboy | (inherits — GM doesn't have a true chip drum kit; uses house-909 as closest) |
+
+## Listening notes
+
+- **M5 Synthwave** scores lower than its "feel" suggests because the GM saw lead at low velocity in MS-Basic SF3 sounds thin. The arrangement is correct — the soundfont ceiling shows up here.
+- **M9 Glitch** is intentionally sharp (DIN sharpness ~1.9 acum across the corpus) — that's the genre.
+- **M0 Ambient** outputs land 90% mid-band (4% low / 1% high) on the heuristic. Genre-correct: ambient is mid-range pad music. The heuristic doesn't penalize this any more (relaxed `<8% in any band` rule).
+- **M14 Gameboy** is the closest GM patches can get to chiptune. The square+saw+clarinet trio is a deliberate approximation; a true chiptune pass would need a custom synth or a chip-specific soundfont.
+- **M2 Hip-hop + jazz_minor** is musically valid (jazz hip-hop crossover) but scores lower because trap-808 + jazz-minor melody is a less-conventional combo than M2 + dorian.
+
+The mood ↔ score correlation isn't strong: a mood's *intent* is more about timbre and arrangement than any single quality number.

songhash-0.1.0/BYTES.md

@@ -0,0 +1,112 @@
+# Byte budget — mhash v1
+
+How the SHA-256's 32 bytes (after HKDF expansion) map to musical decisions.
+
+## Macro stream (`HKDF-Expand(prk, "soundhash/v1/macro", 32)`)
+
+| Byte | Decision | Filter chain | Table size |
+|---|---|---|---|
+| 0 | macro mood | family-of-MIME → 4 candidates | 4 of 15 |
+| 1 | mood sub-flavor (4 shades: stock/brighter/darker/tighter) | mood | 4 |
+| 2 | tempo | mood's `tempo_pool` | 5–8 BPMs |
+| 3 | key root | uniform 0–11 | 12 |
+| 4 | mode | mood's `modes` list | 2–5 |
+| 5 | groove template | mood's `_MOOD_GROOVE_POOL` | 1–4 |
+| 6 | form | tempo-tier × `_MOOD_FORM_PREF` | 4–7 |
+| 7 | progression | mood-tag ∩ mode | 2–10 |
+| 8 | voicing style | progression's `allowed_voicing_styles` | 1–5 of 10 |
+| 9 | drum kit | mood-filtered | 1–6 of 12 |
+| 10 | drum pattern (low + high nibbles) | kit + density 1-2 / 3-4 | 8 each |
+| 11 | drum fill | kit's fill bank | 4–5 / kit |
+| 12 | drum escalation algo (high) + de-escalation (low) | always | 8 each (2 implemented) |
+| 13 | bass archetype | mood ∩ time-sig | 2–8 |
+| 14 | bass synth + octave | mood ∩ pattern_compat | 1–4 |
+| 15 | comp role | mood | 1–6 of 12 |
+| 16 | comp synth | role-compatible × mood | 1–6 of 16 |
+| 17 | comp pattern variant | role × mood | 6–11 |
+| 18 | melody scale subset | mode | 1–8 |
+| 19 | melody motif rhythm | time-sig × mood | 32 / 4-4 |
+| 20 | melody contour | mood | 7–32 of 32 |
+| 21 | melody phrase shape | always | 16 (recorded on SongSpec; render-side hook reserved) |
+| 22 | melody tessitura + lead synth | mood | 5–8 leads / mood |
+| 23 | aux-layer mask + counter mode | always | counter mode = 4 |
+| 24 | energy curve | form × `_MOOD_CURVE_PREF` | 3–7 of 16 |
+| 25 | layer activation matrix | form-compatible × lead-audible | 3–10 of 16 |
+| 26 | per-bar mutation seed | per-bar HKDF spillover | n/a |
+| 27 | humanization profile (vel-jitter scale) | always | 6 |
+| 28 | FX preset (per-mood chain in `render/fx.py`) | mood | n/a |
+| 29 | FX wet-level scale (dry/85%/normal/wet) | always | 4 |
+| 30 | mix balance preset (CC7 per layer) | always | 4 |
+| 31 | counter-mode (low 2 bits) + variation salt | always | counter mode = 4 |
+
+## Per-bar / per-section sub-streams
+
+Spillover over the 32-byte macro budget; consumed via separate HKDF labels.
+
+| Label | Length | Consumer |
+|---|---|---|
+| `perbar/melody/<i>` | 4 B / bar | melody mutation (transpose / invert) per bar |
+| `perbar/bass/<i>` | 2 B / bar | bass octave shift, skip-last, ghost-first |
+| `perbar/comp/<i>` | 2 B / bar | comp drop-last, ±5 vel pull |
+| `perbar/aux/<i>` | 4 B / bar | layer dropouts (drums/lead/comp/pad) |
+| `form/section/<letter>` | 4 B / section | section-specific motif/contour/comp pattern |
+| `aux/earcandy/main/<i>` | 4 B / bar | ear-candy stab positions per bar |
+| `expression/velocity/L<n>` | 256 B / layer | per-note velocity jitter |
+| `melody/accent_skeleton` | 5 B | song-wide accent skeleton + 4 strong-beat targets |
+| `meter/timesig` | 1 B | time-signature pick (94% bias to 4/4, else mood's `time_sigs` ∩ {3/4, 6/8, 12/8}) |
+
+## Dimension → byte mapping
+
+A given musical dimension's primary entropy:
+
+| Dim | Bytes | Helper |
+|---|---|---|
+| 01 Key & Mode | 3, 4 | `_pick_mode` |
+| 02 Tempo & Groove | 2, 5 | `_pick_tempo`, `_pick_groove_template` |
+| 03 Form & Energy | 6, 24, 25 | `_pick_form_unconstrained`, `_pick_energy_curve`, `_pick_activation_matrix` |
+| 04 Harmony & Voicing | 7, 8 | `_pick_progression`, voicing style |
+| 05 Drums & Fills | 9, 10, 11, 12 | `_pick_drum_kit`, `_pick_drum_pattern_pair`, `_pick_drum_fill` |
+| 06 Bass | 13, 14 | `_pick_bass_pattern`, `_pick_bass_synth` |
+| 07 Comping | 15, 16, 17 | `_pick_comp_role`, `_pick_comp_synth`, `_pick_comp_pattern`, `_pick_arp_shape` |
+| 08 Melody | 18, 19, 20, 22, `melody/accent_skeleton` | `_pick_melody_motif`, `_pick_contour`, `_pick_scale_subset`, accent skeleton |
+| 09 Aux Layers | 23 | drone enable, counter mode, ear-candy gate |
+| 10 MIDI Expression | 27 (reserved) | velocity jitter via per-layer HKDF |
+| 11 MIME → Mood | 0 + MIME family | `_pick_mood`, `family_for_mime` |
+| 12 Rendering | 28, 29, 30 (reserved) | per-mood FX in `render/fx.py` |
+| 13 Hash Architecture | n/a | HKDF labels in `assets/v1/labels.json` |
+| 14 Perceptual & Determinism | n/a | LUFS, FX-after-LUFS, peak limit, pyloudnorm |
+
+## Empirical distributions (500-hash audit, mixed MIME)
+
+```
+mood:     M0 52, M1 34, M2 21, M3 48, M4 18, M5 11, M6 14, M7 9,
+          M8 14, M9 20, M10 39, M11 51, M12 46, M13 78, M14 45
+modes:    aeolian 164, ionian 126, dorian 84, lydian 47, phrygian 33,
+          jazz_minor 32, locrian 7, mixolydian 7
+keys:     33–55 hits per chromatic root (uniform within ~±20%)
+voicing:  close_triad 53, open_triad 48, sus_open 37, quartal 27,
+          power 17, drop2_7th 8, shell 5, drop3_7th 2, rootless_B 2,
+          rootless_A 1
+groove:   straight_4_4 30%, neo_soul 16%, ambient_drift 8%, dilla_feel 6%,
+          mpc60_swing 5%, gospel_12_8 5%, others <5% each
+counter:  parallel_3rd / parallel_6th / contrary / octave_below
+          (uniform on byte 31's low 2 bits)
+matrix:   arp_lead, 4floor_house, bass_lead_duo, band_basic, band_full,
+          bolero_additive, ambient_drone, staccato_stab, pad_lead,
+          minimal_pad — 10 of 16 reachable (lead-silent matrices filtered)
+```
+
+## Reserved bytes (all consumed)
+
+Every macro byte 0..31 now drives at least one observable decision (recorded on SongSpec or directly affecting render). Byte 21's `phrase_shape_id` is surfaced on SongSpec but not yet consulted at render time — render uses form-driven section letters for phrase structure today.
+
+**#84** Meter is now hash-driven via the dedicated `meter/timesig` HKDF label:
+- 4/4 stays the overwhelming default (~94% of hashes overall, ~98% in
+  4/4-only moods like M2/M5/M11/M13/M14, ~6% odd-meter in opt-in moods like
+  M0/M1/M4/M9/M10/M12).
+- Render is fully parameterized on `spec.time_sig` already; pattern banks
+  filter by `valid_time_sigs`/`time_sigs` and fall back to 4/4 when a meter
+  has no matching pattern in a given bank.
+- Swing remains carried by `groove_template_id` (the groove-template's
+  per-step PPQ offsets are the actual swing implementation); no separate
+  `swing` enum byte is consumed.

songhash-0.1.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to the mhash project. Format: reverse chronological, grouped by milestone.
+
+## v0.0.1 — initial scaffold + research
+
+- Repo scaffold: pyproject, src/mhash skeleton, asset stubs.
+- 14 dimensions of research under `research/<NN-slug>/`.
+- 58 curated JSON tables under `assets/v1/`.
+- Decoder skeleton consumes 32-byte HKDF macro stream.
+- DESIGN.md, README.md, MIME family resolver, soundfont bootstrap.
+
+## v0.1.0 — first PyPI release
+
+- Bumped version to 0.1.0; added MIT LICENSE.
+- Filled in PyPI metadata: authors, license, classifiers, project URLs,
+  keywords, full README rendering.
+- Wheel build: pure-Python `py3-none-any` (~144 KB). Asset bundle ships
+  inside the wheel as `mhash/_assets/v1/...`; SoundFonts are
+  excluded and downloaded on first run.
+- All asset-loading modules (`tables`, `mime`, `render.audio`,
+  `setup_assets`) check the dev path first and fall back to the wheel
+  layout, so `pip install mhash` works the same as `-e .`.
+- `dev` extra now pulls `build` + `twine` for release tooling.
+- Self-test SHA unchanged; 23/23 fast tests green on the wheel.
+
+## Meter flexibility (post-M2)
+
+- New HKDF label `meter/timesig` drives `time_sig` from a dedicated 1-byte
+  spillover. ~94% of hashes still land on 4/4; ~6% of opt-in moods land on
+  3/4, 6/8, or 12/8 (drawn from each mood's `time_sigs` list).
+- Self-test seed unchanged (byte = 147, below the 240 threshold).
+- 7/8 and 5/4 declared by some moods but held back until drum/comp/motif
+  banks have coverage; falls back to 4/4 transparently.
+
+## Milestone 2 — vertical slice
+
+- 9-layer MIDI render: drums, bass, comp, lead, pad, counter, drone, riser, ear-candy.
+- WAV render via `fluidsynth -ni` shell-out + MS-Basic.sf3 SoundFont.
+- LUFS norm to -16 / true-peak limit / cosine fades.
+- Per-mood pedalboard FX chains (reverb / delay / chorus / phaser / EQ).
+- 11-mood showcase generator (`python -m mhash.showcase`) + browser HTML.
+- MP3 + FLAC export.
+- Heuristic (LUFS / crest / spectrum / width) + mosqito psychoacoustic scoring.
+- 4 new moods added per user feedback: M11 lofi, M12 chillout, M13 simple, M14 gameboy.
+
+## Adversarial-review batch
+
+5 parallel reviewers (codex + gemini × 5 areas: implementation, sound design, musical spectrum, quality measurement, dimensions audit) flagged 18 P0/P1/P2 items.
+
+### P0 — correctness bugs
+- Reorder `_postprocess_wav`: FX → LUFS → fades → peak limit (was LUFS-before-FX, so the -16 LUFS contract was a lie).
+- Clear `_GROOVE_CACHE` per-render (asymmetric leak vs. `_VEL_JITTER_CACHE`).
+- `_lead_octave(spec)` actually used by `_counter_track` (was hardcoding 72).
+- Dropped duplicate `counter_program` assignment.
+- Empty-progression infinite-loop guard.
+
+### P1 — spec gaps
+- **Accent skeleton wired** (highest-distinguishability-per-byte feature). HKDF byte from `melody/accent_skeleton` picks 4 strong-beat chord-tone targets weighted [R 35%, 3 30%, 5 25%, 7 10%] + a 3-value micro_shape applied to weak slots.
+- **Layer activation matrix** (byte 25) consumed; 16 matrices on disk filtered to 10 lead-audible ones.
+- **Voicing style** (byte 8) with 10 implementations: close_triad / open_triad / sus_open / quartal / power / shell / drop2_7th / drop3_7th / rootless_A / rootless_B.
+- Mood family rebalance (no mood in >5 family slots; M4/M8 raised from 1 → 3 each).
+- M11–M14 progressions explicitly tagged (39 progressions tagged, was 0).
+- Triage metrics added: `level_range_db`, `loop_repetition`, `low_band_side_width`.
+
+### P2 — polish
+- Counter-melody now has 4 modes (parallel_3rd / parallel_6th / contrary / octave_below).
+- Bass + comp register guards (comp.top ≤ lead.median - 5).
+- Drum escalation algos picked from byte 12 (2 of 8 implemented in render: `linear_add`, `ghost_note_stack`).
+- Locrian + jazz_minor reachable; sub-60 BPM for M0/M10.
+- Label registry test un-skipped; 2 live unregistered labels added.
+
+### Sound-design adversarial pass
+- MIME resolver promoted from top-level stub to exact → prefix → fallback against `mime_families.json`.
+- Master EQ retargeted at MS-Basic SF3's actual problem bands (200-400 Hz mud, 2.5-4.5 kHz plastic).
+- Dropped GM 82 Calliope + GM 87 from inappropriate slots; M2 counter de-aliased from comp.
+- M6 chain reordered so reverb tails don't pump.
+- Lead palettes expanded 3 → 5-8 candidates per mood for "main voice variety".
+
+## Reserved-byte wiring (post-review)
+
+After P-stack closed, all remaining "reserved/unused" macro bytes were wired:
+
+- **byte 1** — 4 mood sub-flavors (stock / brighter / darker / tighter), each tweaks tempo and lead octave.
+- **byte 27** — 6 humanization profiles scaling vel-jitter (machine / groove-tight / groove-loose / acoustic-lively / ballad-rubato / swing-jazz).
+- **byte 29** — 4 FX wet scales (0.6 / 0.9 / 1.0 / 1.15) multiplying any plugin `wet_level` / `mix` kwargs.
+- **byte 30** — 4 mix-balance presets (balanced / bass_forward / lead_forward / minimal) emitting per-layer CC7 channel volume.
+
+## Documentation
+
+- BYTES.md — full byte-by-byte map with filter chain, table size, empirical distributions.
+- DESIGN.md §13 — implementation status with 31/32 bytes wired, only #84 invasive deferred.
+- showcase/showcase.html — browser preview of 15-mood demo.
+
+## Late additions
+
+- **All 8 drum escalation algos** now render-active (linear_add, ghost_note_stack, subdivision_double, snare_roll_crescendo, tom_rollup, hat_density_ramp, polyrhythm_overlay, reverse_cymbal_sweep). Each picks deterministically from byte 12; render applies on rising-energy bars (Δ ≥ 0.08).
+- **`--self-test` CLI** subcommand: renders a fixed seed and verifies its MIDI SHA against a baseline. Catches accidental output drift from refactors / dep upgrades.
+
+## Known deferred work
+
+- **#84 time_sig + swing de-hardcode** — render currently assumes 4/4 in dozens of places (drum patterns 16-cell grid, comp chord_rhythm grid, melody motif `total_beats`). Multi-day rework.
+- **Phrase shape (byte 21)** — phrase_shapes.json on disk; phrase shape is implicit in motif `total_beats` for now.
+- **Cross-arch determinism** — host-bound to Apple Silicon + fluidsynth 2.5.4 + MS-Basic SF3. Docker canonical or per-arch wheel matrix is the next step.