## Summary Follow-up to: #3586243+s Before 1.0, lock down what custom scope authors and contrib can safely depend on, without landing the full persistence/orchestration refactor from #3586243+. This issue is documentation and internal seam-setting only: no new public interface methods and no user-visible behavior changes. The current scope plugin API is already broad enough for map-backed custom scopes, but docs and code send mixed signals. The scope manager is marked `@internal` while developer docs show injection patterns; the resolver interface docblock calls itself public while `api-stability.md` treats it as internal; `supportsSubscriptions()` is documented for agent forms but also drives context auto-inclusion internally; and core code still hardcoded scope plugin ID strings in scattered places. Implementation: [MR !249](https://git.drupalcode.org/project/ai_context/-/merge_requests/249) (merged with current `1.0.x`, including #3586276+ `entity_type` / `entity_item` renames). ## Problem | Concern | Today | |---------|--------| | Public vs internal boundary | Contradictory docs for manager and resolver | | `supportsSubscriptions()` | Documented as agent-form visibility only; also used for auto-inclusion | | Custom scope storage | Implied flexibility via `getValuesFromEntity()`; no clear 1.0 contract for custom storage | | Internal coupling | Magic scope ID strings and a one-off entity item branch in stored-value summary logic | | Superseded work | #3586243+ / [MR !164](https://git.drupalcode.org/project/ai_context/-/merge_requests/164) attempted a large refactor that is out of scope for 1.0 | ## Solution 1. **Documentation alignment** - In `api-stability.md`, `scope_api.md`, and `custom_scopes.md`, state clearly: - Scope plugins, hooks, and the subscription form builder are public. - `plugin.manager.ai_context_scope`, the resolver, index, and cleanup services are internal. - Document that `supportsSubscriptions(): FALSE` means both (a) hidden on agent subscription forms and (b) eligible for context auto-inclusion when `matchesCurrentContext()` returns TRUE. - State explicitly: **1.0 custom scopes are supported on the scope map field**; custom entity-field storage, indexing, cleanup, and form lifecycle integration are **not** a supported extension surface in 1.0 (planned for 1.1). 2. **Internal identifier cleanup** - Add `PLUGIN_ID` constants to built-in scope plugins (matching the existing `VALUE_GLOBAL` pattern). - Replace internal hardcoded core scope ID literals in `src/` with those constants where safe. 3. **Single internal seam for entity item stored values** - Consolidate the entity item special case in stored-value summary logic (e.g. `AiContextScopeManager::buildScopeSummaryFromStoredValues()`) behind one private/internal helper so 1.1 persistence work does not require hunting call sites. 4. **Tests** - Add or adjust kernel/unit tests covering constants and unchanged behavior (stored vs effective scope summaries, subscription form builder still works, no regression in scope plugin discovery). ## Out of scope - New methods on `AiContextScopeInterface` - Splitting `supportsSubscriptions()` into separate capability flags - Entity item encapsulation, manager orchestration, presave validation, index/cleanup plugin APIs - Per-item inclusion mode, agent-form UX reframing #3586281+ - Boundaries / exclusions #3586197+ - Moving entity item storage from DER into the scope map ## Acceptance criteria - [x] `api-stability.md`, `scope_api.md`, and `custom_scopes.md` agree on public vs internal scope-related APIs - [x] Dual semantics of `supportsSubscriptions()` are documented with examples - [x] 1.0 custom-scope storage contract is explicit (scope map yes; custom storage lifecycle no) - [x] Built-in scope plugins expose `PLUGIN_ID` constants; internal literals in `src/` use them - [x] Entity-item stored-value handling uses one internal helper, not ad hoc branching at call sites - [x] `./lint.sh` passes - [x] Relevant kernel/unit tests pass - [x] #3586243+ closed with pointer to this issue and the 1.1 follow-up; [MR !164](https://git.drupalcode.org/project/ai_context/-/merge_requests/164) closed as superseded ## Verification Testers checking out [MR !249](https://git.drupalcode.org/project/ai_context/-/merge_requests/249) on a site still at schema **10014** must run `drush updatedb -y && drush cr` **before** loading admin pages; otherwise the context listing can WSOD on the removed `target_entity` plugin class until update hooks 10015–10019 run. Verified locally: - `./lint.sh` — pass - `AiContextScopeManagerTest` — 14 tests, 0 failures - Broader kernel scope suite — 89 tests, 0 failures - Functional scope/listing tests — 62 tests, 0 failures - Admin routes (listing, general settings, item view) — HTTP 200 after `updatedb` - GitLab CI on `!249` — pass ## Related - Supersedes: #3586243+ - Builds toward: 1.1 capability-based persistence API issue #3586393+ - Downstream UX/semantics: #3586281+ → #3586197+ ## AI usage - [x] AI assisted issue