## Problem/Motivation Follow-up to: #3586414+s Some scopes already strip stored values when an option disappears. Tags do this on term delete. Site sections do this when a section is removed from config. Entity item references are cleared when the target entity is deleted. Other dynamic scopes do not. After a content type, taxonomy term, or language is removed — or an entity type is taken out of Entity Types settings — context items and agent subscriptions can still store the old value. The scope index keeps that row until the item is resaved. This is preexisting. It is not a regression from the Entity Types All wildcard (`type:_all`). All only makes the leftover more visible: a `node:_all` subscription should overlap `node:news`, but the SQL prefilter expands from live `getValues()`, so an orphaned `node:news` row is skipped. Current-context matching cannot use a deleted bundle anyway, and the form can no longer select it. ## Proposed resolution Reuse `ai_context.scope_cleanup` (`AiContextScopeCleanupService::removeScopeValues()`) so items, agent subscriptions, and the scope index stay in sync. Do not invent a second cleanup path. The service only strips values. Plugins that can lose options implement optional `AiContextScopeStoredValueInterface` (same pattern as `AiContextScopeValueMatchingInterface`) and decide which stored values are stale and whether a Drupal change should trigger a scrub. Hooks and the settings-config subscriber stay generic; they do not special-case plugin IDs. ### Live cleanup | Event | What is removed | |-------|-----------------| | Bundle delete | That `type:bundle` value only. `type:_all` stays (All still means current and future bundles). | | Type removed from Entity Types settings | Every value for that type, **including** `type:_all`. | | Taxonomy term delete | That term from Taxonomy Terms (not Context Tags). Cheap ID strip, not a full scan. | | Vocabulary delete | Per-term ID strips, then one full Taxonomy Terms scan. | | Context tag delete | That term from Context Tags. | | Language uninstall | That langcode from Language. | | Role delete | That role from Roles. | | Site section removed from settings | That section ID. `custom:` patterns stay. | | Module uninstall | Full stale-value scrub for leftover type / vocabulary / language values whose providing module is gone. Skipped when uninstalling `ai_context` itself. | ### Decisions - **`type:_all` on bundle delete:** keep. - **`type:_all` when a type is removed from settings:** remove it. It is no longer a live option. - **Use Case:** no event cleanup and no scrub. Options are hardcoded and extendable via `hook_ai_context_scope_values_alter()`, so Use Case does not implement the interface. - **Roles:** included. Same disappearing-option pattern as Language. - **One-time update:** yes. `ai_context_post_update_0006_scrub_stale_scope_values()` asks every opted-in plugin to drop leftovers from before live cleanup existed. - **Config import:** skip the settings-save scrub while config is syncing. Plugins compare stored values to the live environment, so a mid-import settings save can delete content-item values. Bundle-delete hooks still run. A sync that only removes options converges on the next real settings save. - **Post-update 0006 vs deploy order:** standard pipelines run `drush updatedb` before `drush config:import`. `0006` scrubs against the pre-import environment. A copied production database on a lower environment can lose values for options the imminent import is about to add. On production, active config is already authoritative. ### Plugin policy (not a raw `getValues()` diff) - Language, Roles, Context Tags, Entity Types: stale if missing from `getAlteredValues()` (honors alter-hook IDs). - Site Section: keep `custom:` **or** a live section. - Taxonomy Terms: keep if the term exists and is not in `ai_context_tags`, **or** an alter hook added it. - Term, language, and role deletes return that entity ID from `getStaleStoredValuesForEntityDelete()`. Return `NULL` for a full scan (vocabulary entity delete). `AiContextScopeInterface` is unchanged. Custom scopes opt in through the stored-value interface. ## Remaining tasks - [x] Wire bundle delete and Entity Types settings changes into `ai_context.scope_cleanup` - [x] Wire taxonomy term delete and language uninstall the same way - [x] Consider use case cleanup (skipped: hardcoded + alterable; does not implement the interface) - [x] Kernel tests for item scope, agent subscriptions, and index rows - [x] Decide whether a one-time update should scrub values that are already stale (`0006`) - [x] Optional `AiContextScopeStoredValueInterface` so plugins own stale-value policy - [x] Docs (`scope_api.md`, `custom_scopes.md`, `services.md`, `hooks.md`, `api-stability.md`, `configuration.md`, `scopes.md`) - [x] Skip settings-save scrub during config import (`config.installer->isSyncing()`) - [x] Document that `0006` runs against the pre-import environment - [x] `hook_modules_uninstalled()` full scrub (except when uninstalling this module) - [x] Targeted ID strip for term / language / role delete; vocabulary delete does one final full scan MR: !278 ## Testing instructions 1. Check out the MR branch on a site that already has AI Context enabled and run `ddev drush updatedb -y && ddev drush cr`. 2. **Bundle delete:** enable Node on Entity Types settings. Create a News content type. Create a context item scoped to Content: Article, Content: News, and Content: All. Subscribe an agent to the same three values. Delete the News type. Confirm the item and subscription keep Article and All, and News is gone. 3. **Entity Types settings:** create an item scoped to Content: All plus a taxonomy-term bundle. Uncheck Content on Entity Types settings and save. Confirm every `node:…` value is gone, including All. Taxonomy-term values stay. 4. **Taxonomy Terms:** create a Topics term, scope an item to it, delete the term. Confirm Taxonomy Terms no longer stores that ID. A Context Tag on the same item must stay. 5. **Vocabulary delete:** scope an item to two Topics terms, delete the Topics vocabulary. Confirm both term IDs are gone from the item, subscriptions, and index. 6. **Context Tags:** delete a tag term and confirm that tag is stripped from the item and from agent subscriptions. 7. **Language:** add Spanish, scope an item to English + Spanish, uninstall Spanish. Confirm only English remains. 8. **Roles:** create an Editor role, scope an item to Authenticated + Editor, delete Editor. Confirm only Authenticated remains. 9. **Site Sections:** configure HR and Support. Scope an item to HR, Support, and a custom pattern (`/hr/*`). Remove HR from settings. Confirm Support and the custom pattern remain; HR is gone. 10. **Use Case:** confirm Use Case values are not stripped by `0006` or by the events above. 11. **Disable scope:** uncheck Enabled on Entity Types settings and save. Confirm stored `node:…` values are still on the item. 12. Optional: `ddev exec phpunit --configuration=web/core web/modules/contrib/ai_context/tests/src/Kernel/AiContextScopeCleanupServiceTest.php web/modules/contrib/ai_context/tests/src/Kernel/AiContextStaleScopeValuesPostUpdateTest.php` Kernel run: 14 tests, 441 assertions in `AiContextScopeCleanupServiceTest`, plus the `0006` post-update test. ## Related issues #3586414+s (Entity Types All wildcard) #3586415+s (Roles) #3586419+s (mentioned while working on selection capabilities) #3586393+s (related cleanup discussion) ## AI disclosure - [x] AI assisted issue