## Problem/Motivation Plugin `weight` does two unrelated jobs: 1. Form, tab, and listing order. 2. Subscription scoring influence in `AiContextScopeResolver::calculateScopeScore()`. The scope reorder on #3586415+s showed why that is a problem. Moving Roles in the form silently changed which subscribed context items win: Context Tags (80) began outranking Entity Types (30), where before the reorder Entity Types (60) outranked Context Tags (40). Nobody asked for a ranking change. It was a side effect of a form layout change, and nothing in the code or the tests could have caught it. Three further problems surfaced while scoping the fix. **The scoring numbers were never designed as scoring numbers.** 100/90/80 down to 10 is an ordering ladder, where equal steps are meaningful because the values are positions. `calculateScopeScore()` uses the same value as a coefficient: it adds the weight to `$max_score` and adds `weight * match_ratio` to the score, then divides. The only absolute comparison anywhere in the pipeline is `> 0.0`; every other use is relative. So for scoring, only the *ratios* between weights matter, and equal increments produce uneven proportional gaps — the same step of 10 is 1.125x between Use Cases (90) and Context Tags (80) but 1.5x between Entity Types (30) and Taxonomy Terms (20). The most important distinction is the weakest. **Display weight runs backwards from Drupal's convention.** The attribute sorts descending (higher first), while Form API `#weight` and local task `weight` sort ascending. `AiContextScopeManager::getScopePluginDisplayWeights()` exists only to translate the plugin order into ascending `0, 1, 2…` indexes for forms and tabs. If we keep descending weights and add a `getDisplayWeight()` method, we end up with two different things called "display weight" that sort in opposite directions, which is worse than today's ambiguity. **We have no evidence for most of the current ranking.** The relative order of Context Tags, Entity Types, Site Sections, and Taxonomy Terms was never derived from anything. Restoring the pre-#3586415+s order would swap one invented ranking for another. ## Proposed resolution Split the two meanings into two attributes with two methods, each following the convention native to its job. Keep the six-group ladder and the Minimal ⊆ Relevant ⊆ Broad contract from #3586394+s unchanged, and do not change which scopes participate in scoring. ### Display weight — ordering, ascending Rename the attribute parameter `weight` to `display_weight` and `getWeight()` to `getDisplayWeight()`, and flip the direction so lower sorts first, matching Drupal everywhere else. Because the values then match `#weight` semantics directly, **`AiContextScopeManager::getScopePluginDisplayWeights()` can be deleted** rather than renamed. Forms and the local task deriver pass display weight straight through. This is safe because every non-scope sibling in those containers already sorts first: `context_scope` holds the Priority field at `-101` and the summary badges at `-99`, `scope_subscriptions` holds its summary elements at an implicit `0`, and `ai_context.settings.scope_tab` has no children other than the scope derivatives. The constraint that follows is that **display weights must stay positive**. `compareScopePluginOrder()` flips from `$b <=> $a` to `$a <=> $b`, with the plugin ID tie-break unchanged. ### Scoring weight — magnitude, higher is stronger Add an optional attribute `scoring_weight` and a method `getSubscriptionScoringWeight()`. This is a coefficient, not a position, so there is no ascending convention to match; bigger means more influence. The existing rule that values below 1 are treated as 1 during scoring carries over to this value. Display weight keeps no floor, since it is only an ordering position. **`scoring_weight` must not fall back to display weight.** That fallback made sense when both ran descending; now it would invert. A custom scope with `display_weight: 15` wanting to sit near the top would get the weakest possible influence, and a scope that sets nothing would inherit the default display weight of 100 and silently become the most influential scope in the system. The default is instead the existing `MIN_SUBSCRIPTION_SCORING_WEIGHT` of 1, so an unset custom scope is deliberately negligible and the docs tell subscribable custom scopes to set it explicitly. ### Built-in values | Scope | Display (ascending) | Scoring (magnitude) | |---|---|---| | Global | 10 | n/a (own group) | | Use Cases | 20 | 100 | | Context Tags | 30 | 50 | | Roles | 40 | n/a (hard filter only) | | Languages | 50 | n/a (hard filter + situational match) | | Site Sections | 60 | 50 | | Entity Types | 70 | 50 | | Taxonomy Terms | 80 | 50 | | Specific Entities | 90 | n/a (exact-match) | Display order is unchanged from #3586415+s. Steps of 10 leave room between every pair for custom scopes, and 45 is the slot between the agent-facing scopes and the page-derived ones (replacing the old "60 is left free" guidance). The default `display_weight` is 100, so a custom scope that sets nothing sorts last. ### Why those scoring numbers Only one distinction is made, because it is the only one the module's own architecture supports. **Use Cases is weighted double the topical scopes** because it is the one dimension where both sides deliberately opted in — an operator declared the agent's purpose and an editor tagged the item for that purpose — and because subscription scoring is its only influence on selection. **Languages does not participate at all.** #3586448+s resolved this by removing the capability rather than halving the weight. Language detection never fails, so a language subscription could only re-rank items that already matched the request language or were already hard-rejected — it rewards a restriction. There is no 25 tier and no Languages row to weight. **Context Tags, Entity Types, Site Sections, and Taxonomy Terms are tied** because they are all topical proximity measured from different angles and there is no evidence for ranking them against each other. This resolves the original complaint by declining to order Context Tags against Entity Types rather than by reversing them. Ties are safe: scoring weight is only ever a coefficient, nothing sorts by it, and when two items end up with equal scores the selector already falls back to `compareSelectionPreference()` — Priority descending, then shorter content, then highest ID. Every tie we create hands the decision to the Priority field a human set rather than to a number we invented. ### Per-site overrides (Advanced) Add an **Advanced** section to each scope's settings page exposing both numbers, so a site can reorder scope fields and retune ranking without writing code. `AiContextScopeSettingsFormBase` builds the section before delegating to `buildSettingsForm()`, so every scope gets it — including custom ones — with no plugin changes. Values live in the existing `ai_context.scope_settings.<plugin_id>` config object, and empty means "use the plugin's value". `getDisplayWeight()` and `getSubscriptionScoringWeight()` read config first and fall back to the attribute, which makes attribute values defaults rather than fixed points. Two prerequisites, both real work: - **A shared config schema type.** Each `ai_context.scope_settings.<id>` object declares its own hardcoded mapping today and there is no wildcard. Writing weight keys into a custom scope's config object would fail schema validation unless a shared base type exists that custom scope authors adopt. - **Cache invalidation on save.** The manager caches sorted plugin order and invalidates the `local_task` tag when definitions are cleared. A config-driven change needs equivalent invalidation or scope tabs and form order go stale. Validation: display weight must be a positive integer, so the Priority field at `-101` and the summary badges at `-99` keep sorting first. Scoring weight below 1 is floored to 1, matching the code path. **Known trade-off.** There is no ranking preview, so a site changing a scoring weight cannot see what it changed. Per-site values also mean future retuning of the built-in defaults will not reach sites that overrode them, and a stored 50 is indistinguishable from an inherited one. Score observability is listed as a follow-up. ## Remaining tasks - [x] Rename attribute `weight` to `display_weight`; flip to ascending; default 100 - [x] Rename `getWeight()` to `getDisplayWeight()` on the interface and base class - [x] Add attribute `scoring_weight` and `getSubscriptionScoringWeight()`, defaulting to 1 - [x] Flip `compareScopePluginOrder()` to ascending - [x] Delete `AiContextScopeManager::getScopePluginDisplayWeights()` and its callers in `AiContextItemForm`, `AiContextAgentForm`, and `AiContextScopeLocalTask` - [x] Rename the resolver's private `getSubscriptionScoringWeight()` helper (name now taken by the interface method) and point scoring at the new method - [x] Set built-in display and scoring values per the table - [x] Renumber the test-module scope plugins (currently 14–19) into the 81–89 range to keep their relative position - [x] Update `scope_api.md`, `custom_scopes.md`, `features/scopes.md`, `services.md`, and `context_selection.md`: two scales, opposite directions, form order is not ranking - [x] Add an `api-stability.md` "Beta upgrade" section and a release note covering the rename, the direction flip, and the ranking change - [x] Kernel coverage: a custom scope with display weight ≠ scoring weight - [x] Kernel coverage: tied scoring weights fall through to Priority ordering - [x] Add a shared config schema type for scope settings and move the nine existing objects onto it - [x] Add optional `display_weight` and `scoring_weight` to that schema - [x] Build the Advanced section in `AiContextScopeSettingsFormBase`, validating display weight as a positive integer - [x] Read config first and fall back to the attribute in both weight methods - [x] Invalidate cached plugin order and the `local_task` tag when scope settings are saved - [x] Functional coverage: a display weight override reorders the item form and the scope tabs - [x] Kernel coverage: a scoring weight override changes subscription ranking, and clearing it falls back to the attribute - [x] Document the Advanced section, and that attribute values are now defaults ## User interface changes An **Advanced** section is added to each scope settings page at `/admin/config/ai/context/settings/scope/<plugin_id>`, with optional display weight and scoring weight overrides. Defaults are unchanged, so scope form order, tab order, and listing order stay as they are unless a site overrides them. Which subscribed items rank highest does change — see API changes. ## API changes Yes, and breaking. No backward-compatibility wrappers, consistent with the other beta renames on `api-stability.md`. - The attribute parameter `weight` is removed. A custom plugin still passing it fails at plugin discovery with an unknown named parameter error, so the breakage is loud rather than silent. - `getWeight()` is removed from `AiContextScopeInterface`. - The plugin definition key becomes `display_weight`. This is the one silent path: a `hook_ai_context_scope_info_alter()` implementation setting `$definitions['x']['weight']` will quietly stop having any effect. Called out in the release note. - **The meaning of the number inverted.** A custom scope mechanically renaming `weight: 25` to `display_weight: 25` moves from near the bottom of the form to third from the top. The key rename forces the author to open the docs, but the release note must say the direction changed and not just the name. - `AiContextScopeManager::getScopePluginDisplayWeights()` is removed. The scope plugin manager is already documented as internal, so this needs no deprecation. - Ranking of subscribed items changes on existing sites. There is no config migration and none is possible. - Attribute values become defaults rather than fixed points. `ai_context.scope_settings.<id>` may now carry `display_weight` and `scoring_weight`, and config wins when set. Config schema changes: a shared type for scope settings, which custom scope config objects must adopt before they can store weight overrides. ## Data model changes None. ## Out of scope - Splitting `supportsSubscriptions()` into exact-match / situational-match capabilities (#3586419+s) - Changing the six-group merge order or moving subscriptions out of Minimal - Making Roles or Global participate in subscription scoring - Reverting the #3586415+s display order ## Follow-ups - **Resolved in #3586448+s.** Languages is now `supportsSubscriptions(): FALSE`, so it is absent from the scoring table above rather than weighted at 25. - Scoring weights are tuning values, not contract. Once there is real feedback on which scopes predict useful context, the tied 50s are the first thing to revisit. - **Score observability.** A per-scope contribution breakdown for a given agent would let a site evaluate a scoring weight change instead of guessing, and would also tell us whether the tied 50s are right. The Advanced section ships without it. ## AI disclosure - [x] AI assisted issue