Drupal AI Context (Context Control Center / CCC) Playbook

Classification: PROCEDURE. Not authority; the governing standard below owns the rules.
Authority: how-we-build §10
Upstream Project: https://www.drupal.org/project/ai_context
Documentation: https://project.pages.drupalcode.org/ai_context/
Canonical Git: https://git.drupalcode.org/project/ai_context

---

1. The Center of the World: Context Control Center

drupal/ai_context (Context Control Center / CCC) is the single source of truth and architectural center for all AI agent context, memory models, prompt injection, and organizational knowledge across the Bluefly estate.

graph TD
    A["Authoring / Governance (Draft/Published)"] --> B["ai_context_item Entity"]
    B --> C["Scope Manager (plugin.manager.ai_context_scope)"]
    C --> D["Global / UseCase / Language / Entity / Taxonomy Scopes"]
    B --> E["Subcontext Hierarchy (Parent / Child)"]
    E --> F["Required Children (Auto-included)"]
    E --> G["Conditional Children (Model-evaluated)"]

    D & F & G --> H["AiContextRequestFactory & AiContextSelector"]
    H --> I["Selection Pipeline Events<br/>(ITEMS_SELECTED / TEXT_RENDERED)"]
    I --> J["AiContextSystemPromptSubscriber"]
    J --> K["LLM Agent Prompt Execution"]

---

2. Core Upstream Architecture & Public APIs

2.1 Public Service: ai_context.request_factory

Class: Drupal\ai_context\Service\AiContextRequestFactory
The supported, stable public entry point for building context requests and fetching rendered text:

// Inject in classes: services.yml argument '@ai_context.request_factory',
// or create() in plugins/forms/controllers. \Drupal::service() is for
// procedural code only (see DRUPAL-BEST-PRACTICES.md section 2.1).
$factory = $this->contextRequestFactory; // AiContextRequestFactory

// 1. One-liner: get rendered context text
$text = $factory->getRenderedContext(
  scopes: ['use_case' => ['writing_code']],
  maxTokens: 2000,
  currentEntity: $node,
  consumerId: 'agent_drupal',
);

// 2. Full result with cache metadata and item IDs
$result = $factory->getResult(
  scopes: ['use_case' => ['writing_code']],
  maxTokens: 2000,
  currentEntity: $node,
  consumerId: 'agent_drupal',
);
$renderedText = $result->getRenderedText();
$cacheMetadata = $result->getCacheableMetadata();
$selectedIds   = $result->getSelectedItemIds();

2.2 Selector Pipeline Events

Stable lifecycle events on Drupal\ai_context\Event\AiContextSelectionEvents:

Stage	Constant	Event Name	Purpose
Items Selected	ITEMS_SELECTED	ai_context.selection.items_selected	Inspect, filter, or inject ai_context_item entities before rendering.
Text Rendered	TEXT_RENDERED	ai_context.selection.text_rendered	Alter final rendered context text (e.g. Cedar write-guard checks, audit headers).

Extension Law: Never decorate or replace ai_context.selector in services.yml. All customizations MUST use AiContextRequestFactory or subscribe to ITEMS_SELECTED / TEXT_RENDERED.

---

3. Scopes & Scope Plugin Architecture

Scope plugins (plugin.manager.ai_context_scope) implement AiContextScopeInterface:

Scope Plugin	ID	Matching Behavior
Global Scope	global	Always included across all agents and site requests.
Use Case Scope	use_case	Matches task intent (e.g. writing_code, content_authoring, audit).
Language Scope	language	Matches active UI/content language negotiation.
Tag Scope	tag	Matches taxonomy tags on the context item.
Entity Scope	entity	Matches active node, landing page, bundle, or section via Dynamic Entity Reference.
Taxonomy Scope	taxonomy	Matches terms present on the active entity being processed.

---

4. Subcontext Hierarchies (Parent / Child)

Enables deep knowledge organization without prompt blowout: - Parent Context: High-level domain concept or policy. - Child Context: Specialized procedure or subtopic. - Required Children: Automatically injected whenever parent is matched. - Conditional Children: Injected only if the AI model evaluates the child as relevant to the active prompt. - inherit_parent_scope: Children inherit parent scope matching rules.

---

5. First-Class Content Entity: ai_context_item

• Editorial Workflows: Full lifecycle (draft, published, archived) via content_moderation.
• Revision History: Visual diff tracking via drupal/diff.
• Scheduling: Automated activation/expiry via drupal/scheduler.
• Packaging: Bundles (agent_memory, kb_plan, kb_idea, kb_ownership, kb_context_memory) are packaged cleanly via recipe_contextual_memory.

---

6. Token Budgeting & Protection

• AiContextTokenEstimator: Uses configured AI tokenizer (ai.tokenizer) to estimate byte/token weights.
• AiContextSubscriptionBudgetCalculator: Enforces per-agent and per-subscription limits.
• AiContextSelector: Prunes candidate items to ensure the injected prompt stays within context limits.

---

7. Bluefly Integration Contract

HUMAN GOVERNED CONTEXT
  ↓
drupal/ai_context (CCC) ─── Canonical Context Entity, Scopes, Token Budgets
  ↓
Bluefly Extensions (`kb_cache`) ─── GAID Provenance, Cedar PDP Write Guards, DUADP Federation
  ↓
Drupal AI / Vector Provider ─── Qdrant Vector Upserts & Search
  ↓
LLM Agent Prompts ─── Clean, Injected, Governed Context