## Problem/motivation The pre-beta5 review in #3586404+s found three upgrade-path problems that must be resolved in beta5. These affect one-shot database updates and destructive cleanup, so rc1 cannot reliably repair sites that already upgraded. ### 1. Migrated agents silently change from Minimal to Relevant Beta4 treated missing or unrecognized agent `selection_mode` values as Minimal. Its agent form represented the default by omitting the key. `_ai_context_update_10028_convert_agent_row()` currently omits a missing or unrecognized mode. The migrated consumer then inherits the new site default, Relevant. This changes selection behavior during upgrade and may introduce situational matches and full-catalog scanning that the agent did not previously use. `match_all` is already correctly converted to Broad. Current valid modes from intermediate development snapshots should remain valid. The docblock for `ai_context_post_update_0004_add_site_default_selection_mode()` incorrectly describes Relevant as the previous implicit default. Relevant is the new-install default; Beta4 agents implicitly used Minimal. ### 2. A complete beta4 config export cannot be imported after upgrade A beta4 `ai_context.settings.yml` lacks `selection_mode`. The object is `FullyValidatable`, and the new key is required by default, so importing the old object fails validation. There is a larger compatibility problem: a beta4 sync directory contains `ai_context.agents.yml` but not `ai_context.consumers.yml`. After update 10028 creates consumers and deletes the active agents object, the import subscriber explicitly rejects recreation of the legacy agents object. Even if that check were removed, importing the old directory could delete the newly migrated consumers because they are absent from the source storage. Relaxing only the settings schema or allowing `match_all` in the legacy schema is therefore insufficient. Also, post-update 0003 cannot repair an agents object imported after `updatedb` has already completed. The import storage transform needs to recognize a beta4 source and convert its leftover agent rows into consumer rows before storage comparison. It must also preserve or create the required consumer-type settings introduced by beta5. ### 3. Post-update 0006 can destructively remove recoverable scope values `ai_context_post_update_0006_scrub_stale_scope_values()` runs against active configuration before the usual subsequent config import. The generic stale-value policy intentionally treats some options removed from scope settings as stale. That behavior is appropriate for an explicit settings save, as decided in #3586416+s, but is unsafe in a one-shot upgrade: - Entity Types values can be removed merely because their entity type is not enabled in the pre-import settings. - Site Section values can be removed even when the incoming configuration will restore the section. - An unavailable or disabled scope can return no live options and cause stored values to be removed. - On a single-language site, Language values can be removed despite the UI promising that stored values remain and are ignored until the scope becomes available. Changing `getStaleStoredValues()` globally would also change live settings-save cleanup, which is outside this issue. Post-update 0006 instead needs a conservative, upgrade-specific policy. ## Proposed resolution ### Agent migration Update `_ai_context_update_10028_convert_agent_row()` so: - missing mode → explicit `minimal` - unrecognized mode → explicit `minimal`, with the existing notice - `match_all` → `broad` - explicit `minimal`, `relevant`, or `broad` → preserved Update and import must share this conversion so they cannot drift. Identical duplicate agent rows collapse to the first row; conflicting duplicates abort. Delete `ai_context.agents` only after the consumers save succeeds. An interrupted `10028` that saved consumers without a mode is treated as Minimal on resume. Correct the post-update 0004 documentation to distinguish the Beta4 implicit Minimal behavior from the new-install Relevant default. ### Config-import compatibility In `AiContextConfigImportValidateSubscriber` or a dedicated collaborator: 1. During source-storage transformation, detect `ai_context.agents` when `ai_context.consumers` is absent. 2. Convert the leftover rows using the same normalization rules as update 10028, including duplicate collapse. 3. Write the converted `ai_context.consumers` source object in schema key order so a second import reports no changes. 4. Remove the leftover `ai_context.agents` source object. 5. Ensure required `ai_context.consumer_type_settings.agent` configuration is represented or preserved. Copy active Roles settings when the source omitted them. 6. Permit a beta4 `ai_context.settings` object without `selection_mode`; runtime should continue using the beta5 site fallback after import. 7. Remap leftover usage-View handlers and beta1/beta2 paths in place, sharing the path list with update 10027. Remap leftover scope-map / Diff plugin IDs in place. Write those payloads in schema key order too. 8. Reject an `agents` object that has no `agents` list as corrupt, not as an empty export. 9. If leftover `ai_context.agents` remains alongside `ai_context.consumers`, fail validation and tell the site to re-export. Do not tell them to remove only the leftover file. 10. Run the same residual repairs (type settings, Roles, View, plugin IDs) when the sync lost `ai_context.agents.yml` but still has structural leftovers (handler IDs, plugin IDs, leftover path). This is intentional: without it, a mixed sync deletes Beta5 settings and restores a leftover View. 11. Listen after Config Split’s default merge and before Config Ignore. The database update and import transform must share conversion logic so they cannot drift. ### Upgrade-safe stale-value cleanup Keep the existing live settings-save behavior from #3586416+s. For post-update 0006, use an upgrade-specific conservative scrub that: - skips disabled or unavailable scope plugins - removes Entity Types values only when the entity type or bundle actually no longer exists, not merely because the type is deconfigured - does not remove Site Section values based only on pre-import settings - preserves Language values when Language is unavailable - continues removing values backed by entities that objectively no longer exist, such as deleted roles, terms, languages, entity types, and bundles ## Tests ### Update 10028 - a Beta4 agent row without `selection_mode` migrates to explicit Minimal - an unrecognized mode migrates to explicit Minimal - `match_all` migrates to Broad - explicit Minimal, Relevant, and Broad survive - the leftover agents object is deleted only after consumers save successfully ### Config import A complete Beta4-style source containing: - `ai_context.settings` without `selection_mode` - `ai_context.agents` with missing/default and `match_all` modes - no `ai_context.consumers` - no consumer-type settings introduced by beta5 Assert that import succeeds, consumers remain present with correctly migrated modes, and the leftover agents object is not recreated. Also cover: identical/conflicting duplicate rows, missing `agents` list, schema-order convergence on a second import (including a real Beta4 export of the usage View and item display), mixed-sync leftover repair, leftover usage path remap, and transform order after a priority-0 merge. ### Post-update 0006 - values for a deconfigured but existing entity type and bundle survive - values for a genuinely deleted entity type or bundle are removed - non-default Language values survive when Language is unavailable - values belonging to disabled or unavailable scopes survive - pre-import Site Section values survive the post-update - deleted role and taxonomy-term values are still removed - item scope, consumer subscriptions, and scope-index rows remain consistent ## Decisions - F4 leftover repair without an agents object (`9beaadd`): **keep**. Dropping it reopens the mixed-sync wipe. - `sprintf()` in converter exception messages: no change. Exception text is developer-facing. ## Beta5 release notes > Upgrading from beta4. Run `drush updatedb` before importing configuration. Migrated agents keep Beta4's implicit Minimal selection mode; `match_all` becomes Broad. A Beta4 sync directory can still be imported after the upgrade (agents become consumers, the usage View and item display are repaired, settings without a selection mode fall back to Relevant); re-export afterwards. The upgrade removes only scope values whose entities no longer exist (deleted roles, terms, languages, entity types or bundles) and leaves everything else in place, including values for disabled or unavailable scopes. Values for a language removed from active configuration, or for an entity type whose module is disabled in the database, are removed even if the incoming configuration re-adds them; re-add those by hand after the import. ## Out of scope - Redesigning the Entity Types settings form cleanup behavior - Adding confirmation UI when scope options are removed - Changing the live cleanup decisions from #3586416+s - Changing Relevant as the default for fresh beta5 installations - Remapping only handler areas when a View still has leftover handlers (today the whole payload is rewritten) - Remapping translated `language/xx/views.view.ai_context_usage` collections - Copying every active `ai_context.consumer_type_settings.*` object, not only agent and automator - Guarding `stripLegacyMaxItems()` against a scalar `agents` list - Config Split weights above 50 (merge after this transform) - A real `config_split` kernel test ## Related issues #3586404+s #3586416+s #3586444+s ## AI usage - [x] AI assisted issue