agentic-qe 3.11.1 → 3.11.3

package/dist/mcp/tools/code-intelligence/c4.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agentic QE v3 - C4 Architecture MCP Tool (ADR-112)
+ *
+ * qe/code/c4 - Generate C4 architecture diagrams (Context/Container/Component,
+ * Mermaid) from codebase analysis, plus semantic search over stored diagrams.
+ *
+ * Wraps the SAME pipeline the CLI `aqe code c4` drives:
+ *   ProductFactorsBridgeService (detect) → C4ModelService (render+store) →
+ *   deterministic confidence gate. This keeps MCP-CLI parity by construction.
+ */
+import { MCPToolBase, MCPToolConfig, MCPToolContext } from '../base';
+import { ToolResult } from '../../types';
+import type { C4Diagrams, C4ConfidenceAssessment } from '../../../shared/c4-model';
+export type C4Level = 'context' | 'container' | 'component' | 'all';
+export interface CodeC4Params {
+    action: 'generate' | 'search';
+    projectPath?: string;
+    level?: C4Level;
+    query?: string;
+    limit?: number;
+    [key: string]: unknown;
+}
+export interface C4GenerateResult {
+    diagrams: C4Diagrams;
+    confidence?: C4ConfidenceAssessment;
+    componentsDetected: number;
+    externalSystemsDetected: number;
+    relationshipsDetected: number;
+    circularDependencies: number;
+}
+export interface C4SearchHit {
+    key: string;
+    type: 'context' | 'container' | 'component';
+    title: string;
+    score: number;
+    preview: string;
+}
+export interface C4SearchResult {
+    results: C4SearchHit[];
+    total: number;
+}
+export interface CodeC4Result {
+    action: string;
+    generateResult?: C4GenerateResult;
+    searchResult?: C4SearchResult;
+}
+export declare class CodeC4Tool extends MCPToolBase<CodeC4Params, CodeC4Result> {
+    readonly config: MCPToolConfig;
+    private bridge;
+    private searchService;
+    private getBridge;
+    /** Embeddings ON here so stored diagrams are semantically searchable. */
+    private getSearchService;
+    execute(params: CodeC4Params, context: MCPToolContext): Promise<ToolResult<CodeC4Result>>;
+}
+//# sourceMappingURL=c4.d.ts.map

package/dist/mcp/tools/code-intelligence/c4.js

