## Summary Follow-up to: #3586406+s Saving a context item or an agent rebuilds scope (or subscriptions) from whatever the form posted. Disabled scopes, missing plugins, and Language on a single-language site are skipped in the UI, so their stored values disappear. That is silent data loss for recipe, API, and imported items. #3586408 originally covered only the Language case. This issue is that bug plus the same skip path for any disabled or unavailable scope, on both the item form and the agent form. Found in the #3586406 architecture review (group A: rows 13–15). Pre-existing; not caused by the #3586405 field-type change. ## Problem `AiContextItemForm` skips `!$plugin->isEnabled()` when building widgets and again when processing submit. It then calls `setScope($processed_scope)` with only posted, enabled scopes. `AiContextAgentForm` does the same for subscriptions: disabled scopes are not rendered, and `extractValues()` writes only what was posted. `AiContextScopeLanguage::buildValueForm()` special-cases `count($values) <= 1`: it hides the checkboxes and shows “language scoping is ignored.” The plugin stays enabled, so: - The Languages details box still appears on the item form. - Agent subscription forms can still expose language. - Selection / hard filters can still use stored `language` values (`AiContextScopeResolver` skips only `!$plugin->isEnabled()`). - Item form submit posts nothing for Language, so `extractFormValues()` returns `[]` and any stored language scope (API, recipe, Default Content, or an import from a multilingual site) is removed on the first UI save. Disabling Tags (or any other scope) and then editing an item or agent is the same wipe. A missing custom scope plugin is the same skip. Language module off is the same path today. Core still has one language (`en`); there is no hard unavailable check. ## Proposed approach Treat “disabled,” “plugin missing,” and “fewer than two languages” as unavailable, and **keep stored values** when the form cannot show them. Suggested implementation (open to a cleaner hook): - Add something like `isAvailable()` (or fold runtime availability into `isEnabled()` so settings + runtime stay one source of truth). - Language is unavailable when `count($this->languageManager->getLanguages()) <= 1`. - Hide unavailable scopes on the item form and agent subscription form (no Language stub details box on a single-language site). - Skip unavailable scopes in selection / hard filters and listing pills. - On `/admin/config/ai/context/settings/scope`, hide or disable the Language card unless a second language exists. - On save, merge posted values for available scopes with the previously stored values for unavailable / disabled / missing scopes. Do not use form save to strip them. - Leave stored `language` rows in the field. Recipes that ship `language: en` should no-op on a single-language site. When a scope is re-enabled, or a second language is added, existing stored values start applying again without a re-save. Shared surfaces: item form, agent form, language plugin, resolver/listing skip paths, `docs/features/scopes.md`. ## Implemented !271 keeps runtime availability as a separate `isAvailable()` on `AiContextScopeInterface`. It is not folded into the admin `enabled` setting. Forms and selection use an internal `isEnabledAndAvailable()` helper on `AiContextScopeManager`. Language is unavailable when the site has fewer than two languages. Disabled and unavailable scopes are hidden and ignored at runtime; form save keeps their stored item values and agent subscriptions. Two existing item rules still win: saving as Global, or as a subcontext that inherits parent scope, still strips non-applicable stored scope in `preSave()`. Listing pills, the scope field formatter, and selection omit unavailable and disabled scopes. The canonical Details panel already skipped them. Tests that assert Language pills, formatter rows, or filter options must add a second language first. Beta API (see `docs/developers/api-stability.md`): - Direct `AiContextScopeInterface` implementers must add `isAvailable()`. - Direct `AiContextScopeCacheableMetadataInterface` implementers must add `getAvailabilityCacheableMetadata()`. - `extractValues()` gained an optional `$previous` argument so hidden subscriptions can be kept. ## Out of scope - #3586405 field-type / Default Content storage work - Selector `ai_context.scope_settings.*` cache tags (#3586406 #9) - Request-body / function-call entity-hint access (#3586406 #10) - Stale `tags` form-display cleanup - Recipe authoring / import-semantics docs - Changing language detection or translation fallback - Folding language scope into entity langcode - `AiContextScopeItem::generateSampleValue()` (separate DX follow-up) - Splitting `supportsSubscriptions()` ## Acceptance criteria - [x] On a site with one language, Languages does not appear on the context item form or agent subscription form - [x] On a site with one language, stored `language` values do not filter or score items - [x] Saving an item on a single-language site does not clear stored `language` scope - [x] Saving an item after disabling a scope (e.g. Tags) keeps that scope’s stored values - [x] Saving an agent after disabling a scope keeps that scope’s subscriptions - [x] A missing / unavailable custom scope plugin does not wipe its stored item values or agent subscriptions on save - [x] Adding a second language makes Language available; existing stored values apply without a re-save - [x] Removing the last extra language makes Language unavailable again; stored values remain - [x] Re-enabling a disabled scope makes stored item values and agent subscriptions apply without a re-save - [x] The scope field formatter omits disabled and unavailable scopes (listing pills and the Details panel already do) - [x] Docs (`docs/features/scopes.md`, multilingual notes) state that language scope requires more than one language, and that disabled / unavailable scopes are ignored at runtime but not deleted on form save - [x] Kernel/functional coverage for: one-language vs two-language (form + selection); disable-scope then save item; disable-scope then save agent ## Testing instructions See !271 for PHPUnit commands. Manual check: 1. Single-language site (Language module off, or on with only English): - Item add/edit and agent forms have no Languages widget. - Create an item via `setScope(['language' => ['en'], 'use_case' => ['working_with_text']])` or recipe YAML. Save through the UI. Use Case remains. Language remains stored and does not affect listing or selection. - Scope overview shows Language as Unavailable. Saving Language settings does not flip `enabled`. 2. Add Spanish. Edit the same item: Languages checkboxes appear. Selection and listing pills can show language. No re-save needed. 3. Delete Spanish so only English remains. Languages disappears again; stored values are ignored, not deleted. 4. Disable Tags in scope settings. Edit an item that has tag scope and an agent that subscribes to those tags. Save both. Re-enable Tags: item values and agent subscriptions are still there. 5. Repeat step 4 with a custom scope plugin removed from the codebase (or `isEnabled() === FALSE`). 6. Save an item as Global, or as a subcontext that inherits parent scope, and confirm other stored scope is still cleared. After deploy, rebuild caches so listings and item views pick up availability cache tags. ## Related - #3586406 — architecture review (group A, rows 13–15) - #3586405 — scope field storage (discovery only; do not fix here) - #3586196 — scope model discussion - !271 — implementation ## AI usage - [x] AI assisted issue