Update scoring graph descriptions to clarify use of WidgetMatcher

[smessie]

This pull request clarifies how widget selection, scoring, and acceptance are defined and processed. It introduces the concept of shui:WidgetMatcher as a generalization for both scoring and acceptance matchers, and updates function descriptions to consistently refer to this abstraction. The changes also refine the validation logic and improve terminology for better accuracy and clarity.
The term shui:WidgetMatcher was already introduced earlier, but I noticed it was not properly adopted throughout the scoring system.

Widget matcher generalization and documentation updates:

• Added a detailed explanation of shui:WidgetMatcher, which now serves as the base class for both shui:WidgetScore and shui:WidgetAcceptMatcher, and described how these are used to associate widgets with matching conditions and scoring/acceptance logic.
• Updated all relevant function descriptions (Select, Matcher, Score, and Accept) to consistently refer to the scoring graph as containing shui:WidgetMatcher instances, rather than just shui:WidgetScore. This clarifies that both scoring and acceptance matchers are involved in widget selection.

Validation and algorithmic clarifications:

• Improved the validation function to specify that the focus node must be a literal or a subject in the target graph, making the acceptance criteria more precise.

• Corrected the matcher and score function steps to use the correct matcher node (shui:WidgetMatcher), and clarified that the matcher function is called with the specific matcher instance, not just the accept matcher.

• See this document rendered online here

[smessie]

Extra comments to clarify remaining issues:

We did not fully complete the transition towards a separate shui:WidgetAcceptMatcher mechanism instead of using negative shui:WidgetScore instances.

As described in the OP above, I updated the text to support the case where both shui:WidgetScore and shui:WidgetAcceptMatcher instances reside in the scoring graph. These are now covered under the common shui:WidgetMatcher concept.

Remaining points:

• We still need the shui:WidgetAcceptMatcher instances to be defined in the Turtle files, replacing the current -1 score instances.

  • Do we need exactly one accept matcher per widget?
  • This could potentially be handled in a follow-up PR.

• In the Matcher Function, step 5, I believe the last input should be:

  scoring graph as shapes graph
  

  instead of:

  shapes graph as shapes graph
  

• The Select Function currently returns only a single result. However, we previously adjusted the other functions to take a best parameter, allowing callers to choose between:

  • only the best matching widget (best=true), or
  • all matching widgets (best=false).

  The Select Function should also accept this best parameter. When best=false, it should collect all matching widgets and return them as a list instead of returning only the first match.

[danielbeeke]

1. shui:WidgetAcceptMatcher
   1.1. Do we need exactly one accept matcher per widget? No not by spec, maybe an implementation would do it that way. But it should not be required.
   1.2. Do in follow up P-R? Sounds good to me
2. matcher function input
   2.1. About renaming shapes graph reference to scoring graph reference: I agree
3. The select function
   3.1. I went through the spec and think we are trying something like the following diagram.
   3.2. I think the score function can be used to pick up the list of widgets. No need from my perspective to add this to the select function.
   3.3. Also the text of the select function probably needs a line like: "If local state has a value for a selected preference widget return that selected preference widget IRI."

[danielbeeke]

See #994 (comment)