**PLEASE ONLY PICK THIS UP IF YOU CAN WORK ON THIS RIGHT AWAY** **THIS ISSUE BLOCKS #3586438+** ## Description Follow-up to #3586438+s, after the #3586419+s capability split. Languages was still `supportsSubscriptions(): TRUE` and `supportsSituationalMatch(): TRUE`. That double-counted a restriction: the hard filter already drops a known language mismatch, and situational-match already includes a match in Relevant+. Languages is different from Taxonomy, Entity Types, and Site Sections because its request-side value is never unknown. `AiContextLanguageService::detect()` always returns a langcode (URL prefix → same-site Referer → negotiated content language), so `matchesRequestContext()` is always TRUE or FALSE, never NULL. A language subscription cannot broaden reach; it only re-ranks. That matches the Roles rule from #3586415+s: a restriction is not an inclusion reason. This MR overrides `supportsSubscriptions()` to `FALSE` on the Languages plugin and keeps `supportsSituationalMatch(): TRUE` plus the hard filter. The built-in capability row is now `language => [FALSE, FALSE, TRUE]` — the first built-in that combines no-subscriptions with situational matching. Form hiding, the "do not allow subscriptions" note, the scoring skip, and #3586412+s save-time preservation of existing agent language subscriptions (dormant, not deleted) all follow from the capability. Stored values stay valid options, so #3586416+s leaves them alone unless the language itself is uninstalled. Closes #3586448 ## Change 1: the Minimal prefilter strip Flipping the capability was not enough for Minimal. `prefilterItemIdsByScope()` is also used for Global index lookup, so non-subscription scopes cannot be stripped inside that method. A language-only subscription then scored as match-all (`max_score` 0 → 1.0) and leaked language-indexed items into Minimal. The internal resolver now exposes `getParticipatingSubscriptions()`, which drops empty lists and scopes that are disabled, unavailable, or `supportsSubscriptions(): FALSE`. The selector and the budget calculator call it before prefilter / subscribed-ID resolution. After the strip, a language-only subscription looks like no subscriptions: global + exact-match only. The leak was never specific to Languages. Roles has never supported subscriptions either, so a stored roles subscription reached the Minimal prefilter the same way. The strip is capability-driven, so it fixes the whole family, and `testRolesSubscriptionDoesNotReachMinimal()` locks that in. ## Change 2: Specific Entities is availability-gated `calculateScopeScore()` carried a hardcoded skip list, `['global', 'entity_item', 'target_entity']`. Checking each entry: - `global` is unreachable there. The plugin manager instantiates every definition, so Global always takes the capability branch. - `target_entity` is stale. `ai_context_update_10015()` renames it to `entity_item` everywhere, including inside `ai_context.agents` `scope_subscriptions`, and the pre-rename plugin never supported subscriptions in any release. - `entity_item` was load-bearing. `ai_context_ai_context_scope_info_alter()` deleted its definition without `dynamic_entity_reference`, making Specific Entities the only built-in whose capability could not be read. A stored subscription under its ID scored at the minimum weight and diluted every other dimension: 90 / 91 instead of 90 / 90 for an otherwise perfect Use Case match. So the module gated two optional scopes two different ways: Languages stays defined and reports `isAvailable(): FALSE`, while Specific Entities removed itself from discovery. The plugin injects only core services, so nothing required that. `AiContextScopeEntityItem::isAvailable()` now reports whether DER is installed, the alter hook implementation is gone, and the skip list is gone. Both `calculateScopeScore()` and `getParticipatingSubscriptions()` are decided purely by capability, with no ID special cases. Because the settings tab is now reachable while the scope is unavailable, `validateSettingsForm()` no longer queries the `entity_items` field on sites that lack it. Without that guard, unchecking an allowed entity type throws `QueryException: 'entity_items' not found`. Audited every `getScopePlugins()` consumer before making the change: the item form, agent form, view builder, cleanup service, subscription form builder, and both exact-match iterations already gate on `isEnabledAndAvailable()`, and `loadEntityItemCandidateIds()` already guards on the field storage existing. The one consumer that does not gate is the local task deriver, so the visible change is a Specific Entities row with status **Unavailable** plus a reachable settings tab on non-DER sites — the same presentation Languages already has on a single-language site. ## Behavior that changes 1. **Minimal.** Language-only items are unreachable except via Always include. 2. **Ranking.** A language tag no longer lifts an item into the scope-scored group or outranks an untagged peer. 3. **Scope overview.** Non-DER sites show Specific Entities as Unavailable instead of omitting it. 4. **Scoring.** A hand-written `entity_item` subscription on a non-DER site no longer dilutes scores. ## Behavior that does not change - Item-side language tagging and the hard filter. - Situational inclusion in Relevant and Broad when the request language matches. - Availability: Languages is still hidden on monolingual sites, and Specific Entities is still absent from the item form without DER. - Matching, scoring, and forms for Specific Entities when DER is installed. ## Effect on #3586438+s This MR removes the Languages scoring weight question rather than answering it, so the weight-split proposal needs four edits, listed in full in the issue: the "uneven proportional gaps" example that uses Languages (whose `1.17x` / `1.5x` figures also predate #3586415+s), the `| Languages | 50 | 25 |` table row, the "weighted half the topical scopes" rationale plus the "only two distinctions" sentence, and the follow-up bullet that says to file this separately. Display weight 50 is unaffected — it still controls form and listing order. ## Testing instructions Full kernel suite from the project root (921 tests / 18617 assertions, passed): ``` ddev phpunit web/modules/contrib/ai_context/tests/src/Kernel/ ``` Functional tests — not run locally, no frontend test setup: ``` ddev phpunit web/modules/contrib/ai_context/tests/src/Functional/AiContextScopeAgentFormTest.php ddev phpunit web/modules/contrib/ai_context/tests/src/Functional/AiContextScopeContextItemFormTest.php ddev phpunit web/modules/contrib/ai_context/tests/src/Functional/AiContextUnavailableScopeFormTest.php ``` `./lint.sh` passes: cspell, phpcs, phpstan, stylelint, eslint. ### New or updated coverage - `testLanguageCapabilities()` and the capability matrix pin `language => [FALSE, FALSE, TRUE]`. - `testLanguageSubscriptionDoesNotReachMinimal()` fails without the participating-subscription strip. - `testRolesSubscriptionDoesNotReachMinimal()` fails the same way, proving the leak was not Languages-specific. - `testLanguageTagDoesNotOutrankUntaggedItem()` replaces an assertion that could not fail. Subscribing to the same language the item was tagged with scored 1.0 both before and after the flip; comparing a tagged item against a language-universal peer fails at 0.643 when `supportsSubscriptions()` returns TRUE. - `testCalculateScopeScoreIgnoresEntityItemWithoutDer()` fails at 90 / 91 without the capability check. - `testEntityItemAvailabilityFollowsDynamicEntityReference()` pins the definition being discovered and `isAvailable()` following DER. - `testEntityItemSettingsValidationSkipsMissingField()` errors with `QueryException` without the validate guard. - `testGetParticipatingSubscriptionsDropsDisabledScope()` and `testGetParticipatingSubscriptionsDropsNonSubscriptionScopes()` cover the disabled-scope branch and plugin-less custom keys. - `AiContextScopeManagerTest` updated: the plugin count no longer varies with DER, and `getAllScopeValues()` carries an empty `entity_item` entry. - `AiContextScopeAgentFormTest` asserts no language widgets, Languages in the "do not allow subscriptions" note, and that existing language subscriptions are preserved on save. - `AiContextScopeContextItemFormTest::testEntityScopeDescriptionsAndAccessibleLabel` asserted the Languages item-form description verbatim, including the old "more likely to be chosen" wording, and is updated to the new copy. This assertion failed from the first push of this branch. - `AiContextUnavailableScopeFormTest` gains the Unavailable row, the reachable settings tab, and a settings save without DER, and one assertion about removed subscription copy that could no longer fail is replaced. - `AiContextScopeCleanupServiceTest::testLanguageUninstallCleansLanguageValues()` already covered #3586416+s scrubbing dormant agent language subscriptions when a language is uninstalled; it still passes. ### Manual checks Performed on a two-language site with DER installed, after `drush cr`: 1. `/admin/config/ai/context/settings/agents/{ai_agent}/edit` has no Languages subscription widget. The note reads "These scope plugins do not allow subscriptions: Global, Roles, Languages, Specific Entities", and the subscribable scopes are Use Cases, Context Tags, Site Sections, Entity Types, and Taxonomy Terms. 2. The context item form still shows Languages tagging and the Specific Entities DER widget. 3. Context listing, general settings, Specific Entities settings, and an item view page all load with no PHP errors in the log. 4. With an agent in **Relevant**, a request whose page language matches an item tagged only with that language still injects the item via situational-match, with no agent language subscription. 5. Switching the same agent to **Minimal** no longer injects that language-only item. 6. An agent with `scope_subscriptions.language` already stored keeps those values in config after saving the form, and they do not affect ranking. To exercise the non-DER paths, uninstall `dynamic_entity_reference` on a throwaway site: the scope overview shows Specific Entities as Unavailable, its settings tab loads, and saving it with entity types unchecked succeeds. Do not do this where the `entity_items` field holds data. No update hook and no config change. After deploy, rebuild caches so plugin definitions and the agent form pick up the new capability and availability. No EchoAI tests: this is a scope-capability, prefilter, and plugin-availability change, not provider integration. ## Checklist - [x] I have updated the MR title to use format: `Issue #1234: My issue title.` - [x] I have updated the MR description to include: `Closes #1234` - [x] I have performed a self-review of my own code - [x] I have added or updated tests, or explained in the description why this change is not covered by tests - [x] I have updated documentation for any new or changed functionality - [x] I have written testing instructions and verified them locally - [x] I have noted any required post-merge steps (config imports, cache rebuilds, manual changes) - [x] This MR contains no breaking API or hook changes, or they are explicitly documented in the description — **behavioral: Languages `supportsSubscriptions()` is now FALSE (ranking and Minimal reach); Specific Entities is always discovered and reports `isAvailable()` FALSE without dynamic_entity_reference. Internal: `getParticipatingSubscriptions()` added on `@internal` `AiContextScopeResolverInterface`; `ai_context_ai_context_scope_info_alter()` is no longer implemented by this module. All documented above and in `docs/developers/api-stability.md`.** ## AI Compliance > [!note] > Check the one that best describes your usage, or leave all unchecked if AI was not significantly used. > > * [ ] AI **Assisted Code** \ > _Mainly written by a human; AI used for autocomplete or partial generation under full human supervision._ > > * [x] **AI Generated Code** \ > _Mainly generated by AI, reviewed and approved by a human before this MR was created._ > > * [ ] **Vibe Coded** \ > _Generated by AI and only functionally reviewed before this MR was created._