Save

docs/composer/evaluation_contract.md

@@ -0,0 +1,31 @@
+# Authoritative musical evaluation
+
+Normal thematic production uses `scoring.musical` and its immutable `MusicalEvaluation` result (`joint-musical-1`). `Phrase.score` is exactly `evaluation.total`. A complete solo is selected by the duration-weighted sum of those complete phrase evaluations. No later post-pass changes the winning notes or adds an undisclosed transition penalty.
+
+The result exposes validity, pending obligations, exact scope, raw values, denominators, weights, contributions, total and an error. Invalid harmony, identity, protected sounding tails, placement, or activity intent cannot be traded against a low cost. Identity is a contract, not two differently named resemblance rewards. Consequently the proposed redundant soft “theme” weight was not retained: fulfilled identity does not earn ever-increasing credit for copying more events.
+
+| Contribution | Initial weight | Meaning |
+|---|---:|---|
+| Rhythm | 3 | Internal isolated short events / interruptions and actual incoming connection; entrance/release are distinct |
+| Destination | 2 | Preparation of declared arrivals, including the final approach; no destination obligation at an ordinary frontier |
+| Harmony | 2 | Time-normalized unexplained exposure; validated typed treatments have their own hard checks |
+| Register | 1 | Soft overlapping role corridor, weighted by sounding duration |
+| Repetition | 1 | Bounded recent exact/relative figure and oscillation history; sustains are separate from attacks |
+| Activity | 1 | Configured broad activity range over active spans, excluding held-arrival/intentional-space demands |
+| Difficulty | 0.5 | Approximate time-aware fretboard travel, normalized by attacks |
+
+Weights reside in `data/composition/grammar.json`. These independently authored preferences are not fitted to optional targets and are not a model of aesthetic quality. Source time and chord semantics remain exact rational values. Floating-point arithmetic is confined to soft costs.
+
+Retrieval uses explicitly separate estimates to keep purposeful rhythmic, register and directional alternatives before expensive route/placement work. Unit and phrase frontiers use elapsed-duration rates when their coverage differs; only complete equal-span candidates enter the authoritative comparison. This is a bounded heuristic, not an admissible global-optimality proof. Cutoff counts are recorded under `selection_trace.operations` and `expression_operations`.
+
+Tie continuations merge before durations, attack count, harmonic exposure and evaluation. Repeated attacks remain separate. Empty active passages are invalid; intentional space has no fabricated pitch/register cost. Partial expressive gestures carry a pending contract until the actual target/hold is heard; a missing past event or expired deadline fails.
+
+`--trace-level full` preserves candidate evaluation tables and operation counts in `.roles` reports. Summary mode removes heavy candidate tables only; it does not change generation. Optional profiling reports are outside musical inputs. The report schema is `composer-report-2` and runtime score/notation schemas are unchanged.
+
+Tests: `tests/test_composer_repair.py`, existing sustained-note/quotation/placement/expression tests, and production score-equals-evaluation assertions. Selected and competing evaluation examples are exported in the release evidence; their aggregate scores establish explainable selection, not listener preference.
+
+Counterfactual fixtures cover every configured contribution, including nonzero rhythm interruption, destination approach and recent-pattern recurrence. Identity evidence is a hard treatment contract, not a second hidden cost. Exact sustained notes and tie-split versions return equal evaluations. Ordinary mapped nonmember notes may end an open computational unit; they do not acquire an accidental anchor requirement.
+
+The expressive toggle now means **exclude jointly composed expression candidates**. It can select a different valid complete phrase. It does not promise the decorated winner minus ornament notes. The exported `before_enclosure` stage preserves the selected phrase's actual strict provisional realization for a local controlled comparison; undecorated phrases retain their complete notes rather than becoming silent in that view.
+
+`Policy.weights` still belongs to the explicit legacy draft/paraphrase API and is not the active thematic evaluator's weight table. The normal score uses `data/composition/grammar.json → evaluation.weights`. The audit distinguishes those consumers; modifying a legacy-only weight is not claimed to affect the new production winner.