## Summary Blocks: #3586385+s Replace the core `map` field used for context item `scope` with a custom multi-value Field API type (`scope_id` + `value` columns) so Default Content / recipes, Diff, and similar consumers can import and display scope without workarounds. **Approved approach: Option 2.** Recipes that set scope are a 1.0 requirement. This is a freeze-exception storage change. The logical model (`scope_id => list of value IDs`) and the custom scope plugin API stay. Implementation: [MR !258](https://git.drupalcode.org/project/ai_context/-/merge_requests/258). ## Problem Context item scope was stored as a core `map` base field: ```php ['scope_id' => ['value1', 'value2'], ...] ``` `MapItem::propertyDefinitions()` returns an empty list by design. Anything that sets field properties by name fails: - Core Default Content / recipe import calls `$item->get('value')` and throws `InvalidArgumentException: Property value is unknown`. - The Diff module's core map builder looks for a `value` key; CCC already shipped a map Diff builder for that gap. - SQL selection cannot query the blob, so CCC maintains `ai_context_item_scope_index` as a denormalized copy of `(item_id, scope_id, value)`. The Rotterdam demo recipe (#3586385) must ship published items with scope (Global for the university writing guidelines). A stash-and-presave Default Content subscriber was prototyped and rejected: it is not a Drupal 11 recipe pattern. Core `map` is an escape hatch (`no_ui`, serialized blob, no properties). It was a reasonable early choice because plugins can add keys without schema changes and `getScope()` / `setScope()` stay simple. That still applies to the **API shape**. It does not apply to using core `map` as the **field type** once recipes must ship scope. #3586243 locked the logical model and plugin persistence. It did not choose the Field API type. This issue replaces only the backing store. ## Approved approach (Option 2) Custom field type `ai_context_scope`, unlimited cardinality, revisionable, `no_ui`. Each assignment is one delta: | delta | scope_id | value | |------:|----------|-------| | 0 | global | global | | 1 | use_case | working_with_text | | 2 | language | en | Recipe / Default Content YAML is a standard delta list: ```yaml scope: - scope_id: global value: global - scope_id: use_case value: working_with_text ``` Keep: - `getScope()` / `setScope()` / `getScopeValues()` / `setScopeValues()` as the nested-map PHP API (assemble / explode rows internally). - The `ai_context_item_scope_index` table. It stores **effective** scope (parent inheritance copied onto the child id). The field table only has the item's **own** rows. - `entity_items` as DER. Do not fold Specific Entities into these rows. Do **not** accept a grouped array on `create()` or `$entity->set('scope')`. That path stored a malformed delta and made `getScope()` return empty. Grouped arrays belong only on `setScope()`. Field API deltas belong on `create()`, `set('scope')`, recipes, and Default Content. Either mismatch throws `InvalidArgumentException`. Write-path contract: - Every Field API write (`setValue()`, `set()`, `appendItem()`, offset append) rejects arrays, objects, and booleans instead of casting them. - Direct item and property writes use the same rule (`AiContextScopeString` plus item `setValue()` / `onChange()`). - Duplicate `scope_id` + `value` pairs are dropped on those paths and again in list `preSave()`. - `setScope()` also rejects delta-shaped input and IDs/values over 64/255 characters. Migrate existing map blobs (including revisions) with `ai_context_update_10026()`. The blob lived on `ai_context_item_field_data.scope` and `ai_context_item_field_revision.scope`. After the change, storage is `ai_context_item__scope` and `ai_context_item_revision__scope`. `10024` is already used (taxonomy scope default config). Do not reuse it. Remove the Default Content subscriber / presave hack. Rebase #3586385 onto this and put real `scope` YAML in the university recipe. ## Explored options (not selected) | # | Approach | Decision | Why | |---|----------|----------|-----| | 0 | Keep core `map`; recipes omit scope | Rejected | Recipes cannot set scope. Diff and the index stay special cases. | | 1 | Custom field type, still one nested-map blob, but define a `value` property | Rejected | Unblocks import only. Views, entity query, Diff, JSON:API, and the dual-write index keep special-casing a blob. | | 2 | Multi-value field: `scope_id` + `value` columns | **Approved** | Native Field API. Recipes, revisions, and query work. Matches the index shape. | | 3 | Boolean `is_global` plus keep `map` | Rejected | Two sources of truth. Only helps Global. | | 4 | One field per scope plugin | Rejected | Breaks the supported custom-scope storage model. DER for Specific Entities remains the one internal exception. | | 5 | Default Content subscriber + presave stash | Rejected | Not a Drupal 11 recipe pattern. Do not merge. | | 6 | Child "scope assignment" entities / paragraphs | Deferred | Idiomatic but heavier than the problem needs. | | 7 | JSON column / contrib `json_field` | Rejected | Still a blob unless named properties are defined. | | 8 | Wait for a core `map` / Default Content fix | Rejected | Core almost never uses `map` on real entities. Unlikely to become first-class. | | 9 | Make the index table the source of truth | Rejected | Inverts Field API. | | 10 | `string_long` + `json_encode` | Rejected | Worse than `map`. | | 11 | Two separate multi-value fields (`scope_id` and `scope_value`) | Rejected | Deltas do not stay paired. | ## Out of scope - Folding `entity_items` into the pair field - Dropping the scope index table - Inclusion semantics (#3586281) or exclusions (#3586197) - Changing which scopes participate in subscriptions JSON:API output changes from a map blob to a list of pairs. That is acceptable before 1.0 and is noted in the upgrade docs. ## Acceptance criteria - [x] `scope` is field type `ai_context_scope` with `scope_id` + `value` properties (unlimited, revisionable) - [x] Existing items and revisions migrate; empty scope and mixed global + other scopes are covered - [x] `getScope()` / `setScope()` keep working for in-module callers and custom scope plugins - [x] `create()` / `$entity->set('scope')` accept only Field API deltas; a grouped array throws `InvalidArgumentException` instead of storing empty scope - [x] Malformed values (arrays, objects, booleans) are rejected on list, item, and property writes - [x] Duplicate `scope_id` + `value` pairs are dropped on every write path - [x] A recipe can import Global and other scopes without a custom presave / Default Content subscriber - [x] Diff, listing, selection, and the scope index keep current behaviour - [x] Published-global counts query the dedicated field instead of loading every published item - [x] `entity_items` remains DER - [x] Update hook `10026` (batched) and upgrade notes - [x] Tests cover field type, formatter, Default Content import, migration, and the grouped-vs-delta contract - [x] `./lint.sh` passes ## Testing instructions See [MR !258](https://git.drupalcode.org/project/ai_context/-/merge_requests/258). 1. Create a context item with Use Case + Language scope. Save, view, and edit it. Scope still shows and persists. 2. On `/admin/config/ai/context/items`, confirm the cascade Scope / Scope value filters still hide and show rows. 3. Confirm an existing item from before this update still has its scope after `drush updatedb` (including an older revision if you have one). 4. Optional: import Default Content / recipe YAML that uses `scope_id` + `value` deltas (`docs/developers/scope_api.md`). ## Post-merge - Deploy code and run `drush updatedb -y` then `drush cr` before serving traffic. Do not serve between code deploy and 10026. - Rebase #3586385 onto this so the Rotterdam recipe can ship real `scope` YAML. ## Affected functional areas Context items, scope plugins, context selection, recipes / Default Content, Diff, scope index, entity view display. ## Related - #3586385 — CCC recipe for Inside Rotterdam demo (depends on this for shipping scope in YAML) - #3586243 — Scope plugin persistence API (logical model / plugin contract; this issue does not reopen that spike) - #3586196 — Scope model discussion ## AI usage - [x] AI assisted issue