musa-dsl 0.43.1 → 0.47.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4255273d1d071bd791ad11b5da8cd3e452442c2ec5bc78aed0f594968589a79
-  data.tar.gz: 8814fbd0fa803dd30f1aaad76a0b4843f008065db1533bef87872fccf1cf8e9c
+  metadata.gz: f8a1f6bc6c231c4b43a8ad4dcfe5db56a0da9de25de6392cc077dba95dc41648
+  data.tar.gz: a725d6365bcb16d52dd86de6c6d64d56f72e4eab197d8129fdfd1125570a9212
 SHA512:
-  metadata.gz: 61b3eb793d334844822636e2d8597c86dee2f353170d215328bf6dfc1be4aa24fdbe96c830584de377d99472d2259ef75a804f3c564fa5785f2430a14c1805a2
-  data.tar.gz: 7616c2dd4e24bf46714a64d48690d81989fa8ed41d99972f7c0aa2164607c8e72bf7fcd57b20963eed38d56420e889cd3421135d79df11d35464f2b2b1637005
+  metadata.gz: 2219dc7c259c72a81f8b1a14640313af2537dcb47d24746b8f17c3221df1ff49c34551e520873d4102df32c9a2429939b08c4c3f5f2b6a75d8258e2e062e28b0
+  data.tar.gz: 8f77c647934c2024b75529feb983cb45c2ad45e1d5083279f339133cd65c5eb057ca0033c60cdae992408d4a58b704cc6f5a067953b5cade6726f72312327e90

data/README.md

@@ -23,7 +23,7 @@ Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby
 - **Transport & Timing** - Multiple clock sources (internal, MIDI, external) with microsecond precision
 - **Audio Engine Independent** - Works with any MIDI-capable, OSC-capable or any other output hardware or software system
 - **Series-Based Composition** - Flexible sequence generators for pitches, rhythms, dynamics, and any musical parameter
-- **Generative Tools** - Markov chains, combinatorial variations (Variatio), rule-based production systems (Rules), formal grammars (GenerativeGrammar), and genetic algorithms (Darwin)
+- **Generative Tools** - Markov chains, combinatorial variations (Variatio), formal grammars (GenerativeGrammar), and genetic algorithms (Darwin)
 - **Matrix Operations** - Mathematical transformations for musical structures
 - **Scale System** - Comprehensive support for scales, tuning systems, and chord structures
 - **Neumalang Notation** - Intuitive text-based and customizable musical (or sound) notation