@@ -0,0 +1,145 @@
+/**
+ * Agentic QE v3 - C4 Architecture MCP Tool (ADR-112)
+ *
+ * qe/code/c4 - Generate C4 architecture diagrams (Context/Container/Component,
+ * Mermaid) from codebase analysis, plus semantic search over stored diagrams.
+ *
+ * Wraps the SAME pipeline the CLI `aqe code c4` drives:
+ *   ProductFactorsBridgeService (detect) → C4ModelService (render+store) →
+ *   deterministic confidence gate. This keeps MCP-CLI parity by construction.
+ */
+import { MCPToolBase, getSharedMemoryBackend } from '../base';
+import { ProductFactorsBridgeService } from '../../../domains/code-intelligence/services/product-factors-bridge';
+import { C4ModelService } from '../../../domains/code-intelligence/services/c4-model';
+import { KnowledgeGraphService } from '../../../domains/code-intelligence/services/knowledge-graph';
+import { createKnowledgeGraphRelationshipResolver } from '../../../domains/code-intelligence/services/c4-model/kg-relationships';
+import { InMemoryEventBus } from '../../../kernel/event-bus';
+import { toErrorMessage } from '../../../shared/error-utils.js';
+const want = (level, l) => level === 'all' || level === l;
+// ============================================================================
+// Tool Implementation
+// ============================================================================
+export class CodeC4Tool extends MCPToolBase {
+    config = {
+        name: 'qe/code/c4',
+        description: 'Generate C4 architecture diagrams (Context/Container/Component, Mermaid) from a codebase with a deterministic confidence gate, or semantically search previously generated diagrams.',
+        domain: 'code-intelligence',
+        schema: CODE_C4_SCHEMA,
+        streaming: false,
+        timeout: 300000,
+    };
+    bridge = null;
+    searchService = null;
+    async getBridge(context) {
+        if (!this.bridge) {
+            const memory = context.memory ?? (await getSharedMemoryBackend());
+            // ADR-112 C2: KG-backed resolver (project-scoped) so MCP matches the CLI.
+            // publishEvents:false — the MCP path doesn't need the cross-domain event.
+            this.bridge = new ProductFactorsBridgeService(new InMemoryEventBus(), memory, {
+                publishEvents: false,
+                // ADR-112: embed generated diagrams so `search` can find them.
+                enableC4Embeddings: true,
+                relationshipResolver: createKnowledgeGraphRelationshipResolver((projectPath) => new KnowledgeGraphService(memory, { basePath: projectPath })),
+            });
+        }
+        return this.bridge;
+    }
+    /** Embeddings ON here so stored diagrams are semantically searchable. */
+    async getSearchService(context) {
+        if (!this.searchService) {
+            const memory = context.memory ?? (await getSharedMemoryBackend());
+            this.searchService = new C4ModelService(memory, { enableEmbeddings: true });
+        }
+        return this.searchService;
+    }
+    async execute(params, context) {
+        const { action, projectPath = '.', level = 'all', query, limit = 10 } = params;
+        try {
+            if (this.isAborted(context)) {
+                return { success: false, error: 'Operation aborted' };
+            }
+            const result = { action };
+            switch (action) {
+                case 'generate': {
+                    const bridge = await this.getBridge(context);
+                    const res = await bridge.requestC4Diagrams({
+                        projectPath,
+                        includeContext: want(level, 'context'),
+                        includeContainer: want(level, 'container'),
+                        includeComponent: want(level, 'component'),
+                        includeDependency: level === 'all',
+                        analyzeComponents: true,
+                        detectExternalSystems: true,
+                        analyzeCoupling: true,
+                    });
+                    if (!res.success) {
+                        return { success: false, error: toErrorMessage(res.error) };
+                    }
+                    const c4 = res.value;
+                    result.generateResult = {
+                        diagrams: c4.diagrams,
+                        confidence: c4.metadata.analysisMetadata?.confidence,
+                        componentsDetected: c4.components.length,
+                        externalSystemsDetected: c4.externalSystems.length,
+                        relationshipsDetected: c4.relationships.length,
+                        circularDependencies: (c4.couplingAnalysis ?? []).filter((co) => co.isCircular).length,
+                    };
+                    break;
+                }
+                case 'search': {
+                    if (!query) {
+                        return { success: false, error: 'Query is required for search action' };
+                    }
+                    const service = await this.getSearchService(context);
+                    const res = await service.searchDiagrams(query, limit);
+                    if (!res.success) {
+                        return { success: false, error: toErrorMessage(res.error) };
+                    }
+                    result.searchResult = {
+                        results: res.value.map((r) => ({ key: r.key, type: r.type, title: r.title, score: r.score, preview: r.preview })),
+                        total: res.value.length,
+                    };
+                    break;
+                }
+                default:
+                    return { success: false, error: `Unknown action: ${action}` };
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            return { success: false, error: toErrorMessage(error) };
+        }
+    }
+}
+// ============================================================================
+// Schema
+// ============================================================================
+const CODE_C4_SCHEMA = {
+    type: 'object',
+    properties: {
+        action: {
+            type: 'string',
+            description: 'C4 action to perform',
+            enum: ['generate', 'search'],
+        },
+        projectPath: {
+            type: 'string',
+            description: 'Project root to analyze (generate action). Defaults to the current directory.',
+        },
+        level: {
+            type: 'string',
+            description: 'C4 level to generate (generate action)',
+            enum: ['context', 'container', 'component', 'all'],
+        },
+        query: {
+            type: 'string',
+            description: 'Semantic search query over stored diagrams (search action)',
+        },
+        limit: {
+            type: 'number',
+            description: 'Max search results (search action)',
+        },
+    },
+    required: ['action'],
+};
+//# sourceMappingURL=c4.js.map

package/dist/mcp/tools/index.d.ts

@@ -37,6 +37,7 @@ export { DefectPredictTool, type DefectPredictParams, type DefectPredictResult,
 export { RequirementsValidateTool, type RequirementsValidateParams, type RequirementsValidateResult, type RequirementInput, type ValidationResult, type TestabilityScore, type BDDScenario, } from './requirements-validation/validate';
 export { QualityCriteriaTool, qualityCriteriaTool, type QualityCriteriaParams, type QualityCriteriaResult, type EvidencePointInput, type AgentInvocation, } from './requirements-validation/quality-criteria';
 export { CodeAnalyzeTool, type CodeAnalyzeParams, type CodeAnalyzeResult, type IndexResult, type SearchResult, type ImpactResult, type DependencyResult, } from './code-intelligence/analyze';
+export { CodeC4Tool, type CodeC4Params, type CodeC4Result, type C4GenerateResult, type C4SearchResult, } from './code-intelligence/c4';
 export { SecurityScanTool, type SecurityScanParams, type SecurityScanResult, type Vulnerability, type ScanSummary, type ComplianceResult, } from './security-compliance/scan';
 export { ContractValidateTool, type ContractValidateParams, type ContractValidateResult, type BreakingChange, type VerificationResult, type CompatibilityReport, } from './contract-testing/validate';
 export { VisualCompareTool, A11yAuditTool, type VisualCompareParams, type VisualCompareResult, type A11yAuditParams, type A11yAuditResult, type A11yViolation, type VisualComparison, } from './visual-accessibility';

package/dist/mcp/tools/index.js

@@ -61,6 +61,7 @@ export { QualityCriteriaTool, qualityCriteriaTool, } from './requirements-valida
 // Code Intelligence Domain
 // ============================================================================
 export { CodeAnalyzeTool, } from './code-intelligence/analyze';
+export { CodeC4Tool, } from './code-intelligence/c4';
 // ============================================================================
 // Security Compliance Domain
 // ============================================================================

package/dist/mcp/tools/registry.d.ts

@@ -33,6 +33,7 @@ export declare const QE_TOOL_NAMES: {
     readonly REQUIREMENTS_VALIDATE: "qe/requirements/validate";
     readonly QUALITY_CRITERIA: "qe/requirements/quality-criteria";
     readonly CODE_ANALYZE: "qe/code/analyze";
+    readonly CODE_C4: "qe/code/c4";
     readonly SECURITY_SCAN: "qe/security/scan";
     readonly CONTRACT_VALIDATE: "qe/contracts/validate";
     readonly VISUAL_COMPARE: "qe/visual/compare";

package/dist/mcp/tools/registry.js

@@ -13,6 +13,7 @@ import { DefectPredictTool } from './defect-intelligence/predict';
 import { RequirementsValidateTool } from './requirements-validation/validate';
 import { QualityCriteriaTool } from './requirements-validation/quality-criteria';
 import { CodeAnalyzeTool } from './code-intelligence/analyze';
+import { CodeC4Tool } from './code-intelligence/c4';
 import { SecurityScanTool } from './security-compliance/scan';
 import { ContractValidateTool } from './contract-testing/validate';
 import { VisualCompareTool, A11yAuditTool } from './visual-accessibility';
@@ -48,6 +49,7 @@ export const QE_TOOL_NAMES = {
     QUALITY_CRITERIA: 'qe/requirements/quality-criteria',
     // Code Intelligence
     CODE_ANALYZE: 'qe/code/analyze',
+    CODE_C4: 'qe/code/c4',
     // Security Compliance
     SECURITY_SCAN: 'qe/security/scan',
     // Contract Testing
@@ -110,6 +112,7 @@ export const QE_TOOLS = [
     new QualityCriteriaTool(),
     // Code Intelligence Domain
     new CodeAnalyzeTool(),
+    new CodeC4Tool(),
     // Security Compliance Domain
     new SecurityScanTool(),
     // Contract Testing Domain

package/dist/shared/c4-model/confidence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ADR-112 — Deterministic C4 confidence gate.
+ *
+ * Pure, code-only (NO LLM in the gate — same discipline as ADR-111's accept
+ * gate). Turns the code-intelligence detector's known limits (the
+ * qe-code-intelligence skill records ~18% success on complex queries and
+ * degradation above ~50K LOC) into an explicit, surfaced signal so a
+ * confident-but-wrong diagram is never presented as ground truth.
+ */
+export type C4Confidence = 'high' | 'medium' | 'low';
+export interface C4ConfidenceInputs {
+    /** Number of components the detector found. */
+    componentsDetected: number;
+    /** Number of component relationships (edges) detected. */
+    relationshipsDetected: number;
+    /** Number of external systems detected. */
+    externalSystemsDetected: number;
+    /** Number of source files analyzed. */
+    filesAnalyzed: number;
+    /** Total lines of code, if known (e.g. from MetricCollector). Optional. */
+    totalLoc?: number;
+}
+export interface C4ConfidenceAssessment {
+    /** Bucketed level for quick display. */
+    level: C4Confidence;
+    /** Continuous score in [0,1] the level is derived from. */
+    score: number;
+    /** Human-readable reasons (always populated). */
+    reasons: string[];
+}
+/** Repo size (LOC) beyond which the skill records detection degradation. */
+export declare const C4_LOC_DEGRADE_THRESHOLD = 50000;
+/**
+ * Assess how much to trust an auto-generated C4 diagram. Deterministic: the same
+ * inputs always yield the same level + reasons.
+ */
+export declare function assessC4Confidence(inputs: C4ConfidenceInputs): C4ConfidenceAssessment;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/shared/c4-model/confidence.js

@@ -0,0 +1,69 @@
+/**
+ * ADR-112 — Deterministic C4 confidence gate.
+ *
+ * Pure, code-only (NO LLM in the gate — same discipline as ADR-111's accept
+ * gate). Turns the code-intelligence detector's known limits (the
+ * qe-code-intelligence skill records ~18% success on complex queries and
+ * degradation above ~50K LOC) into an explicit, surfaced signal so a
+ * confident-but-wrong diagram is never presented as ground truth.
+ */
+/** Repo size (LOC) beyond which the skill records detection degradation. */
+export const C4_LOC_DEGRADE_THRESHOLD = 50_000;
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+/**
+ * Assess how much to trust an auto-generated C4 diagram. Deterministic: the same
+ * inputs always yield the same level + reasons.
+ */
+export function assessC4Confidence(inputs) {
+    const { componentsDetected, relationshipsDetected, externalSystemsDetected, totalLoc } = inputs;
+    const reasons = [];
+    // Empty diagram — nothing to trust.
+    if (componentsDetected === 0) {
+        return {
+            level: 'low',
+            score: 0,
+            reasons: ['No components detected — the diagram is effectively empty; verify against the source.'],
+        };
+    }
+    let score = 0.5;
+    // Relationships are the weakest link in heuristic detection. Their presence is
+    // the strongest signal that the STRUCTURE (not just a node list) is real.
+    const relDensity = relationshipsDetected / Math.max(1, componentsDetected);
+    if (relationshipsDetected === 0 && componentsDetected > 1) {
+        score -= 0.25;
+        reasons.push('No relationships detected between components — edges are heuristic-only or missing; the structure is unverified.');
+    }
+    else if (relDensity >= 0.5) {
+        score += 0.2;
+        reasons.push(`${relationshipsDetected} relationship(s) detected across ${componentsDetected} components.`);
+    }
+    else {
+        score += 0.05;
+        reasons.push(`${relationshipsDetected} relationship(s) detected (sparse) across ${componentsDetected} components.`);
+    }
+    // External systems detected → the Platform/Interfaces picture is grounded.
+    if (externalSystemsDetected > 0) {
+        score += 0.1;
+        reasons.push(`${externalSystemsDetected} external system(s) detected from dependencies.`);
+    }
+    // Repo size vs the known degradation threshold.
+    if (totalLoc !== undefined && totalLoc > C4_LOC_DEGRADE_THRESHOLD) {
+        score -= 0.3;
+        reasons.push(`Repository is large (${totalLoc.toLocaleString()} LOC > ~${C4_LOC_DEGRADE_THRESHOLD / 1000}K) — detection accuracy degrades; treat the diagram as a draft.`);
+    }
+    // A healthy component count adds confidence; a single component is thin.
+    if (componentsDetected >= 5) {
+        score += 0.1;
+    }
+    else if (componentsDetected === 1) {
+        score -= 0.05;
+        reasons.push('Only one component detected — likely an under-segmented view.');
+    }
+    score = clamp01(score);
+    const level = score >= 0.7 ? 'high' : score >= 0.4 ? 'medium' : 'low';
+    if (level !== 'high' && !reasons.some((r) => r.includes('draft') || r.includes('verify'))) {
+        reasons.push('Auto-generated draft — verify against the source before relying on it.');
+    }
+    return { level, score: Math.round(score * 1000) / 1000, reasons };
+}
+//# sourceMappingURL=confidence.js.map

package/dist/shared/c4-model/index.d.ts

@@ -8,6 +8,8 @@
  * Based on the C4 Model by Simon Brown:
  * https://c4model.com/
  */
+export * from './confidence';
+import type { C4ConfidenceAssessment } from './confidence';
 /**
  * C4 Diagrams container for all diagram levels
  */
@@ -52,6 +54,8 @@ export interface C4AnalysisMetadata {
     externalSystemsDetected: number;
     /** Analysis duration in milliseconds */
     analysisTimeMs: number;
+    /** ADR-112: deterministic confidence gate for the generated diagrams */
+    confidence?: C4ConfidenceAssessment;
 }
 /**
  * C4 Person element - represents a user of the system

package/dist/shared/c4-model/index.js

@@ -8,6 +8,7 @@
  * Based on the C4 Model by Simon Brown:
  * https://c4model.com/
  */
+export * from './confidence';
 /**
  * Check if a cache entry is still valid
  */

package/dist/shared/llm/providers/gemini.js

@@ -17,7 +17,7 @@ import { safeJsonParse } from '../../safe-json.js';
  * Default Gemini configuration
  */
 export const DEFAULT_GEMINI_CONFIG = {
-    model: 'gemini-1.5-pro',
+    model: 'gemini-2.5-flash', // gemini-1.5-pro was retired ("not found for API version"); 2.5-flash is current
     maxTokens: 8192,
     temperature: 0.7,
     timeoutMs: 60000,
@@ -42,6 +42,10 @@ export const GEMINI_PRICING = {
     'gemini-1.5-flash': { input: 0.075, output: 0.3 },
     'gemini-1.5-flash-latest': { input: 0.075, output: 0.3 },
     'gemini-2.0-flash-exp': { input: 0.075, output: 0.3 },
+    // Gemini 2.5 (current generation)
+    'gemini-2.5-pro': { input: 1.25, output: 10.0 },
+    'gemini-2.5-flash': { input: 0.3, output: 2.5 },
+    'gemini-flash-latest': { input: 0.3, output: 2.5 },
     // Gemini Ultra (flagship)
     'gemini-ultra': { input: 7.0, output: 21.0 },
     'gemini-1.0-ultra': { input: 7.0, output: 21.0 },
@@ -393,15 +397,18 @@ export class GeminiProvider {
         if (this.cachedModels) {
             return this.cachedModels;
         }
+        // Current text-generation models (verified via Gemini ListModels API 2026-06-27).
+        // Prefer the `-latest` aliases as defaults so they don't rot (gemini-1.5-pro was retired).
         return [
-            'gemini-pro',
-            'gemini-1.0-pro',
-            'gemini-1.5-pro',
-            'gemini-1.5-pro-latest',
-            'gemini-1.5-flash',
-            'gemini-1.5-flash-latest',
-            'gemini-2.0-flash-exp',
-            'gemini-ultra',
+            'gemini-flash-latest',
+            'gemini-pro-latest',
+            'gemini-flash-lite-latest',
+            'gemini-2.5-pro',
+            'gemini-2.5-flash',
+            'gemini-2.5-flash-lite',
+            'gemini-2.0-flash',
+            'gemini-2.0-flash-lite',
+            'gemini-3.5-flash',
         ];
     }
     /**
@@ -485,7 +492,6 @@ export class GeminiProvider {
      */
     handleApiError(status, data, model) {
         const message = data.error?.message ?? 'Unknown API error';
-        const errorStatus = data.error?.status ?? '';
         switch (status) {
             case 400:
                 // Check for context length exceeded FIRST (message-based detection)

package/dist/shared/llm/providers/openrouter.js

@@ -61,7 +61,7 @@ export const OPENROUTER_PRICING = {
  * OpenRouter LLM provider implementation
  */
 export class OpenRouterProvider {
-    type = 'openai'; // Compatible with OpenAI interface
+    type = 'openrouter';
     name = 'OpenRouter';
     config;
     requestId = 0;
@@ -138,7 +138,7 @@ export class OpenRouterProvider {
     async generate(input, options) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
-            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openai', retryable: false });
+            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openrouter', retryable: false });
         }
         const messages = this.formatMessages(input, options?.systemPrompt);
         const model = options?.model ?? this.config.model;
@@ -193,7 +193,7 @@ export class OpenRouterProvider {
             return {
                 content,
                 model: data.model,
-                provider: 'openai', // Report as openai for compatibility
+                provider: 'openrouter',
                 usage,
                 cost,
                 latencyMs,
@@ -206,7 +206,7 @@ export class OpenRouterProvider {
             if (error instanceof Error && 'code' in error) {
                 throw error; // Re-throw LLM errors
             }
-            throw createLLMError(error instanceof Error ? error.message : 'Request failed', 'NETWORK_ERROR', { provider: 'openai', model, retryable: true, cause: error });
+            throw createLLMError(error instanceof Error ? error.message : 'Request failed', 'NETWORK_ERROR', { provider: 'openrouter', model, retryable: true, cause: error });
         }
     }
     /**
@@ -216,7 +216,7 @@ export class OpenRouterProvider {
     async *generateStream(input, options) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
-            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openai', retryable: false });
+            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openrouter', retryable: false });
         }
         const messages = this.formatMessages(input, options?.systemPrompt);
         const model = options?.model ?? this.config.model;
@@ -246,7 +246,7 @@ export class OpenRouterProvider {
             throw this.handleApiError(response.status, errorData, model);
         }
         if (!response.body) {
-            throw createLLMError('No response body for streaming', 'NETWORK_ERROR', { provider: 'openai', model, retryable: true });
+            throw createLLMError('No response body for streaming', 'NETWORK_ERROR', { provider: 'openrouter', model, retryable: true });
         }
         let fullContent = '';
         let finishReason = 'stop';
@@ -311,7 +311,7 @@ export class OpenRouterProvider {
         return {
             content: fullContent,
             model: responseModel,
-            provider: 'openai',
+            provider: 'openrouter',
             usage,
             cost,
             latencyMs,
@@ -327,7 +327,7 @@ export class OpenRouterProvider {
     async embed(text, options) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
-            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openai', retryable: false });
+            throw createLLMError('OpenRouter API key not configured', 'API_KEY_MISSING', { provider: 'openrouter', retryable: false });
         }
         const model = options?.model ?? 'openai/text-embedding-3-small';
         const start = Date.now();
@@ -351,7 +351,7 @@ export class OpenRouterProvider {
             return {
                 embedding: data.data[0].embedding,
                 model: data.model,
-                provider: 'openai',
+                provider: 'openrouter',
                 tokenCount: data.usage.total_tokens,
                 latencyMs,
                 cached: false,
@@ -361,7 +361,7 @@ export class OpenRouterProvider {
             if (error instanceof Error && 'code' in error) {
                 throw error;
             }
-            throw createLLMError(error instanceof Error ? error.message : 'Embedding request failed', 'NETWORK_ERROR', { provider: 'openai', model, retryable: true, cause: error });
+            throw createLLMError(error instanceof Error ? error.message : 'Embedding request failed', 'NETWORK_ERROR', { provider: 'openrouter', model, retryable: true, cause: error });
         }
     }
     /**
@@ -378,7 +378,7 @@ export class OpenRouterProvider {
         return {
             completion: response.content,
             model: response.model,
-            provider: 'openai',
+            provider: 'openrouter',
             usage: response.usage,
             latencyMs: response.latencyMs,
             cached: response.cached,
@@ -525,19 +525,19 @@ export class OpenRouterProvider {
         switch (status) {
             case 401:
                 throw createLLMError(message, 'API_KEY_INVALID', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: false,
                 });
             case 402:
                 throw createLLMError(message, 'COST_LIMIT_EXCEEDED', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: false,
                 });
             case 429:
                 throw createLLMError(message, 'RATE_LIMITED', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: true,
                     retryAfterMs: 60000,
@@ -545,19 +545,19 @@ export class OpenRouterProvider {
             case 400:
                 if (errorCode === 'context_length_exceeded' || errorType === 'invalid_request_error') {
                     throw createLLMError(message, 'CONTEXT_LENGTH_EXCEEDED', {
-                        provider: 'openai',
+                        provider: 'openrouter',
                         model,
                         retryable: false,
                     });
                 }
                 throw createLLMError(message, 'UNKNOWN', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: false,
                 });
             case 404:
                 throw createLLMError(message, 'MODEL_NOT_FOUND', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: false,
                 });
@@ -565,14 +565,14 @@ export class OpenRouterProvider {
             case 502:
             case 503:
                 throw createLLMError(message, 'PROVIDER_UNAVAILABLE', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: true,
                     retryAfterMs: 5000,
                 });
             default:
                 throw createLLMError(message, 'UNKNOWN', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     model,
                     retryable: false,
                 });
@@ -594,7 +594,7 @@ export class OpenRouterProvider {
         catch (error) {
             if (error instanceof Error && error.name === 'AbortError') {
                 throw createLLMError('Request timed out', 'TIMEOUT', {
-                    provider: 'openai',
+                    provider: 'openrouter',
                     retryable: true,
                 });
             }

package/dist/validation/conservation-guard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Conservation Guard (Phoenix essay 14 "UI Is a Conservation Layer", ADR-114)
+ *
+ * AQE's human/agent-facing surfaces — CLI commands, output schemas, MCP tools,
+ * the dashboard — are its conservation layer: users and CI pipelines build muscle
+ * memory and scripts around them. Internals may regenerate freely; these surfaces
+ * must change slowly and ADDITIVELY. This module diffs a captured baseline against
+ * the current surface and flags breaking removals/renames that are not in the
+ * deprecation registry.
+ *
+ * Pure functions only — extraction + I/O live in scripts/conservation-guard.ts.
+ */
+export interface SurfaceDiff {
+    surface: string;
+    /** Entries present now but not in the baseline — additive, always allowed. */
+    added: string[];
+    /** Entries removed from the baseline and NOT in the deprecation registry — breaking. */
+    removedBreaking: string[];
+    /** Entries removed but listed as deprecated — an allowed, deliberate removal. */
+    removedDeprecated: string[];
+    /** True when there are no breaking removals. */
+    clean: boolean;
+}
+/**
+ * Diff one surface. Additive changes pass; a removal/rename is breaking unless the
+ * removed entry appears in `deprecated` (the deprecation window has been honored).
+ */
+export declare function diffSurface(surface: string, baseline: string[], current: string[], deprecated?: string[]): SurfaceDiff;
+export interface ConservationReport {
+    diffs: SurfaceDiff[];
+    clean: boolean;
+    /** Total breaking removals across all surfaces. */
+    breakingCount: number;
+}
+/** Aggregate per-surface diffs into an overall verdict. */
+export declare function aggregate(diffs: SurfaceDiff[]): ConservationReport;
+/** Human-readable report (used by the CLI guard and CI logs). */
+export declare function formatReport(report: ConservationReport): string;
+//# sourceMappingURL=conservation-guard.d.ts.map