## Summary On 1.0.x (rc1), `ai_context_item` and `ai_context_usage` are content entity types that are not marked internal. When a site enables core JSON:API, core builds a resource type and routes for each of them. Nothing in CCC turns them off. JSON:API is not enabled by default (Drupal CMS does not install it), so this affects sites that enable it on purpose. This issue turns both resources off for 1.0.0. An opt-in for context items can follow later without a break. Parent: #3586600+s (child 3). Part of #3586615+s. ### Why turn off the context item resource JSON:API is useful for some sites, for example sites that sync content with Entity Share. But for context items, the resource has these problems: 1. **The wrong permission controls it.** JSON:API checks only entity access. For a published item, that is the permission **Use Published AI Context in AI Features**. That permission is for using context in AI features, it is not restricted, and the docs suggest giving it to broad roles, also to anonymous users for public chatbots. With JSON:API on, every account with that permission can page through all published items over HTTP. The permission description says that it does not give the CCC listing, but the JSON:API collection route is a listing. 2. **It returns raw data without the CCC rules.** The response has the raw fields: content, purpose, description, stored scope values (role IDs, term UUIDs, site section patterns), priority, token count, and the IDs of the parent item, the author and Specific Entities targets. The CCC delivery rules (Roles, Languages, Site Sections, Never include, token budget, token neutralization) do not apply, and no usage record is written. Each collection response also lists, in `meta.omitted`, the UUIDs of items on that page that the caller cannot view, published or not. Anonymous callers get these UUIDs too. 3. **It is not useful for integrations as it is.** CCC has no JSON:API filter-access hook, so every filtered request from an account without **Administer AI Context** returns no results. Only unfiltered paging works. A child item that inherits its parent's scope stores an empty scope, so a generic client sees it as an item with no scope. 4. **It can only be turned off before 1.0.0.** If the resource stays on in 1.0.0, its resource name, field names, scope field shape and access rules become an HTTP contract that sites can depend on. Turning it off in a later minor release would break those sites. If it is off in 1.0.0, an opt-in later only adds a feature. 5. **A safe opt-in needs work that cannot land before the code freeze (2026-11-09).** It needs a dedicated read permission (#3586357+s, postponed), a filter-access hook, field access rules for writes (for example the author field), and a setting that rebuilds the resource types and the router when it changes. This is not a new access level. An account with the consumer permission can already open one published item at a time on the item page, or through the Load tool. The issue removes the bulk HTTP path, which site builders do not expect from a permission that reads as an in-site AI permission. What JSON:API already protects, so it is not a reason for this change: - Older revisions and drafts need the revision permissions. - The revision log message is hidden from accounts that cannot view revisions or edit the item. - Access is checked for each translation, so an unpublished translation is not returned. ### Why make usage records internal - Usage records are a documented internal entity. The CCC usage page shows "(no access)" for items that the viewer cannot access. JSON:API would return the raw records, with consumer IDs, runner IDs, tools used and routes, without that redaction. - A change to the usage storage that is not backward compatible is already planned for 1.1 (`entity_item_id` changes from an integer to a string). It must not become an HTTP contract. - Usage records are not moderated, so `internal = TRUE` does not affect editorial workflows. This is the same approach as core's `content_moderation_state`. ### Who is affected - Sites that read or sync context items or usage records through JSON:API, for example with Entity Share, lose that access in 1.0.0. CCC 1.0.0 has no supported replacement. Outside access is planned in #3586600+s. - Core REST still offers a resource for context items, because core REST skips only internal entity types. A site builder must enable it on purpose. - Other generic tools that list entities, for example the AI Agents tool `ai_agent:list_content_entities`, can still return raw item fields to the same accounts. This issue closes only the JSON:API path. Separating AI use from item access is planned in #3586357+s. ## Proposed resolution - Set `internal = TRUE` on `ai_context_usage`. Core REST resource discovery and other integrations that skip internal entity types also stop offering usage records. - Do not set `internal = TRUE` on `ai_context_item`. Content Moderation and Workspaces skip internal entity types, so the flag would remove the editorial workflow and the moderation transition access checks. - Add an `@internal` subscriber for `jsonapi.resource_type.build` that disables the context item resource type. The event name is a string, so the subscriber works when JSON:API is not installed. - Add no post-update. The release note tells sites to run `drush cr`, which rebuilds the container, the entity type definitions and the JSON:API resource types. Until then, the resources stay available. - Docs: - `access-boundaries.md`: "Generic entity APIs". There is no supported way to enable the resources again in 1.0.0. Core REST can still be enabled for context items by a site builder. - `api-stability.md`: the output of generic entity APIs (JSON:API, REST) is not part of the 1.x public API. Update "Beta upgrade: scope field JSON:API shape", which describes the item resource. - `configuration.md`: update the JSON:API sentence in the scope field update section. **Decisions:** 1. **1.0.0, not 1.1.0-alpha1.** Turning the resource off is a break after 1.0.0, but an opt-in later is not. 2. **No setting to enable the resources again in 1.0.0.** An opt-in for context items is planned in #3586600+s (child 3). It can be added later without a break. Because 1.0.0 is the first stable release, the 1.1 plan to keep the resource on for existing sites with an update hook is no longer necessary. ### Other approaches considered - **Keep the resource on and document the fields as unstable.** Not done. A docs note does not protect HTTP clients, and turning the resource off later is a break. - **Add a setting in 1.0.0 that is off by default.** Not done. The "on" state needs the work in point 5 above before it is safe. The setting also needs a config schema change, a form field, a post-update and cache and router rebuilds. - **Add a `settings.php` switch.** Not done now. It is smaller, but when it is on, the exposure is the same as today. It can be added before the code freeze if a site reports that it depends on the resource. - **Require a restricted permission on the JSON:API item routes.** Not done. Filters would still return no results, the CCC rules would still not apply, and the raw field shape would still become a contract. - **Mark context items internal.** Not done, because it removes Content Moderation and Workspaces support. - **Add an empty post-update, so that `drush updb` rebuilds the caches.** Not done. Sites run `drush cr` after the update. An empty post-update adds a function with no code, and other open MRs also use the next post-update number. ## Remaining tasks - [x] Kernel: with JSON:API enabled, the `ai_context_item` and `ai_context_usage` resource types are internal, and the `user` resource type is not (`AiContextEntityExposureTest`). - [x] Kernel: `ai_context_usage` is internal, `ai_context_item` is not, and context items keep the moderation handler. - [x] Existing moderation tests pass: `AiContextModeratedDetachTest` and `AiContextItemModerationAccessTest`. - [x] Decide 1.0.0 or 1.1.0-alpha1: 1.0.0. - [x] Decide whether sites can enable the resources again: no setting in 1.0.0; an opt-in can follow without a break. - [x] Decide how sites pick up the change: `drush cr` in the release note, no post-update. - [x] Check on a local site with JSON:API enabled: `/jsonapi` lists no context item or usage resource, both collection routes return 404, and the usage page still works. - [x] Docs: `access-boundaries.md` ("Generic entity APIs"). - [x] Release note. - [x] Open the MR (!354). - [x] Docs: in `access-boundaries.md`, replace "must replace the JSON:API resource type repository" with "there is no supported way to enable the resources again", and say that core REST can still be enabled for context items. - [x] Docs: in `api-stability.md`, say that the output of generic entity APIs is not part of the 1.x public API, and update "Beta upgrade: scope field JSON:API shape" (line 159). - [x] Docs: update the JSON:API sentence in `configuration.md` (line 454). - [x] Align with #3586606+s (!347). Its "Core JSON:API" section says that both entity types are exposed. Whichever merges second must change the text. (tracked in #3586606: !347 removes its Core JSON:API section after this merges) - [x] Update #3586600+s child 3 (open question 3): 1.0.0 turns the resources off with no exception for existing sites, and an opt-in can follow. - [x] Update the MR text to match. - [x] Docs: in `access-boundaries.md`, add the step for sites that enabled a core REST resource for usage records (delete it before `drush cr` or `drush updatedb`), and use the current permission titles. ## Release note Context items and usage records are no longer available through core JSON:API. Before this change, a site that enabled JSON:API gave every account with **Use Published AI Context in AI Features** a bulk HTTP read of all published context items with their raw fields, without the CCC delivery rules. Usage records are now an internal entity type, so core REST and other integrations that skip internal types no longer offer them either. Context items remain non-internal for Content Moderation and Workspaces. Sites that read or synced context items through JSON:API, for example with Entity Share, lose that access, and this release has no supported replacement. Run `drush cr` after the update. Until the caches are rebuilt, the resources stay available. If the site enabled a core REST resource for usage records, delete it before you rebuild the router, that is before you run `drush cr` or `drush updatedb`: run `drush config:delete rest.resource.entity.ai_context_usage`, and remove it from config sync. Otherwise the router rebuild fails, because the REST plugin for usage records no longer exists. Workspaces now ignores usage records, so usage is also recorded while a non-default workspace is active. ## Environment - Module version: 1.0.0-rc1 (8a57807); 1.0.x has no later commits. > [!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._