product-vamp/docs/composer/active_path_audit.md

# Active production path audit

Baseline: revision `405066e` (`Revamp`), initially clean working tree. The immutable copy is `build/composer_repair/405066e/baseline/`; `baseline_inputs.json` records source/data and optional-reference hashes. These are evidence, not production inputs. The named ZIP archives and external remediation/comparison Markdown files were absent. The extracted source copies in `data/songs/` remain authoritative and unchanged.

Optional reference paths actually present:

- `build/all-of-me-solo-1.xml` — acoustic
- `build/all-of-me-solo-2.xml` — electric
- `build/autumn-leaves-solo-1.xml` — acoustic
- `build/autumn-leaves-solo-2.xml` — electric

No reference contents were inspected to author the production changes. Optional comparison commands run after generation, preserve raw XML, and explicitly apply the separately confirmed guitar-written octave convention. Source import keeps its own contract.

| Reported issue | Reproduction / earliest failing stage | Repair |
|---|---|---|
| Broad score overwritten | Confirmed: `checked_phrase` score replaced in `themes.phrase_candidates`; selection | One `MusicalEvaluation` supplies the actual score; no subsequent replacement or extra chorus transition cost |
| Density calculated but unused | Confirmed in removed `phrasing.evaluate`; selection | Active-span attack-range contribution in authoritative evaluator; sustains and planned space have separate intents |
| Absolute onset “rhythm diversity” | Confirmed in `themes.seeds`; retrieval | Duration/rest descriptors invariant under time translation |
| Chord tone at every internal endpoint | Confirmed in `unit_candidates`; construction and validity | Ordinary endpoints use mapped pitches; sustained notes and declared destinations retain their contracts |
| Every window sustained/closed | Confirmed; representation/construction | Open alternative; local settles are intermediate; cadential completions and source handoffs are terminal |
| Answer vocabulary unreachable | Confirmed: operation chooser omitted answer; construction | Data-defined chooser requests answer, extension, fragment, free continuation, development and return |
| Residual third/sixth-beat offsets | Reproduced from half-beat edits of triplet material; construction | Complete group checks; binary-only boundary alteration; complete displaced triplets preserved |
| Expressions after strict winner | Confirmed in `composer.compose`; construction | Typed alternatives and direct versions compete before phrase selection |
| Narrow starting/route choices | Confirmed: three first pitches, prefix of two paths, suffix of three; pruning | Whole-route actions, register representatives, named cutoff counts; no independently selected suffix |
| Source register / electric +12 | Confirmed in role data and `profiles.for_part`; construction | Soft overlapping role centers and phrase alternatives, all six strings |
| Role dependency / reference lookup | Not reproduced in baseline normal path | Existing independent process workers retained; runtime read boundary added |
| Overly full responsive accompaniment | Not reproduced in current production | Current source-only canonical sparse comping retained; no generated-solo response reintroduced |

## Before and after call graph

Both enter through `generator.__main__ → arrange.generate.generate_performance_scores → production.generate_tree → generate_role`. A spawn process pool already existed (default two workers). Roles use immutable original-song analysis and independently keyed policies/caches. Assembly applies source-defined role masks.

Previously the solo path was `composer.compose → leads.thematic_options → themes.phrase_candidates → unit_candidates → protected prefix + route suffix → checked_phrase → overwritten score → solo winner → expressions.refine`.

Now it is `composer.compose → leads.thematic_options → themes.phrase_candidates → whole joint unit_candidates → complete routes → provisional two-sided join alternatives / typed expression alternatives → checked_phrase → scoring.musical → phrase frontier → independent solo winner → validation → notation → assembly`. Source masks, vocal pickup, scales and physical checks are retained.

| Module/function | Live responsibility | Production inputs / budgets |
|---|---|---|
| `production.SourceAnalysis.read` | Canonical melody, harmony, exact meter/tempo/form | Original source only; corrected `meter` key to actual `time_signature` |
| `themes.seeds` | Source feature evidence throughout the head | Source notes, preferred feature roles; eight diverse seeds |
| `themes.rhythm_windows` / `patterns` | Complete rhythm alternatives and lawful transformations | Meter-filtered catalog, authored cells and difficulty; eight representatives |
| `themes.operation_choices` | Request development purposes | `grammar.operations`, actual home/incoming state |
| `themes.unit_candidates` | Complete joint actions | Actual incoming note, theme, destination, register; 16 jobs, eight retained gestures, deterministic retry |
| `routes.candidates` | Full octave-aware scale/chord route | Relative sequence catalog, chord traversal operators, exact sounding span; eight route representatives |
| `gesture_rhythm.join_variants` | Bounded edits across internal joins | Up to two beats on each side; eight legal alternatives; no protected hold consumed |
| `expressions.joint_candidates` | Approach/color/anticipation/suspension alternatives | Versioned rules; eight representatives per provisional phrase, with direct version retained |
| `realization.checked_phrase` | Identity, harmony, hold, placement, final evaluation | No optional reference inputs; one final evaluation result |
| `leads.thematic_options` | Bounded continuation across windows | Eight chorus alternatives; duration-weighted complete evaluations |
| `comping.Canonical` | Source-only reusable accompaniment | Written harmony/source rhythm/form, sparse voicing and comping resources |

`themes.prefix_paths`, `_prefix_paths`, and unused `instantiate` were removed. The old thematic `phrasing.evaluate` was removed. The generic cell/draft realizer and explicit `mode='paraphrase'` API remain compatibility/test/audition paths; ordinary production does not call them or silently fall back to them. Their existence is not claimed as a new production capability.

A further pruning defect appeared during the real-song build: the seed category combined treatment and form position. Its first layer could fill the entire budget with eight exact-interval references and discard rhythm/contour contracts. The corrected cutoff preserves treatment families first; a synthetic reachability regression covers this. Open windows now also request continuing rhythm, rather than using arrival rhythm simply because a computational window ends.

Profiling found repeated `diverse` ranking and interval-family classification among the major costs. Ranking is now decorated once per item and immutable path descriptors are memoized. A stable-order comparison test proves that the optimized cutoff preserves the old ordering for tied ranks; no larger beam or wall-clock-dependent choice was added.

## Baseline export correspondence

A fresh read of each preserved MusicXML export was compared with `playback.compile_timeline` of its saved role document (explicit guitar octave convention and merged sounding ties). All four matched exactly: All of Me acoustic 117 attacks, electric 121; Autumn Leaves acoustic 83, electric 110. Evidence is `baseline-export-proof.json`. This confirms the saved baseline's exported music; it is not a claim that XML formatting or those counts predict musical quality.