## Summary When scope cleanup removes the last value of a scope from a context item, it deletes that scope key and keeps the item published. An empty scope key does not restrict the item. An item that was limited to one role, language, site section, content type, term or entity is then delivered more widely, and nothing is logged. Example: an item is limited to the "Reviewer" role. An admin deletes the role. The item is now delivered to every user who can use published context. Target: 1.0.0 if this is RTBC by the code freeze on 2026-11-09, otherwise 1.0.1. ## Steps to reproduce 1. Add a role "Reviewer" at `/admin/people/roles/add`. Do not give it to the test editor. 2. Add a published context item "Reviewer checklist" at `/admin/config/ai/context/items/add` with: - Roles: Reviewer - Entity Types: Content: Blog post 3. Run this check as a user who has the "Use Published AI Context in AI Features" permission and does not have the Reviewer role. Replace `EDITOR_UID` and `BLOG_NID`. "Reviewer checklist" is not in the list. ``` drush php:eval ' \Drupal::service("account_switcher")->switchTo(\Drupal\user\Entity\User::load(EDITOR_UID)); $node = \Drupal\node\Entity\Node::load(BLOG_NID); $result = \Drupal::service("ai_context.selection_factory")->getResult([], NULL, $node, NULL, "relevant"); print_r($result->getSelectedItemIds()); ' ``` 4. Delete the role at `/admin/people/roles/manage/reviewer/delete`. 5. Open "Reviewer checklist" from `/admin/config/ai/context/items`, then open its Revisions tab. 6. Run the check from step 3 again. ## Expected result - After step 4, "Reviewer checklist" is unpublished. On sites that use the `ai_context_editorial` workflow, its state is Archived. - The admin who deleted the role sees a warning that one context item was unpublished, with a link to the item list. - The Revisions tab shows a new revision by the admin who deleted the role, with a log message that says scope cleanup unpublished the item and which Roles value it removed. - Recent log messages shows a warning that names the item and the removed Roles value. - In step 6, "Reviewer checklist" is not in the list. ## Actual result - The item has no Roles value and is still Published. No new revision is created, and nothing is shown or logged. - In step 6, "Reviewer checklist" is in the list. It is now delivered on every Blog post to every user who can use published context. Cause: - `removeScopeValuesFromItems()` unsets a scope key that becomes empty and saves the item (`src/Service/AiContextScopeCleanupService.php:364-372`). - An empty key does not restrict the item: - Roles returns NULL for an item with no role values (`src/Plugin/AiContextScope/AiContextScopeRoles.php:150-153`). - Language uses the same rule in the base class (`src/Plugin/AiContextScope/AiContextScopeBase.php:513-519`). - Site Section, Entity Types and Taxonomy do the same (`AiContextScopeSiteSection.php:362-365`, `AiContextScopeEntityType.php:200-203`, `AiContextScopeTaxonomy.php:209-212`). - `removeEntityItemReference()` has the same problem for Specific Entities (`src/Service/AiContextScopeCleanupService.php:306-322`). An item with no entity reference is not restricted by that scope (`src/Plugin/AiContextScope/AiContextScopeEntityItem.php:196-198`). - The existing tests check the emptied scope but not the status (`tests/src/Kernel/AiContextScopeCleanupServiceTest.php:985` and `:1023`). Before cleanup, a stale value never matches ("A leftover stale role ID never matches", `docs/features/scopes.md:180-181`). So the item is safe while the stale value is stored, and becomes wider only when cleanup removes the last value. Every cleanup trigger can widen an item: - role delete (`AiContextScopeRoles.php:188-202`) and language delete (`AiContextScopeLanguage.php:241-255`); - term and vocabulary delete, and delete of any entity that Specific Entities references (`ai_context.module:200-216`); - bundle delete (`ai_context.module:257-261`); - uninstall of any other module, which scans every enabled stored-value scope (`ai_context.module:311-319`); - save of Site Section or Entity Types settings (`src/EventSubscriber/AiContextScopeConfigSubscriber.php:66`); - post-update 0006 (`ai_context.post_update.php:146-149`). The scans also remove values that do not exist on this site, for example term UUIDs or roles on items copied from another site. One unrelated module uninstall can then widen many items at once. ## Proposed resolution Unpublish the item when cleanup would make it wider. Record why in the item's revision history. Tell the person who triggered the cleanup, and log each item. Changes in `AiContextScopeCleanupService` (`@internal`): 1. In `removeScopeValuesFromItems()`, when the last value of a hard-filter scope is removed, unpublish the item. Context Tags only rank items (`docs/features/scopes.md:55`), so removing a tag, including the last one, leaves the item published. Exception: a subcontext item with no stored inherit flag resolves to its parent when it has no own value left. If that parent is Global, unpublish the child. The scope plugin API has no flag for hard filters, so custom stored-value scopes are treated as hard filters. This is the safe default. Do not add a public API for this during the release candidate. A cleanup policy interface can follow in 1.1 if a custom ranking-only scope needs it. 2. In `removeEntityItemReference()`, unpublish the item when its last Specific Entities reference is removed. 3. Use `setUnpublishedWithModerationState()` (`src/Entity/AiContextItem.php:235`), so that content moderation does not publish the item again. Unpublish every published translation, because the scope field is shared by all translations but the status is stored for each translation. Save all translations in one database transaction, and roll back if a save fails. Never unpublish a Global item, because it already reaches every request. Also clear the Publish on date (and `publish_state`) on every translation, so that Scheduler does not publish the item later with the emptied scope. If the workflow has no unpublished state that is a default revision state, content moderation would keep the item published. Check this before the save: do not save the item, keep the stale value (it matches no request), log an error, and add a sentence for these items to the status warning (item 6). Log each scope of an item once, so that each error names a scope to fix, and count the item once in the warning, also when a later scan in the same request finds the stale value again. 4. Save the unpublished item as a new revision: - `setNewRevision(TRUE)`. Without a new revision, `preSaveRevision()` keeps the old log message (`src/Entity/AiContextItem.php:274-277`). - Revision log message, for example: "Unpublished automatically by scope cleanup: the last Roles value (reviewer) was removed because it is no longer available on this site." For Specific Entities: "…the last Specific Entities reference (node 12) was removed because the entity was deleted." - Revision user: the current user (the account that triggered the cleanup). Revision time: the request time. 5. The review record (key-value collection `ai_context.cleanup_review`) and the UI that shows it move to a follow-up issue, because nothing reads the records until that UI exists. 6. Log one warning for each unpublished item with its label, ID, the scope ID and the removed values. Show one warning message with the number of unpublished items and a link to the item list. Show the link only to users who can open the list. When cleanup runs more than once in one request, replace the message with the new total, also across the container rebuild of a module uninstall. Show no message to the anonymous user (cron, Drush); the log entries are still written. 7. Do not change the status of items that are already unpublished, and do not write a revision, log entry or message for them. Cleanup still removes the stale value (item 8) and saves it without a new revision. Exception: when such an item has a Publish on date, cancel it in a new revision with the log message "Scheduled publishing cancelled by scope cleanup: …", and log and count the item, because Scheduler would otherwise publish it later with the emptied scope. 8. Keep removing the values from items and from consumer subscriptions. A subscription value does not limit who receives an item, so subscriptions need no extra step. 9. Inject `@logger.channel.ai_context`, `@messenger`, `@current_user`, `@datetime.time` and `@database` into the service (`ai_context.services.yml`), and the new `@ai_context.scope_cleanup_notice`, which is tagged `persist` and keeps the count for item 6. 10. When cleanup does not unpublish an item (a value is left, or the item is already unpublished), save it with `setSyncing(TRUE)`, so that content moderation does not add a revision that copies the previous log message, author and time. Save-time pruning, planned in #3586393+s for 1.1, must follow the same rule. Add a comment there. ### Alternatives considered - **Keep the last stale value instead of removing it.** The item stays restricted, because a stale value never matches. But the item form does not show values that are not valid options, so the next editor save can remove the value and widen the item without a message. Planned save-time pruning (#3586393+s) would do the same. - **Store a "matches nothing" marker in an emptied key.** Every scope plugin, including custom scopes, must then know the marker. Situational scopes return NULL when the request has no context (for example Drush or cron without an entity), so the marker would not block the item in all cases. - **Scan only the scopes of the uninstalled module.** This makes a module uninstall affect fewer items, but it does not fix role, language, term or bundle deletes. - **Find cleanup revisions from the log message.** The message is translated and editors can type the same text, so the review record is the reliable signal. The log message is for people. Unpublishing is visible to editors, keeps working after the next save, and works for custom scopes. ## Remaining tasks 1. [x] Rebase on MR !326 (#3586551+s) if it is committed first. It also changes the constructor of `AiContextScopeCleanupService`, its service definition, `ai_context_modules_uninstalled()` and the `ai_context.scope_cleanup` docs section. The branch is built on the !326 branch (d9c387e); merge after !326. 2. [x] Implement the changes above, starting from the local branch `wip-unpublish-emptied-hard-filter` (unpublish, transaction, Global exception, warning log and tests). Add the revision log message and the status message, and use the hard-filter default for custom scopes instead of the policy interface on that branch. 3. [x] File the follow-up issue for the review record and the UI that shows unpublished items on the context items page: #3586604+s. 4. [x] Kernel: extend `AiContextScopeCleanupServiceTest`: 1. [x] lines 985 and 1023: the emptied items are unpublished; 2. [x] Roles emptied while Entity Types remains: the item is unpublished; 3. [x] Tag emptied while another scope remains: the item stays published; 4. [x] a key that keeps one value: the item stays published; 5. [x] last Specific Entities reference deleted: the item is unpublished; 6. [x] moderated item: the state is Archived and stays unpublished after save (in the new `AiContextScopeCleanupModerationTest`, because content moderation makes every save a new revision); 7. [x] item with a translation: the status of every translation is unpublished (in `AiContextScopeCleanupModerationTest`); 8. [x] a new revision exists, with the log message, the current user as revision user, and the request time; 9. [x] already unpublished item: no change, no new revision, no log entry and no message (the stale value is still removed); 10. [x] the log entry names the item ID and the scope ID, and one message shows the count; 5. [x] Kernel: add `AiContextScopeCleanupForeignValuesTest`. Add one case for each trigger, with values that do not exist on this site: module uninstall, bundle delete, Site Section settings save, Entity Types settings save, role delete, language delete, term delete and vocabulary delete. Each case checks which values are removed and the publish state. Use Case values are never removed. Config import does not run the uninstall and settings-save scans. 6. [x] EchoAI kernel: extend `AiContextEchoAiSystemPromptTest`. Delete the `editor` role used by the "Editor climate" item, run the agent as the contributor, and check that the prompt does not contain that item. 7. [x] Docs: - [x] `docs/features/scopes.md:98-101` and `:180-181`: cleanup unpublishes an item when it removes the last value of a hard-filter scope, and adds a revision that says why. - [x] The `ai_context.scope_cleanup` section in `docs/developers/services.md` (from line 262): the new behaviour. - [x] The stored-value paragraph in `docs/developers/custom_scopes.md:64-69`: custom stored-value scopes are treated as hard filters. 8. [x] Release note: cleanup now unpublishes items that it would make wider, and adds a revision that says why. After you delete roles, languages, terms or bundles, or uninstall modules, check the context item list for newly unpublished or archived items. 9. [x] Add a comment on #3586393+s: save-time pruning must follow the same rule. 10. [x] Update #3586604+s: it writes the review records itself, because this issue does not write them. 11. [x] File the follow-up issue for a Site Section settings check that reports a section still in use before it is removed: #3586684+s. ## Environment - Drupal version: any version that 1.0.0-rc1 supports (^10.5 || ^11.2) - Module version: 1.0.0-rc1 (8a57807) and 1.0.x (913c3c2) - PHP version: any supported version - Provider: any. Cleanup runs without a provider call. - Last known working version: none ### Frontend environment *(only required for UI / frontend issues)* Not applicable. This is server-side behaviour. ### Screenshots / recordings *(optional)* None. ### Error messages or logs *(optional)* None. Cleanup logs nothing when it empties a scope. > [!note] > Check the one that best describes your usage, or leave all unchecked if AI was not significantly used. > > * [ ] AI **Assisted Issue** \ > _Mainly written by a human; AI used for partial generation under full human supervision._ > > * [x] AI **Generated Issue** \ > _Mainly generated by AI, reviewed and approved by a human before this issue was created._