@@ -39,7 +39,7 @@ Musa-DSL is a programming language DSL (Domain-Specific Language) based on Ruby
 - [Non-commercial use](https://www.jetbrains.com/non-commercial/) — for learning, hobbies, open-source, content creation
 - [Students](https://www.jetbrains.com/academy/student-pack/) and [Teachers/Researchers](https://www.jetbrains.com/academy/teacher-pack/) — with institutional email
 
-VSCode with the Ruby LSP extension also works well, though Ruby autocomplete and hover documentation are less complete.
+[VSCode](https://code.visualstudio.com/) with the Ruby LSP extension also works well, though Ruby autocomplete and hover documentation are less complete.
 
 ### Framework Installation
 
@@ -58,24 +58,19 @@ gem install musa-dsl
 **Requirements:**
 - Ruby ~> 3.4
 
-## Quick Start
+## Examples
 
-A complete working example with multiple interacting voice lines, demonstrating sequencer DSL, timing control, and shared state.
+Two complete, runnable examples included here. Pedagogical learning is covered separately in the [musadsl-demo](https://github.com/javier-sy/musadsl-demo) repository.
 
-**📖 [Complete Quick Start Guide](docs/getting-started/quick-start.md)**
-
-## Tutorial
-
-Detailed tutorial showing the Neuma notation system for composing melodies with grade-based notation.
-
-**📖 [Complete Tutorial](docs/getting-started/tutorial.md)**
+- **[Sequencer DSL with interacting voices](docs/examples/sequencer-dsl-voices.md)** — multiple voice lines coordinated through shared state, demonstrating the sequencer DSL and timing primitives.
+- **[Neuma notation](docs/examples/neuma-notation.md)** — composing melodies with grade-based Neuma notation and the parser.
 
 ## Demo Projects
 
 A collection of 22+ working demo projects covering the full spectrum of Musa DSL capabilities:
 
 - **Basic concepts**: Setup, series, neumas, canon
-- **Generative tools**: Markov chains, Variatio, Darwin, Grammar, Rules, Matrix
+- **Generative tools**: Markov chains, Variatio, Darwin, Grammar, Matrix
 - **DAW integration**: MIDI sync, live coding, clock modes
 - **External protocols**: OSC with SuperCollider and Max/MSP
 - **Advanced patterns**: Event architecture, parameter automation, multi-phase compositions
@@ -84,12 +79,10 @@ Each demo is a complete, runnable project with documentation explaining the conc
 
 **📦 [musadsl-demo Repository](https://github.com/javier-sy/musadsl-demo)**
 
-## System Architecture
+## MusaDSL Ecosystem
 
 MusaDSL is a comprehensive ecosystem consisting of a core framework (musa-dsl) and associated projects for communication, development, and integration.
 
-### MusaDSL Ecosystem
-
 **Core Framework:**
 - [**musa-dsl**](https://github.com/javier-sy/musa-dsl) - Main DSL framework for algorithmic composition and musical thinking
 
@@ -99,159 +92,37 @@ MusaDSL is a comprehensive ecosystem consisting of a core framework (musa-dsl) a
 - [**midi-communications**](https://github.com/javier-sy/midi-communications) - Cross-platform MIDI I/O abstraction layer
 - [**midi-communications-macos**](https://github.com/javier-sy/midi-communications-macos) - macOS-specific MIDI native implementation
 
-### musa-dsl Internal Architecture
-
-The musa-dsl framework is organized in modular layers:
-
-#### 1. Foundation Layer
-- **core-ext** - Ruby core extensions (refinements for enhanced syntax)
-- **logger** - Structured logging system with severity levels
-
-#### 2. Temporal & Scheduling Layer
-- **sequencer** - Event scheduling engine with microsecond precision
-  - Tick-based (quantized) and tickless (continuous) timing modes
-  - Series playback with automatic duration management
-  - Support for polyrhythms and polytemporal structures
-- **transport** - High-level playback control with clock synchronization
-  - BPM management and tempo changes
-  - Start/stop/pause/continue controls
-  - Multiple clock source support (internal, MIDI, external)
-
-#### 3. Notation & Parsing Layer
-- **neumas** - Text-based musical notation system
-- **neumalang** - Parser and interpreter for neuma notation with DSL support
-
-#### 4. Generation & Transformation Layer
-- **series** - Lazy sequence generators with functional operations
-  - Map, filter, transpose, repeat, and combination operations
-  - Infinite and finite series support
-- **generative** - Algorithmic composition tools
-  - **Markov chains**: Probabilistic sequence generation
-  - **Variatio**: Cartesian product parameter variations
-  - **Rules**: L-system-like production systems with growth/pruning
-  - **GenerativeGrammar**: Formal grammar-based generation
-  - **Darwin**: Genetic algorithms for evolutionary composition
-- **matrix** - Matrix operations for musical gestures
-  - Matrix-to-P (point sequence) conversion
-  - Gesture condensation and transformation
-
-#### 5. Output & Communication Layer
-- **transcription** - Musical event transformation system
-  - Ornament expansion (trills, mordents, turns)
-  - GDV to MIDI/MusicXML conversion
-  - Dynamic articulation rendering
-- **musicxml** - MusicXML score generation
-  - Multi-part score creation
-  - Notation directives (dynamics, tempo, articulations)
-  - Standard MusicXML 3.0 output
-- **midi** - MIDI voice management
-  - Polyphonic voice allocation
-  - Channel management
-  - Note-on/note-off scheduling
-
-#### 6. Musical Knowledge Layer
-- **music** - Scales, tuning systems, intervals, and chord structures
-  - Equal temperament and just intonation support
-  - Modal scales (major, minor, chromatic, etc.)
-  - Chord definitions and harmonic analysis
-- **datasets** - Musical data structures (GDV, PDV, Score)
-  - GDV (Grade-Duration-Velocity): Scale-relative representation
-  - PDV (Pitch-Duration-Velocity): Absolute pitch representation
-  - Score: Timeline-based multi-track composition structure
-
-#### 7. Development & Interaction Layer
-- **repl** - Interactive Read-Eval-Print Loop for live composition
-
-## Core Subsystems
-
-### MIDI - Voice Management & Recording
-
-Polyphonic voice management for MIDI output with automatic note tracking, and MIDI input recording with precise timestamping.
-
-**📖 [Complete Documentation](docs/subsystems/midi.md)**
-
-### Sequencer - Temporal Engine
-
-Event scheduling engine with musical time (bars/beats), precise tick-based timing, and DSL for temporal composition.
-
-**📖 [Complete Documentation](docs/subsystems/sequencer.md)**
-
-### Transport - Timing & Clocks
-
-Comprehensive timing infrastructure connecting clock sources to the sequencer. Supports multiple clock types (TimerClock, InputMidiClock, ExternalTickClock, DummyClock) and manages playback lifecycle with precise timing control.
-
-**📖 [Complete Transport Documentation](docs/subsystems/transport.md)**
-
-
-### Series - Sequence Generators
-
-Lazy functional sequence generators with map/filter operations, numeric generators, buffering, quantization, and timed merging.
-
-**📖 [Complete Documentation](docs/subsystems/series.md)**
-
-### Neumas & Neumalang - Musical Notation
-
-Compact text-based musical notation system with parser for converting notation to structured musical data.
-
-**📖 [Complete Documentation](docs/subsystems/neumas.md)**
-
-### Datasets - Sonic Data Structures
-
-Type-safe musical event representations (GDV, PDV, PS, P, V) with conversions, validation, Score container, and advanced queries.
-
-**📖 [Complete Documentation](docs/subsystems/datasets.md)**
-
-### Matrix - Sonic Gesture Conversion
-
-Convert matrix representations to point sequences for sequencer playback, treating sonic gestures as geometric objects.
-
-**📖 [Complete Documentation](docs/subsystems/matrix.md)**
-
-### Transcription - MIDI & MusicXML Output
-
-Convert between representations with ornament expansion for MIDI or preservation as notation symbols for MusicXML.
-
-**📖 [Complete Documentation](docs/subsystems/transcription.md)**
-
-### Music - Scales & Chords
-
-Comprehensive scale and chord systems with equal temperament, custom tunings, chord navigation, and extensible definitions.
-
-**📖 [Complete Documentation](docs/subsystems/music.md)**
-
-### Generative - Algorithmic Composition
-
-Algorithmic composition tools: Markov chains, Variatio, Rules (L-systems), GenerativeGrammar, and Darwin (genetic algorithms).
-
-**📖 [Complete Documentation](docs/subsystems/generative.md)**
-
-### MusicXML Builder - Music Notation Export
-
-Comprehensive MusicXML score generation with hierarchical structure, multiple voices, articulations, and dynamics.
-
-**📖 [Complete Documentation](docs/subsystems/musicxml-builder.md)**
-
-### REPL - Live Coding Infrastructure
+## MusaDSL Architecture
 
-TCP-based server for live coding — real-time code evaluation and error handling. Consumed by external REPL clients (editor extensions, custom evaluators).
+The musa-dsl framework is organized in modular layers. Each component has its own detailed documentation.
 
-**📖 [Complete Documentation](docs/subsystems/repl.md)**
+### 1. Foundation Layer
+- [**core-ext**](docs/subsystems/core-extensions.md) - Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges, DeepCopy, DynamicProxy, AttributeBuilder.
+- **logger** - Structured logging system with severity levels.
 
-### Core Extensions - Advanced Metaprogramming
+### 2. Temporal & Scheduling Layer
+- [**sequencer**](docs/subsystems/sequencer.md) - Event scheduling engine with musical time (bars/beats), microsecond-precise tick-based timing, and a DSL for temporal composition. Tick-based (quantized) and tickless (continuous) modes; series playback with automatic duration management; polyrhythms and polytemporal structures.
+- [**transport**](docs/subsystems/transport.md) - Comprehensive timing infrastructure connecting clock sources to the sequencer. Supports multiple clock types (TimerClock, InputMidiClock, ExternalTickClock, DummyClock), BPM management, tempo changes, and the start/stop/pause/continue playback lifecycle.
 
-Ruby refinements and metaprogramming utilities: Arrayfy, Hashify, ExplodeRanges, DeepCopy, DynamicProxy, AttributeBuilder, Logger.
+### 3. Notation & Parsing Layer
+- [**neumas + neumalang**](docs/subsystems/neumas.md) - Compact text-based musical notation system with parser and interpreter for converting notation to structured musical data, with DSL support.
 
-**📖 [Complete Documentation](docs/subsystems/core-extensions.md)**
+### 4. Generation & Transformation Layer
+- [**series**](docs/subsystems/series.md) - Lazy functional sequence generators with map/filter operations, numeric generators, buffering, quantization, and timed merging. Transpose, repeat, and combination operations; infinite and finite series support.
+- [**generative**](docs/subsystems/generative.md) - Algorithmic composition tools: Markov chains (probabilistic sequence generation), Variatio (Cartesian product parameter variations), GenerativeGrammar (formal grammar-based generation), and Darwin (genetic algorithms for evolutionary composition).
+- [**matrix**](docs/subsystems/matrix.md) - Matrix operations for musical gestures: matrix-to-P (point sequence) conversion for sequencer playback, gesture condensation and transformation. Treats sonic gestures as geometric objects.
 
-## More from the MusaDSL ecosystem
+### 5. Output & Communication Layer
+- [**transcription**](docs/subsystems/transcription.md) - Musical event transformation system with ornament expansion (trills, mordents, turns), GDV to MIDI/MusicXML conversion, and dynamic articulation rendering. Expansion for MIDI or preservation as notation symbols for MusicXML.
+- [**musicxml**](docs/subsystems/musicxml-builder.md) - MusicXML score generation. Hierarchical structure, multiple voices, multi-part scores, articulations, dynamics, tempo, and notation directives. Standard MusicXML 3.0 output.
+- [**midi**](docs/subsystems/midi.md) - MIDI voice management with polyphonic voice allocation, channel management, note-on/note-off scheduling, automatic note tracking, and MIDI input recording with precise timestamping.
 
-- [MusaDSL](https://musadsl.yeste.studio) — Ruby framework for algorithmic sound and musical composition.
-- [MusaLCE](https://musalce.yeste.studio) — live coding environment for Ableton Live and Bitwig Studio.
-- [Nota](https://nota.yeste.studio) — Claude Code plugin for AI-assisted MusaDSL composition.
-- **Pulso** — Stream Deck plugin for MusaLCE Surface controls *(upcoming)*.
-- **VST3 plugins** — collection of audio plugins for mixing and mastering *(upcoming)*.
+### 6. Musical Knowledge Layer
+- [**music**](docs/subsystems/music.md) - Scales, tuning systems, intervals, and chord structures. Equal temperament and just intonation support; modal scales (major, minor, chromatic, etc.); chord definitions, harmonic analysis, and chord navigation.
+- [**datasets**](docs/subsystems/datasets.md) - Type-safe musical event representations: GDV (Grade-Duration-Velocity, scale-relative), PDV (Pitch-Duration-Velocity, absolute), PS, P, V. Conversions, validation, Score container (timeline-based multi-track composition), and advanced queries.
 
-For the full map — descriptions, how they relate, which one to pick for what — see [musa-ecosystem.yeste.studio](https://musa-ecosystem.yeste.studio).
+### 7. Development & Interaction Layer
+- [**repl**](docs/subsystems/repl.md) - Interactive Read-Eval-Print Loop for live composition. TCP-based server for real-time code evaluation and error handling. Consumed by external REPL clients (editor extensions, custom evaluators).
 
 ## Author
 

data/docs/README.md

@@ -5,9 +5,10 @@ Complete documentation for the Musa DSL framework for algorithmic sound and musi
 ## 📚 Documentation Structure
 
 ### Getting Started
-- **[Installation](../README.md#installation)** - Set up Musa DSL
-- **[Quick Start](../README.md#quick-start)** - 5-minute introduction
-- **[Not So Quick Start](../README.md#not-so-quick-start)** - Comprehensive tutorial
+- **[Installation](../README.md#getting-started)** - Set up Musa DSL
+- **[Examples](../README.md#examples)** - Two runnable examples:
+  - [Sequencer DSL with interacting voices](examples/sequencer-dsl-voices.md)
+  - [Neuma notation](examples/neuma-notation.md)
 
 ### Core Subsystems
 
@@ -39,8 +40,8 @@ For users extending the DSL or integrating deeply:
 ## 🎯 Learning Paths
 
 ### New to Musa DSL?
-1. Start with [Quick Start](../README.md#quick-start)
-2. Read [System Architecture](../README.md#system-architecture)
+1. Start with one of the [Examples](../README.md#examples)
+2. Read [MusaDSL Architecture](../README.md#musadsl-architecture)
 3. Explore subsystems in this order:
    - [MIDI](subsystems/midi.md) - Output basics
    - [Sequencer](subsystems/sequencer.md) - Temporal control

data/docs/api-reference.md

@@ -82,5 +82,5 @@ yard stats --list-undoc
 ## See Also
 
 - **Conceptual Documentation**: [subsystems/](subsystems/) - Guides and tutorials for each subsystem
-- **Getting Started**: [getting-started/](getting-started/) - Quick start and tutorials
+- **Examples**: [examples/](examples/) - Runnable code examples
 - **Main Documentation**: [README.md](README.md) - Documentation hub

data/docs/{getting-started/tutorial.md → examples/neuma-notation.md}

@@ -1,6 +1,6 @@
-# Tutorial: Not So Quick Start
+# Neuma notation
 
-Here's a more detailed example showing the Neuma notation system:
+A more detailed example showing the Neuma notation system:
 
 ```ruby
 require 'musa-dsl'
@@ -20,7 +20,10 @@ decoder = Decoders::NeumaDecoder.new(
 
 # Define a melody using neuma notation with duration and velocity
 # Format: (grade duration velocity)
-# Durations: 1/4 = quarter, 1/2 = half, 1 = whole
+# Durations are multiples of base_duration, which here is 1r -- a bar. So the
+# numbers below are fractions of a bar: 1/4 of a bar, 1/2 of a bar, a whole
+# bar. In 4/4 those are a quarter, a half and a whole note; in another meter
+# they are not, because a bar and a whole note are only the same in 4/4.
 # Velocities: pp, p, mp, mf, f, ff
 melody = "(0 1/4 p) (+2 1/4 mp) (+2 1/4 mf) (-1 1/2 f) " \
          "(0 1/4 mf) (+4 1/4 mp) (+5 1/2 f) (+7 1/4 ff) " \

data/docs/{getting-started/quick-start.md → examples/sequencer-dsl-voices.md}

@@ -1,6 +1,6 @@
-# Quick Start
+# Sequencer DSL with interacting voices
 
-Here's a complete example showcasing the sequencer DSL with multiple melodic lines that interact with each other:
+A complete example showcasing the sequencer DSL with multiple melodic lines that interact with each other:
 
 ```ruby
 require 'musa-dsl'

data/docs/idioms.md

@@ -0,0 +1,326 @@
+# Idioms — choosing the MusaDSL form
+
+Every entry below names a **reflex**: something a competent programmer writes
+when they have not yet asked what MusaDSL calls it. The reflex always works.
+That is the problem — it produces code that runs, sounds right, passes every
+test, and is foreign to the framework.
+
+This document is the answer to one question, asked at the moment of writing:
+
+> *What I have to do here — how would it be expressed most beautifully in
+> MusaDSL?*
+
+It is organised by **the shape of the data and of the problem**, not by
+subsystem, because the shape is what you can see when you are about to make the
+mistake. The subsystem is what you can only see afterwards.
+
+Read it from the symptom.
+
+---
+
+## The root principle
+
+> **The shape of the data decides the idiom.**
+
+The generalist reflex is not committed when the loop is written. It is committed
+earlier, when the plan is modelled. Hold absolute positions and a loop of `at`
+is already inevitable; hold durations and `play` is already natural. No guard
+placed later can rescue a plan modelled in the wrong coordinates.
+
+Two corollaries used throughout this document:
+
+- **Model plans as durations, not as positions.**
+- **Keep the musical layer musical**: grades, proportional durations and
+  dynamic marks travel as far as the sink; pitches, seconds and integers appear
+  only where the sound is actually produced.
+
+---
+
+## 1. Events placed in time
+
+**Reflex** — precompute absolute positions, then iterate:
+
+```ruby
+plan.each_with_index do |(start, duration), i|
+  at 1 + start do ... end
+end
+```
+
+**Idiom** — a serie whose elements carry `duration:` (and, when the sounding
+length differs from the step, `note_duration:` and `forward_duration:`),
+consumed by `play`, which walks time itself:
+
+```ruby
+play plan_serie do |duration:, order:, ...|
+  ...
+end
+```
+
+**What is gained** — the plan stays *data*: sliceable (`.cut`, `.max_size`),
+composable (`MERGE`, `H`, `HC`), reusable across voices (`.buffered`). Temporal
+arithmetic disappears from the code. And `play` returns a control, so the ending
+is a handle (`control.after { ... }`) instead of a computed final position.
+
+**Detectable** — `at` inside `each`/`times`/`while`, or `at` whose position
+contains a loop variable.
+
+**When the reflex is right** — a genuine one-off landmark: the start, a single
+structural mark, the end.
+
+---
+
+## 2. Sequences of anything
+
+**Reflex** — an array, iterated, indexed, or consumed with `.next_value` by
+hand.
+
+**Idiom** — `S(...)` and the operations: `.map`, `.select`, `.remove`,
+`.reverse`, `.shift`, `.randomize`, `.repeat`, `.max_size`, `.cut`, `.with`,
+`MERGE`, `H`/`HC`. Numeric contours have constructors of their own: `FOR`,
+`SIN`, `FIBO`, `HARMO`, `RND`.
+
+**What is gained** — laziness (infinite generators, no cost until consumed) and
+composition (a complex line is an expression, not a built list). The
+prototype/instance split (`.i`) lets the same definition be read independently
+by several voices; `.buffered` + `.buffer.i` lets them read the *same* progress
+at different speeds, which is what a canon is.
+
+**Detectable** — `.i.to_a` followed by Array operations followed by `S(*...)`.
+
+**When the reflex is right** — materialising a finite, already-computed plan
+into `S(*plan)` is legitimate: generators feed series. The smell is when every
+intermediate step was expressible as a serie operation.
+
+---
+
+## 3. Pitch
+
+**Reflex** — arithmetic on MIDI note numbers: `pitch + 7`, `% 12`, a table of
+semitones, an array called `pitches`.
+
+**Idiom** — `scale[grade]`, `note.at_octave`, `.sharp` / `.flat`, `chord_on`,
+`chord.with_quality` / `.with_move`, `chord.search_in_scales`,
+`scale.degree_of_chord`.
+
+**What is gained** — this is not decoration. A piece written in MIDI integers is
+welded to one tuning and one tonic; written in grades, transposing, modulating
+or re-temperament is *rebinding the scale*. And the material stays navigable:
+you can ask a chord for its degree, a scale for its chords.
+
+**Detectable** — literals in the 48–84 range combined with `+`/`-`/`% 12`.
+
+---
+
+## 4. Layers: musical intent vs. realization
+
+**Reflex** — compute MIDI pitches and durations in seconds where the material is
+defined.
+
+**Idiom** — GDV (grade, duration as a multiple of `base_duration`, velocity as a
+dynamic mark) all the way to the edge; `to_pdv(scale)` and the conversion to
+seconds only in the sink.
+
+**What is gained** — the same material renders to MIDI, to a synthesis server or
+to MusicXML by changing the sink, not the piece.
+
+**Detectable** — `60.0 / bpm`, `* beat` or integer velocities appearing in the
+*material* (constants, series, plans) rather than in the block that finally
+emits sound. Converting inside the emitting call is correct and is not a smell.
+
+---
+
+## 5. Recurrences and hand-made state
+
+**Reflex** — `a, b = b, a + b`, accumulators inside `loop`, a small class whose
+core is a recurrence.
+
+**Idiom** — `FIBO(first, second)`, whose seeds are its first two values, so
+`FIBO(1, 2)` and `FIBO(2, 1)` are relatives of Fibonacci and not delayed echoes
+of it; `E(*seeds) { |last_value:, caller:| ... }` when the recurrence is not
+Fibonacci at all (`caller.parameters` carries the state); `.repeat` for cycles.
+
+**What is gained** — the recurrence becomes a serie, so it composes with
+everything else: `.map`, `.select`, feeding `play` directly.
+
+**Detectable** — the swap `a, b = b, a + b` is a literal grep.
+
+**When the reflex is right** — when the object needs to be *inspected*, not just
+consumed. A serie is a flow: you cannot ask it for its period, its reachable
+states or its cycle. A grid that must answer "when does my state repeat?" is a
+domain object and deserves a class. What is never right is writing the
+recurrence four times instead of extracting it.
+
+---
+
+## 6. Randomness
+
+**Reflex** — `rand` with a ladder of `if p < 0.3`.
+
+**Idiom** — `RND(values, random: Random.new(seed))` — a *shuffle*: each value is
+drawn once and the serie ends. `.repeat` reshuffles on every pass and is what
+gives a die. Constrained with
+`.remove { |value, history| ... }`; Markov when the tendency has memory. Note
+that `Markov` **is a serie** — it can feed `play` directly and be chained with
+`.map`.
+
+**What is gained** — reproducibility (an explicit seed makes the piece the same
+piece), tendencies as a *mutable table* (blend two tables to evolve behaviour
+while the chain keeps its state), and constraints declared rather than filtered
+ad hoc.
+
+**Detectable** — `rand` not derived from a seeded `Random`; thresholds in a
+chain of `if`.
+
+---
+
+## 7. Combinatorics and search
+
+**Reflex** — nested loops, `Array#product`, `permutation` followed by filters.
+
+**Idiom** — **Variatio** (fields + `constructor`, re-constrained at runtime with
+`.on()`), **GenerativeGrammar** (`|` alternative, `+` sequence, `.repeat`,
+`.limit`), **Darwin** (score candidates by measures and weights, select the
+fittest).
+
+**What is gained** — the exploration space becomes an object: re-restrictable,
+filterable, and prunable *during* growth instead of generate-then-filter. The
+constraints are declared where they are conceived.
+
+**Detectable** — `product` / `permutation` / `combination`, or three nested
+loops filling an array of candidates.
+
+---
+
+## 8. Musical material as text
+
+**Reflex** — literal arrays of `{ grade:, duration:, velocity: }`.
+
+**Idiom** — neumas: `'(0 1 mf) (+2 1/2 f tr)'.to_neumas`, `|` for polyphony,
+`.neu` files.
+
+**What is gained** — material readable *as a score*, relative encoding
+(invariant under transposition), access to ornaments, and the route to MusicXML.
+
+**Detectable** — hash literals with those three keys, repeated.
+
+---
+
+## 9. Articulation and ornament
+
+**Reflex** — schedule a grace note plus the real note; multiply a duration by
+`0.5` for staccato.
+
+**Idiom** — a `Transcriptor` with the appropriate transcription set; the
+distinction between `duration`, `note_duration` and `forward_duration`.
+
+**What is gained** — articulation as annotation instead of arithmetic, and the
+same GDV rendering expanded MIDI or symbolic MusicXML by changing the set.
+
+**Detectable** — `* 0.5` on durations; pairs of notes with a small fixed offset.
+
+---
+
+## 10. Parameters that change over time
+
+**Reflex** — `every` plus a variable nudged towards a target.
+
+**Idiom** — `move from:, to:, duration:, every:, function:` (scalar and hash
+forms); `SIN()` for cyclic contours; `.quantize` for stepped output.
+
+**What is gained** — the *shape* (a proc from `[0..1]` to `[0..1]`) is separated
+from the *clock*, so one movement can rise and fall, and the shape can be
+reasoned about, plotted and reused.
+
+**Detectable** — `every` whose body mutates a variable towards a target.
+
+---
+
+## 11. Several layers of events in time
+
+**Reflex** — arrays of `[time, ...]` sorted and traversed with indices.
+
+**Idiom** — AbsTimed series and `TIMED_UNION` (array and hash forms),
+`.flatten_timed`, `.compact_timed`, consumed with `play_timed`, whose block
+receives `time:` and `started_ago:`.
+
+**What is gained** — merging layers becomes algebra, with components addressable
+by name.
+
+**Detectable** — `sort_by { |e| e[:time] }` followed by pointer traversal.
+
+---
+
+## 12. Macro form
+
+**Reflex** — constants chained by addition (`SECTION_2 = SECTION_1 + LENGTH`),
+boolean flags, a counter deciding what happens.
+
+**Idiom** — `on` / `launch` for sections; `control.after` for natural
+completion; `control.on_stop` for cleanup; `every` with `duration:`, `till:` or
+`condition:`.
+
+**What is gained** — form as a graph of events rather than arithmetic; material
+recalculated at each entry rather than precomputed; and the distinction between
+*finishing* and *being stopped*, which position arithmetic cannot express at
+all. `after` fires only on natural completion — never rely on it for cleanup.
+
+**Detectable** — position constants defined in terms of other position
+constants.
+
+---
+
+## 13. Multiparametric gesture
+
+**Reflex** — tables of parameters traversed by loops.
+
+**Idiom** — `Matrix#to_p(time_dimension:)` → `to_ps_serie` / `to_timed_serie` →
+`play_timed`; `condensed_matrices` for the reduction.
+
+**What is gained** — a trajectory drawn in several dimensions at once becomes a
+single object, interpolated and consumed as one gesture.
+
+**Detectable** — low. This is territory for *suggestion*, not for lint: the
+user will rarely ask for it by name. When someone describes "a trajectory that
+is drawn", the matrix is the honest answer.
+
+---
+
+## 14. Event lists for querying or export
+
+**Reflex** — hand-rolled arrays of events, then hand-rolled queries over them.
+
+**Idiom** — `Datasets::Score` (`at`, `between`, `changes_between`, `subset`,
+`values_of`) and the MusicXML builder.
+
+**What is gained** — the piece becomes queryable, and exportable, without a
+second representation.
+
+---
+
+## 15. Clocks
+
+**Reflex** — always the real clock, even for tests and offline rendering.
+
+**Idiom** — `DummyClock` for tests and fast rendering, `ExternalTickClock` when
+another source owns time, tickless mode when events are not on a grid,
+`change_position_to` to jump.
+
+**What is gained** — a piece that can be rendered faster than real time, and
+tested at all.
+
+---
+
+## Using this document
+
+For each layer or material of a piece, before writing code, name:
+
+1. **the shape of the data** — serie? neumas? generator output? timed serie? a
+   class of its own, and if so why the framework does not have it;
+2. **the verb that consumes it** — `play`, `play_timed`, `move`, `every`,
+   `on` + `launch`, `at`;
+3. **why not the neighbouring verb**.
+
+`at` with a computed position, and a bespoke class, are the two answers that
+always require an explicit justification. Neither is forbidden — sometimes a
+class modelling an inspectable structure *is* the honest answer. What is not
+acceptable is that the choice was never argued against the framework.