@wildo-ai/saas-backend-lib 1.0.1

package/src/__tests__/integration/prompt-compiler.integration.test.ts

@@ -0,0 +1,723 @@
+/**
+ * Integration Tests for Prompt Compiler Backend Service
+ *
+ * Tests the PromptCompilerBackendService from AGENT_SYSTEM_ENHANCEMENT_V3:
+ * - 10-section prompt precedence order
+ * - XML, Markdown, and Roles format rendering
+ * - Context curation integration
+ * - PromptSpec field compilation
+ * - Skill type baseline instructions
+ *
+ * NOTE: These tests require @wildo-ai/saas-models to import without errors.
+ * If tests fail with "Invalid relationship configuration" errors,
+ * the relationship definitions in resources-registry.shared.core.definitions.ts
+ * need to be fixed first (specifically the applications → emailTemplates relationship).
+ */
+
+import 'reflect-metadata';
+import { Container } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+import { MockErrorBuilderService } from '~wildo-backend-lib/errors/services/__tests__/mock-error-builder.service';
+import { MockAppConfigurationService } from '~wildo-backend-lib/config/services/__tests__/mock-app-configuration.service';
+import { MockExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/__tests__/mock-external-providers-registry.service';
+
+// Import services
+import { PromptCompilerBackendService } from '~wildo-backend-lib/flows-actors/services/prompt-compiler.backend.service';
+import { ContextCurationBackendService } from '~wildo-backend-lib/flows-actors/services/context-curation.backend.service';
+
+// Import models
+// Note: Using @wildo-ai/saas-models requires full module initialization
+// If tests fail due to relationship config errors, update imports to use direct paths
+import {
+  FlowsActors_Agent,
+  FlowsActors_Agent_Invocation,
+  FlowsActors_Agent_Skill_Type,
+  FlowsActors_Agent_ConstraintType,
+  FlowsActors_Agent_UncertaintyPolicy,
+  FlowsActors_Agent_Verbosity,
+  FlowsActors_Agent_Tone,
+  FlowsActors_IO_PartKind,
+  AppsBlueprint_FileFormat,
+  PromptIR_CompiledPrompt,
+  PromptIR_ContextItem,
+  PromptIR_ContextSourceKind,
+  PromptIR_TrustLevel,
+} from '@wildo-ai/saas-models';
+import {
+  LLMProvider_PromptFormat,
+  LLMProvider_Profile,
+} from '@wildo-ai/external-connectors-models';
+
+// =============================================================================
+// TEST CONTAINER
+// =============================================================================
+
+function createPromptCompilerTestContainer(): Container {
+  const container = new Container({
+    defaultScope: 'Singleton',
+  });
+
+  // Bind mocks
+  container.bind(SAAS_SERVICE_TYPES.Logger).toConstantValue(new MockLoggerService());
+  container.bind(SAAS_SERVICE_TYPES.ErrorBuilderService).toConstantValue(new MockErrorBuilderService());
+  container.bind(SAAS_SERVICE_TYPES.AppConfigService).toConstantValue(new MockAppConfigurationService());
+
+  // Mock external providers registry
+  const mockExternalProvidersRegistry = new MockExternalProvidersRegistryBackendService();
+  container.bind(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)
+    .toConstantValue(mockExternalProvidersRegistry);
+
+  // Real context curation service
+  container.bind(SAAS_SERVICE_TYPES.ContextCurationService)
+    .to(ContextCurationBackendService)
+    .inSingletonScope();
+
+  // Real prompt compiler service
+  container.bind(SAAS_SERVICE_TYPES.PromptCompilerService)
+    .to(PromptCompilerBackendService)
+    .inSingletonScope();
+
+  return container;
+}
+
+// =============================================================================
+// TEST FIXTURES
+// =============================================================================
+
+function createTestAgent(overrides?: Partial<FlowsActors_Agent>): FlowsActors_Agent {
+  return {
+    _id: 'test-agent-id',
+    ref: 'test-agent',
+    displayName: 'Test Agent',
+    config: {
+      providerRef: 'anthropic',
+      modelRef: 'claude-3-opus',
+      temperature: 0.7,
+    },
+    promptSpec: {
+      role: 'You are a helpful test assistant',
+      skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+      instructions: ['Be helpful', 'Be accurate'],
+    },
+    capabilities: {
+      tools: {
+        enabled: false,
+        functionRefs: [],
+      },
+    },
+    ...(overrides as any),
+  };
+}
+
+function createTestInvocation(): FlowsActors_Agent_Invocation<any, any, any> {
+  return {
+    _id: 'test-invocation-id',
+    agentRef: 'test-agent',
+    status: 'PENDING',
+    input: { prompt: 'Test prompt' },
+    output: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function createTestContextItem(id: string, content: string): PromptIR_ContextItem {
+  return {
+    id,
+    content,
+    trust: PromptIR_TrustLevel.VERIFIED,
+    sourceKind: PromptIR_ContextSourceKind.DOCUMENT,
+    relevance: 0.9,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('PromptCompilerBackendService Integration', () => {
+  let container: Container;
+  let promptCompiler: PromptCompilerBackendService;
+  let mockProvidersRegistry: MockExternalProvidersRegistryBackendService;
+
+  beforeEach(() => {
+    container = createPromptCompilerTestContainer();
+    promptCompiler = container.get(SAAS_SERVICE_TYPES.PromptCompilerService);
+    mockProvidersRegistry = container.get(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService);
+  });
+
+  afterEach(() => {
+    mockProvidersRegistry.reset();
+  });
+
+  // ===========================================================================
+  // BASIC COMPILATION
+  // ===========================================================================
+
+  describe('Basic Compilation', () => {
+    it('should compile a minimal agent successfully', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+      const context: PromptIR_ContextItem[] = [];
+
+      const result = await promptCompiler.compile(agent, invocation, context, 'Test user prompt');
+
+      expect(result).toBeDefined();
+      expect(result.systemPrompt).toBeDefined();
+      expect(result.userPrompt).toContain('Test user prompt');
+    });
+
+    it('should include agent role in system prompt', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('You are a helpful test assistant');
+    });
+
+    it('should include agent instructions in system prompt', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Be helpful');
+      expect(result.systemPrompt).toContain('Be accurate');
+    });
+  });
+
+  // ===========================================================================
+  // PROMPT SPEC FIELD COMPILATION
+  // ===========================================================================
+
+  describe('PromptSpec Field Compilation', () => {
+    it('should compile constraints in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Security analyst',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          constraints: [
+            {
+              id: 'sec-1',
+              text: 'Never expose credentials',
+              type: FlowsActors_Agent_ConstraintType.SECURITY,
+              onViolation: 'refuse',
+            },
+            {
+              id: 'priv-1',
+              text: 'Do not output PII',
+              type: FlowsActors_Agent_ConstraintType.PRIVACY,
+              onViolation: 'refuse',
+            },
+          ],
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Never expose credentials');
+      expect(result.systemPrompt).toContain('Do not output PII');
+    });
+
+    it('should compile goal in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Test agent',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          goal: 'Identify security vulnerabilities in the provided code',
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Identify security vulnerabilities');
+    });
+
+    it('should compile output specification in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Report generator',
+          skillType: FlowsActors_Agent_Skill_Type.GENERATION,
+          instructions: [],
+          output: {
+            type: FlowsActors_IO_PartKind.FILE,
+            fileFormat: AppsBlueprint_FileFormat.MARKDOWN,
+            lengthGuidance: FlowsActors_Agent_Verbosity.HIGH,
+            includeReasoning: true,
+            requiredSections: ['summary', 'findings', 'recommendations'],
+          },
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toMatch(/markdown/i);
+      expect(result.systemPrompt).toContain('summary');
+      expect(result.systemPrompt).toContain('findings');
+    });
+
+    it('should compile uncertainty policy in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Decision maker',
+          skillType: FlowsActors_Agent_Skill_Type.DECISION,
+          instructions: [],
+          uncertainty: {
+            policy: FlowsActors_Agent_UncertaintyPolicy.CONSERVATIVE,
+            confidenceThreshold: 0.9,
+          },
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('conservative');
+      expect(result.systemPrompt).toContain('0.9');
+    });
+
+    it('should compile out of scope items in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Code reviewer',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          outOfScope: ['Do not provide exploit code', 'Do not execute code'],
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Do not provide exploit code');
+      expect(result.systemPrompt).toContain('Do not execute code');
+    });
+
+    it('should compile examples in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'SQL analyzer',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          examples: [
+            {
+              input: 'SELECT * FROM users WHERE id = ' + "'1' OR '1'='1'",
+              output: 'SQL Injection vulnerability detected',
+              explanation: 'User input is concatenated directly into SQL query',
+            },
+          ],
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('SQL Injection vulnerability detected');
+      expect(result.systemPrompt).toContain('concatenated directly');
+    });
+
+    it('should compile style settings in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Technical writer',
+          skillType: FlowsActors_Agent_Skill_Type.GENERATION,
+          instructions: [],
+          style: {
+            verbosity: FlowsActors_Agent_Verbosity.MEDIUM,
+            tone: FlowsActors_Agent_Tone.TECHNICAL,
+          },
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('medium');
+      expect(result.systemPrompt).toContain('technical');
+    });
+
+    it('should compile hints in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Advisor',
+          skillType: FlowsActors_Agent_Skill_Type.CHAT,
+          instructions: [],
+          hints: ['Prefer accuracy over speed', 'Ask for clarification when needed'],
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Prefer accuracy over speed');
+      expect(result.systemPrompt).toContain('Ask for clarification');
+    });
+
+    it('should compile persona in system prompt', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Senior Security Engineer',
+          persona: 'Experienced and thorough, with 15 years in application security',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+        },
+      });
+      const invocation = createTestInvocation();
+
+      const result = await promptCompiler.compile(agent, invocation, [], 'Test');
+
+      expect(result.systemPrompt).toContain('Senior Security Engineer');
+      expect(result.systemPrompt).toContain('15 years in application security');
+    });
+  });
+
+  // ===========================================================================
+  // SKILL TYPE BASELINE INSTRUCTIONS
+  // ===========================================================================
+
+  describe('Skill Type Baseline Instructions', () => {
+    it('should include ANALYSIS baseline instructions', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Analyst',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('analysis');
+    });
+
+    it('should include GENERATION baseline instructions', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Generator',
+          skillType: FlowsActors_Agent_Skill_Type.GENERATION,
+          instructions: [],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('generation');
+    });
+
+    it('should include TRANSFORMATION baseline instructions', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Transformer',
+          skillType: FlowsActors_Agent_Skill_Type.TRANSFORMATION,
+          instructions: [],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('transformation');
+    });
+
+    it('should include DECISION baseline instructions', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Decider',
+          skillType: FlowsActors_Agent_Skill_Type.DECISION,
+          instructions: [],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('decision');
+    });
+
+    it('should include CHAT baseline instructions', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Chatter',
+          skillType: FlowsActors_Agent_Skill_Type.CHAT,
+          instructions: [],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('conversation');
+    });
+
+    it('should not add baseline for CUSTOM skill type', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Custom Agent',
+          skillType: FlowsActors_Agent_Skill_Type.CUSTOM,
+          instructions: ['Only my custom instruction'],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      // Should have custom instruction but no standard baseline
+      expect(result.systemPrompt).toContain('Only my custom instruction');
+    });
+  });
+
+  // ===========================================================================
+  // FORMAT RENDERING
+  // ===========================================================================
+
+  describe('Format Rendering', () => {
+    it('should render XML format for Anthropic provider', async () => {
+      const agent = createTestAgent({
+        config: {
+          providerRef: 'anthropic',
+          modelRef: 'claude-3-opus',
+          temperature: 0.7,
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      // XML format uses tags
+      expect(result.systemPrompt).toContain('<role>');
+      expect(result.systemPrompt).toContain('</role>');
+    });
+
+    it('should render Markdown format when specified via override', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Test role',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          promptFormatOverride: LLMProvider_PromptFormat.MARKDOWN_HEADINGS,
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      // Markdown format uses ## headings
+      expect(result.systemPrompt).toContain('## ');
+    });
+
+    it('should infer XML format from provider name containing "claude"', async () => {
+      const agent = createTestAgent({
+        config: {
+          providerRef: 'my-claude-provider',
+          modelRef: 'claude-3',
+          temperature: 0.5,
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.systemPrompt).toContain('<role>');
+    });
+
+    it('should infer Roles format from provider name containing "openai"', async () => {
+      const agent = createTestAgent({
+        config: {
+          providerRef: 'openai-gpt4',
+          modelRef: 'gpt-4',
+          temperature: 0.5,
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      // Roles format uses [SYSTEM] markers or similar
+      // Check it doesn't use XML tags
+      expect(result.systemPrompt).not.toContain('<role>');
+    });
+  });
+
+  // ===========================================================================
+  // CONTEXT INTEGRATION
+  // ===========================================================================
+
+  describe('Context Integration', () => {
+    it('should include context items in user prompt', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+      const context = [
+        createTestContextItem('ctx-1', 'Important document content here'),
+      ];
+
+      const result = await promptCompiler.compile(agent, invocation, context, 'Analyze this');
+
+      // Context should be in user prompt section
+      expect(result.userPrompt).toContain('Important document content');
+    });
+
+    it('should handle multiple context items', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+      const context = [
+        createTestContextItem('ctx-1', 'First document'),
+        createTestContextItem('ctx-2', 'Second document'),
+        createTestContextItem('ctx-3', 'Third document'),
+      ];
+
+      const result = await promptCompiler.compile(agent, invocation, context, 'Analyze these');
+
+      expect(result.userPrompt).toContain('First document');
+      expect(result.userPrompt).toContain('Second document');
+      expect(result.userPrompt).toContain('Third document');
+    });
+
+    it('should apply curation config to context', async () => {
+      const agent = createTestAgent({
+        promptSpec: {
+          role: 'Curating agent',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          instructions: [],
+          curation: {
+            maxItems: 2,
+            minRelevance: 0.5,
+          },
+        },
+      });
+      const invocation = createTestInvocation();
+      // Create 5 items - should be reduced to 2 by curation
+      const context = [
+        createTestContextItem('ctx-1', 'Item 1'),
+        createTestContextItem('ctx-2', 'Item 2'),
+        createTestContextItem('ctx-3', 'Item 3'),
+        createTestContextItem('ctx-4', 'Item 4'),
+        createTestContextItem('ctx-5', 'Item 5'),
+      ];
+
+      const result = await promptCompiler.compile(agent, invocation, context, 'Test');
+
+      // Check metadata shows curation happened
+      expect(result.metadata?.contextItemCount).toBe(5);
+    });
+
+    it('should maintain trust level separation in context', async () => {
+      const agent = createTestAgent();
+      const invocation = createTestInvocation();
+
+      const verifiedItem: PromptIR_ContextItem = {
+        id: 'verified-1',
+        sourceKind: PromptIR_ContextSourceKind.DOCUMENT,
+        trust: PromptIR_TrustLevel.VERIFIED,
+        content: 'Verified trusted content',
+        relevance: 0.9,
+        timestamp: new Date().toISOString(),
+      };
+
+      const userItem: PromptIR_ContextItem = {
+        id: 'user-1',
+        sourceKind: PromptIR_ContextSourceKind.USER_INPUT,
+        trust: PromptIR_TrustLevel.USER_PROVIDED,
+        content: 'User provided content',
+        relevance: 0.9,
+        timestamp: new Date().toISOString(),
+      };
+
+      const result = await promptCompiler.compile(agent, invocation, [verifiedItem, userItem], 'Test');
+
+      // Both should be included
+      expect(result.userPrompt).toContain('Verified trusted content');
+      expect(result.userPrompt).toContain('User provided content');
+    });
+  });
+
+  // ===========================================================================
+  // PRECEDENCE ORDER VERIFICATION (XML FORMAT)
+  // ===========================================================================
+
+  describe('10-Section Precedence Order (XML Format)', () => {
+    it('should render sections in correct precedence order', async () => {
+      const agent = createTestAgent({
+        config: {
+          providerRef: 'anthropic',
+          modelRef: 'claude-3',
+          temperature: 0,
+        },
+        promptSpec: {
+          role: 'Full featured agent',
+          persona: 'Expert persona',
+          skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+          constraints: [{ id: 'c1', text: 'Constraint text', type: FlowsActors_Agent_ConstraintType.SECURITY, onViolation: 'refuse' }],
+          goal: 'The goal statement',
+          output: { includeReasoning: true },
+          instructions: ['Instruction 1'],
+          uncertainty: { policy: FlowsActors_Agent_UncertaintyPolicy.ASK },
+          outOfScope: ['Out of scope item'],
+          examples: [{ input: 'Ex input', output: 'Ex output' }],
+          style: { verbosity: FlowsActors_Agent_Verbosity.HIGH },
+          hints: ['Hint text'],
+        },
+      });
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+      const prompt = result.systemPrompt;
+
+      // Verify order by checking relative positions
+      const rolePos = prompt.indexOf('<role>');
+      const personaPos = prompt.indexOf('<persona>');
+      const constraintsPos = prompt.indexOf('<constraints>');
+      const goalPos = prompt.indexOf('<goal>');
+      const outputPos = prompt.indexOf('<output_format>');
+      const instructionsPos = prompt.indexOf('<instructions>');
+      const uncertaintyPos = prompt.indexOf('<uncertainty>');
+      const outOfScopePos = prompt.indexOf('<out_of_scope>');
+      const examplesPos = prompt.indexOf('<examples>');
+      const stylePos = prompt.indexOf('<style>');
+      const hintsPos = prompt.indexOf('<hints>');
+
+      // Precedence order: role < persona < constraints < goal < output < instructions < uncertainty < outOfScope < examples < style < hints
+      expect(rolePos).toBeLessThan(personaPos);
+      expect(personaPos).toBeLessThan(constraintsPos);
+      expect(constraintsPos).toBeLessThan(goalPos);
+      expect(goalPos).toBeLessThan(outputPos);
+      expect(outputPos).toBeLessThan(instructionsPos);
+      expect(instructionsPos).toBeLessThan(uncertaintyPos);
+      expect(uncertaintyPos).toBeLessThan(outOfScopePos);
+      expect(outOfScopePos).toBeLessThan(examplesPos);
+      expect(examplesPos).toBeLessThan(stylePos);
+      expect(stylePos).toBeLessThan(hintsPos);
+    });
+  });
+
+  // ===========================================================================
+  // METADATA
+  // ===========================================================================
+
+  describe('Compilation Metadata', () => {
+    it('should include format in metadata', async () => {
+      const agent = createTestAgent();
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.format).toBeDefined();
+    });
+
+    it('should include context counts in metadata', async () => {
+      const agent = createTestAgent();
+      const context = [
+        createTestContextItem('ctx-1', 'Content 1'),
+        createTestContextItem('ctx-2', 'Content 2'),
+      ];
+
+      const result = await promptCompiler.compile(agent, createTestInvocation(), context, 'Test');
+
+      expect(result.metadata?.contextItemCount).toBe(2);
+    });
+
+    it('should include compiled timestamp', async () => {
+      const agent = createTestAgent();
+      const result = await promptCompiler.compile(agent, createTestInvocation(), [], 'Test');
+
+      expect(result.metadata?.compiledAt).toBeDefined();
+      expect(new Date(result.metadata!.compiledAt!)).toBeInstanceOf(Date);
+    });
+  });
+});