Cleanup

docs/composer/evaluation_contract.md

@@ -1,20 +1,15 @@
-# One musical evaluator
+# Authoritative action evaluation
 
-`scoring.evaluate` returns `Evaluation(version='phrase-musical-1')`: validity, raw values, enabled weights, weighted contributions, total, and exact-event normalization counts. The selected phrase score is exactly its reported total. Selection additionally reports the bounded next-phrase total; it is not disguised as the local score.
+`selection.Selector.evaluate` returns `Evaluation(version='action-selection-1')`: raw normalized values, enabled weights, exact rational contributions, total and denominators. Ranking uses exactly the sum of reported contributions. Tied continuations merge before evaluation; repeated attacks remain distinct.
 
-Lookahead averages the current normalized phrase score and the best feasible following phrase score. Candidate phrases can have different durations. This is a bounded, variable-horizon heuristic, not equal-duration whole-chorus optimization or a proven remaining-cost bound. Both local and lookahead totals appear in the decision trace so this limitation is inspectable.
+The scope is one complete musical action, not a chorus. Alternatives compete by cost per exact quarter; compound routes remain indivisible. Prefix and reporting-phrase totals sum local decisions. They are diagnostics, not global objectives or partition-invariant phrase quality scores. Computational partitioning that preserves the action objects does not change evaluation. Changing musical action boundaries can change the local search objective.
 
-| Contribution | Weight | Interpretation |
-|---|---:|---|
-| Purpose | 2 | Unprepared large motion, repeated oscillation and preparation of the chosen destination |
-| Continuity | 2 | Incoming musical connection beyond a comfortable interval |
-| Repetition | 1 | Recent complete rhythmic/interval figure overuse; deliberate return receives bounded allowance |
-| Register | 1 | Duration-normalized excursions beyond the role's broad comfortable region |
+Fixed priors address excessive leaps, register distance outside a soft corridor, oscillation, repeated attacks, unprepared space, repeated rests, source interval relationships, actual theme relationships, sustained chord-tone arrivals and directed steps. Shared integer coefficients can distinguish action kind, duration, chord-relative pitch role, incoming interval, relative metric position, motion direction, register band, source rhythm, realized theme evidence and context of silence. Title, filename, absolute bar index, reference hash and event lookups are not allowed features.
 
-These are contextual preferences, not a perceptual memorability model. Broad acceptability can produce equal musical totals. A stable role-specific choice key breaks those ties. Guitar travel is absent from this total: it chooses a fingering for the selected music rather than giving an easier but otherwise unrelated tune an automatic advantage.
+Silence has no pitch/register value. A rest after an arrival differs from an interruption or repeated rest. A sustain is one attack with its complete duration. Approved expression is validated by contract rather than automatically rewarded or penalized as chromatic.
 
-Harmonic validity, complete typed resolutions, exact duration, promised held destinations, rhythmic-group integrity, physical range and arrangement allocation are checked independently. Approved expression has no generic chromatic penalty or reward. Active empty candidates cannot pass; explicit no-harmony space can.
+Hard validity remains separate: mapped collections, typed exceptions, exact target register/time/duration, pending deadlines, rhythm groups, physical domain, monophony and source-derived allocation. Pending obligations filter the frontier before pruning. Final placement cannot change selected pitches or rhythm.
 
-Rests are constructed within groups, at entrances, or after destinations. There is no global attack-density/occupancy optimization. Holds count as one sounding event, regardless of tied notation fragments. A repeated attack does not fulfill a single committed sustain.
+The optional fitter uses an integer early-update structured perceptron, at most 200 passes. Coefficients are shared between songs within each role. Its checkpoint prefers fewer incorrect rollouts, then longer exact prefixes, then smaller coefficients. This differs from minimizing whole-output discrepancy; full export comparison remains the acceptance gate. Fitted artifacts stay under `build/` until a verified model is deliberately promoted. Constructibility alone is not grounds for promotion.
 
-Ordinary phrase endpoints may be mapped non-chord tones when the phrase remains open. Local settling, completion and handoff have actual timed destinations. Expression disabling reconstructs valid strict phrases; it does not delete notes from a chromatic winner.
+Synthetic tests check contribution sums, weight counterfactuals, tied-event invariance, forbidden feature names and a learnable two-choice fitting problem. They establish mechanics, not that this finite feature set expresses the four desired decisions or predicts musical preference.