feat(rivet): storyboard composition with flexible lengths and meters

Rivet 0.4.0 tells a motif as a story. A timeline of blocks with roles
(statement, answer, departure, return, rest) replaces tasks, pins and
branches. Rivet writes each block from a motif and joins the seams with
a cut, breath, pickup or approach.

- Motifs of 1-8 bars in a bin of 16; storyboards up to 32 bars.
- Meters 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 and 12/8 for import, writing,
  audition and export. Phrygian, harmonic minor and Mixolydian scales.
- Per-block options, Another take and Keep; templates for new boards.
- Editor rebuilt: motif bin, timeline, large piano roll, inspector,
  tabs for generation, harmony and sound roles, 32-step undo/redo.
- Sessions from 0.1-0.3 open as a storyboard from their source motif.

docs/rivet/implementation.md

@@ -1,54 +1,64 @@
-# Rivet 0.2 implementation plan
+# Rivet 0.4 implementation notes
 
 ## Musical intent
-Develop a producer's own motif through audible choices about recognition, space,
-contrast, and return. Offer three distinct compositional proposals rather than
-three randomly shifted versions. Emotional interpretation stays with the producer.
+Tell a producer's own motif as a story. The unit of work is a storyboard of
+blocks; each block has a role that says what it does for the story, and Rivet
+writes the notes for that role from the motif. Emotional interpretation stays
+with the producer.
 
-## Engine
-- Keep an exact opening quotation. Build subsequent two-bar sections as statement,
-  answer, departure, and return (four-bar phrases use statement and return).
-- Add tasks Develop, Answer, Make space, and Return. Generate a deterministic pool
-  using rhythmic displacement, fragmentation, call/response, sparse subtraction,
-  a later register peak, changed endings, and harmonic returns; remove duplicates
-  and choose three candidates by task fit and musical distance. Return fewer if
-  locks make three distinct outcomes impossible.
-- Preserve groove and contour independently. Per-note locks protect pitch, rhythm,
-  or every attribute. Locked events survive subtraction; rhythm locks keep exact
-  timing and duration. Global constraints and locks take precedence over transforms.
-- Optional harmony consists of bounded time regions with pitch-class masks and
-  bass pitch. Accept polyphonic MIDI without claiming chord-root detection. Also
-  provide editable per-bar chord progressions. Guide metrically strong notes and
-  ending targets using the actual harmony at that time. Open endings prefer an
-  available scale tone outside the ending chord; closed endings use chord tones.
-- Candidate generation changes note count, spacing, duration, and articulation
-  when constraints allow. Preserve recognizable fragments; avoid overlaps and
-  clipping MIDI values. Keep generated notes within two-bar section boundaries so
-  sections can be combined safely.
+## Model
+- **Meter.** One time signature per session: 2/4, 3/4, 4/4, 5/4, 6/8, 7/8 or
+  12/8. Bar length is `PPQ * 4 * beats / unit`. Compound meters (6/8, 12/8) pulse
+  in dotted quarters; strong positions, pickups and breaths use that pulse.
+- **Motif.** A monophonic phrase of 1–8 whole bars with per-note locks (whole
+  note, pitch, rhythm). The bin holds 16 motifs.
+- **Block.** Motif, role, 1–8 bars, the join into the next block, a take number,
+  up to three realized options, the chosen option, and a keep flag. A storyboard
+  holds 32 blocks and 32 bars.
+- **Roles.** Statement, Answer, Departure, Return and Rest. Each role ranks the
+  transformation families that suit it (statement: quote, displaced groove,
+  changed ending; answer: call/response, changed ending, held back; departure:
+  higher peak, displaced groove, fragment; return: familiar return, quote, room
+  to breathe). The quote is always in the pool, so a statement can play the
+  motif as written. Rest yields one silent option.
+- **Realizing a block.** The motif is tiled to the block length (notes crossing
+  the end are shortened, or dropped when rhythm-locked), then developed. The seed
+  mixes the session seed, the block's take and its position, so options are
+  deterministic and differ between blocks. Harmony is read at the block's
+  absolute position. The last sounding block follows the ending setting; other
+  statements prefer an open last note.
+- **Joins.** Applied when the storyboard is composed, never stored in options.
+  Breath ends the last note at least half a beat before the seam. Approach moves
+  the last note one scale step next to the following first note. Pickup writes
+  two half-beat notes in the last beat that move toward the following first note;
+  it is skipped when anchors occupy that beat. Defaults follow the roles: into a
+  departure a pickup, into a return an approach, around rests a cut, otherwise a
+  breath.
+- **Keep.** Kept blocks are not rewritten when settings, harmony or neighbours
+  change, unless their stored options no longer fit (for example after a meter
+  change).
 
-## Producer workflow
-Import motif -> choose identity/locks -> optionally import or enter harmony ->
-choose task -> audition alternatives -> pin two-bar sections -> export combined
-MIDI or accept a complete candidate. Retain accepted work during regeneration.
-Pins survive changes to task and seed, and clear when source or phrase length
-changes. Pinned material overrides regenerated sections. Reject unsafe seams
-rather than silently truncate a sustained note.
+## Editor
+Header (key, scale, meter, tempo, play, loop, undo/redo, export), motif bin,
+timeline with role-coloured blocks and clickable seams, one large roll (the
+storyboard, or the selected motif for lock editing), inspector (block or motif),
+and tabs for generation, harmony and sound roles. Edits are synchronous; file
+dialogs run on a worker. Undo keeps the last 32 session states in the editor;
+continuous drags and typing collapse into one step. While the storyboard plays,
+an edit queues the new composition for the next bar line.
 
-## Audition
-Keep the internal voice and add a MIDI output mode. Preview is explicitly started,
-optionally loops, and switches pending selections at the next two-bar boundary or
-current clip end. Stop, replacement, mode changes, reset, and state restoration
-release emitted notes. Host transport start never auto-starts audition. All clips,
-queues, scheduling, and MIDI event emission remain bounded and allocation-free
-on the audio thread. Validate FL Studio routing manually; retain MIDI file export
-as the reliable commit path. Native OS MIDI drag-out is outside this release.
+## Compatibility
+State version 4. Versions 1–3 are read leniently and upgraded: the source motif,
+a kept phrase and saved gestures enter the bin; an eight-bar phrase becomes an
+arc, a four-bar phrase statement and return. Branch history is dropped. Future
+versions are rejected without changing the current session. The CLAP ID and the
+`story-session-v1` host field are unchanged.
 
-## Compatibility and verification
-Write state version 2; migrate version-1 JSON and host fields with serde defaults,
-retain legacy strategy names for old candidates, and keep the persisted host field
-identifier. New controls/harmony/pins/audition choices persist. Test timing, locks,
-contour, harmonic targets, candidate diversity, section composition, migration,
-loop boundaries, sample-accurate note events, queued switches, and RT allocation.
-Run existing core/ABI tests and Clippy, render the updated editor, and package
-Windows CLAP plus Linux CLAP/standalone. Do not claim Devath-derived algorithms or
-FL Studio validation without direct evidence.
+## Verification
+Core tests cover role options and diversity, locks, a fully locked motif,
+harmony and endings, all meters, keys and lengths, templates, limits, joins,
+kept blocks, compound meters, motif removal, and v1/v3 migration. MIDI tests
+cover time signatures and compound-meter round trips. App tests cover queued
+switches at the meter's bar line. The CLAP ABI test restores a 6/8 storyboard
+session through host state. FL Studio routing and musical usefulness still need
+checks in the host (see [FL Studio](fl-studio.md)).