principles-disciple 1.52.0 → 1.53.0

package/tests/core/observability.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { calculateBaselines } from '../../src/core/observability.js';
+import type { ObservabilityBaselines } from '../../src/core/observability.js';
+import { loadLedger, saveLedger } from '../../src/core/principle-tree-ledger.js';
+import type { HybridLedgerStore } from '../../src/core/principle-tree-ledger.js';
+import { safeRmDir } from '../test-utils.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pd-observability-test-'));
+}
+
+function createEmptyStore(): HybridLedgerStore {
+  return {
+    trainingStore: {},
+    tree: {
+      principles: {},
+      rules: {},
+      implementations: {},
+      metrics: {},
+      lastUpdated: new Date(0).toISOString(),
+    },
+  };
+}
+
+function createTestPrinciple(id: string, status: string, priority: string) {
+  return {
+    id,
+    version: 1,
+    text: `Test principle ${id}`,
+    triggerPattern: 'test',
+    action: 'verify',
+    status,
+    priority,
+    scope: 'general',
+    evaluability: 'manual_only' as const,
+    valueScore: 0,
+    adherenceRate: 0,
+    painPreventedCount: 0,
+    derivedFromPainIds: [] as string[],
+    ruleIds: [] as string[],
+    conflictsWithPrincipleIds: [] as string[],
+    createdAt: '2026-04-17T00:00:00.000Z',
+    updatedAt: '2026-04-17T00:00:00.000Z',
+  };
+}
+
+function seedStore(stateDir: string, store: HybridLedgerStore): void {
+  saveLedger(stateDir, store);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('calculateBaselines', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = createTmpDir();
+    seedStore(tmpDir, createEmptyStore());
+  });
+
+  afterEach(() => {
+    safeRmDir(tmpDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty state
+  // -------------------------------------------------------------------------
+
+  it('returns zeros for empty store', () => {
+    const baselines = calculateBaselines(tmpDir);
+
+    expect(baselines.principleStock).toBe(0);
+    expect(baselines.totalRules).toBe(0);
+    expect(baselines.totalImplementations).toBe(0);
+    expect(baselines.avgRulesPerPrinciple).toBe(0);
+    expect(baselines.avgImplementationsPerRule).toBe(0);
+    expect(baselines.totalPainEvents).toBe(0);
+    expect(baselines.associationRate).toBe(0);
+    expect(baselines.internalizedCount).toBe(0);
+    expect(baselines.internalizationRate).toBe(0);
+  });
+
+  it('sets calculatedAt to current time', () => {
+    const before = new Date().toISOString();
+    const baselines = calculateBaselines(tmpDir);
+    const after = new Date().toISOString();
+
+    expect(baselines.calculatedAt >= before).toBe(true);
+    expect(baselines.calculatedAt <= after).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Principle Stock
+  // -------------------------------------------------------------------------
+
+  it('counts all principles in the ledger', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'candidate', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'deprecated', 'P1');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.principleStock).toBe(3);
+  });
+
+  // -------------------------------------------------------------------------
+  // Structure
+  // -------------------------------------------------------------------------
+
+  it('calculates avgRulesPerPrinciple', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = {
+      ...createTestPrinciple('P-001', 'active', 'P1'),
+      ruleIds: ['R-001', 'R-002'],
+    };
+    store.tree.principles['P-002'] = {
+      ...createTestPrinciple('P-002', 'active', 'P1'),
+      ruleIds: ['R-003'],
+    };
+    store.tree.rules['R-001'] = { id: 'R-001', principleId: 'P-001', implementationIds: [] } as any;
+    store.tree.rules['R-002'] = { id: 'R-002', principleId: 'P-001', implementationIds: [] } as any;
+    store.tree.rules['R-003'] = { id: 'R-003', principleId: 'P-002', implementationIds: [] } as any;
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalRules).toBe(3);
+    expect(baselines.avgRulesPerPrinciple).toBe(1.5); // 3 rules / 2 principles
+  });
+
+  it('calculates avgImplementationsPerRule', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = {
+      ...createTestPrinciple('P-001', 'active', 'P1'),
+      ruleIds: ['R-001'],
+    };
+    store.tree.rules['R-001'] = {
+      id: 'R-001',
+      principleId: 'P-001',
+      implementationIds: ['I-001', 'I-002'],
+    } as any;
+    store.tree.implementations['I-001'] = { id: 'I-001', ruleId: 'R-001' } as any;
+    store.tree.implementations['I-002'] = { id: 'I-002', ruleId: 'R-001' } as any;
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalImplementations).toBe(2);
+    expect(baselines.avgImplementationsPerRule).toBe(2); // 2 impls / 1 rule
+  });
+
+  it('returns 0 for structure metrics when no principles exist', () => {
+    seedStore(tmpDir, createEmptyStore());
+    const baselines = calculateBaselines(tmpDir);
+
+    expect(baselines.avgRulesPerPrinciple).toBe(0);
+    expect(baselines.avgImplementationsPerRule).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Association Rate
+  // -------------------------------------------------------------------------
+
+  it('returns 0 association rate when no pain events exist', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalPainEvents).toBe(0);
+    expect(baselines.associationRate).toBe(0);
+  });
+
+  it('computes association rate as principles / pain events', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    seedStore(tmpDir, store);
+
+    // Create a trajectory DB with pain events
+    const dbPath = path.join(tmpDir, 'trajectory.db');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+    db.exec(`
+      CREATE TABLE pain_events (id TEXT PRIMARY KEY, created_at TEXT);
+      INSERT INTO pain_events VALUES ('pe-1', '2026-04-17T00:00:00Z');
+      INSERT INTO pain_events VALUES ('pe-2', '2026-04-17T00:01:00Z');
+      INSERT INTO pain_events VALUES ('pe-3', '2026-04-17T00:02:00Z');
+      INSERT INTO pain_events VALUES ('pe-4', '2026-04-17T00:03:00Z');
+    `);
+    db.close();
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalPainEvents).toBe(4);
+    expect(baselines.associationRate).toBe(0.5); // 2 principles / 4 pain events
+  });
+
+  // -------------------------------------------------------------------------
+  // Internalization Rate
+  // -------------------------------------------------------------------------
+
+  it('computes internalization rate from training store', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'candidate', 'P2');
+    store.trainingStore['P-001'] = {
+      principleId: 'P-001',
+      evaluability: 'deterministic',
+      applicableOpportunityCount: 10,
+      observedViolationCount: 0,
+      complianceRate: 1.0,
+      violationTrend: 0,
+      generatedSampleCount: 5,
+      approvedSampleCount: 5,
+      includedTrainRunIds: ['run-1'],
+      deployedCheckpointIds: ['ckpt-1'],
+      internalizationStatus: 'internalized',
+    };
+    store.trainingStore['P-002'] = {
+      principleId: 'P-002',
+      evaluability: 'weak_heuristic',
+      applicableOpportunityCount: 3,
+      observedViolationCount: 1,
+      complianceRate: 0.67,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'in_training',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizedCount).toBe(1);
+    // 1 internalized / 3 total principles = 0.333
+    expect(baselines.internalizationRate).toBeGreaterThan(0.33);
+    expect(baselines.internalizationRate).toBeLessThanOrEqual(0.334);
+  });
+
+  it('returns 0 internalization rate when no principles are internalized', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.trainingStore['P-001'] = {
+      principleId: 'P-001',
+      evaluability: 'manual_only',
+      applicableOpportunityCount: 0,
+      observedViolationCount: 0,
+      complianceRate: 0,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'prompt_only',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizedCount).toBe(0);
+    expect(baselines.internalizationRate).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Distributions
+  // -------------------------------------------------------------------------
+
+  it('computes status distribution', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'candidate', 'P1');
+    store.tree.principles['P-004'] = createTestPrinciple('P-004', 'deprecated', 'P2');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.statusDistribution.active).toBe(2);
+    expect(baselines.statusDistribution.candidate).toBe(1);
+    expect(baselines.statusDistribution.deprecated).toBe(1);
+  });
+
+  it('computes priority distribution', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P0');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P1');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'active', 'P1');
+    store.tree.principles['P-004'] = createTestPrinciple('P-004', 'active', 'P2');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.priorityDistribution.P0).toBe(1);
+    expect(baselines.priorityDistribution.P1).toBe(2);
+    expect(baselines.priorityDistribution.P2).toBe(1);
+  });
+
+  it('computes internalization distribution', () => {
+    const store = createEmptyStore();
+    store.trainingStore['p-1'] = {
+      principleId: 'p-1',
+      evaluability: 'deterministic',
+      applicableOpportunityCount: 5,
+      observedViolationCount: 0,
+      complianceRate: 1.0,
+      violationTrend: 0,
+      generatedSampleCount: 3,
+      approvedSampleCount: 3,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'internalized',
+    };
+    store.trainingStore['p-2'] = {
+      principleId: 'p-2',
+      evaluability: 'manual_only',
+      applicableOpportunityCount: 0,
+      observedViolationCount: 0,
+      complianceRate: 0,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'prompt_only',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizationDistribution.internalized).toBe(1);
+    expect(baselines.internalizationDistribution.prompt_only).toBe(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // Persistence
+  // -------------------------------------------------------------------------
+
+  it('persists baselines to .state/baselines.json', () => {
+    calculateBaselines(tmpDir);
+
+    const baselinesPath = path.join(tmpDir, 'baselines.json');
+    expect(fs.existsSync(baselinesPath)).toBe(true);
+
+    const raw = JSON.parse(fs.readFileSync(baselinesPath, 'utf8')) as ObservabilityBaselines;
+    expect(raw.principleStock).toBe(0);
+    expect(raw.calculatedAt).toBeDefined();
+  });
+
+  it('overwrites previous baselines on recalculation', () => {
+    // First calculation with empty store
+    calculateBaselines(tmpDir);
+
+    // Add a principle
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    seedStore(tmpDir, store);
+
+    // Second calculation
+    calculateBaselines(tmpDir);
+
+    const baselinesPath = path.join(tmpDir, 'baselines.json');
+    const raw = JSON.parse(fs.readFileSync(baselinesPath, 'utf8')) as ObservabilityBaselines;
+    expect(raw.principleStock).toBe(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // Edge cases
+  // -------------------------------------------------------------------------
+
+  it('handles missing state directory gracefully', () => {
+    const missingDir = path.join(tmpDir, 'nonexistent');
+    // loadLedger handles missing dirs by returning empty store
+    const baselines = calculateBaselines(missingDir);
+    expect(baselines.principleStock).toBe(0);
+  });
+});

package/tests/core/pain-signal-adapter.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import type { PainSignalAdapter } from '../../src/core/pain-signal-adapter.js';
+import type { PainSignal } from '../../src/core/pain-signal.js';
+import { validatePainSignal } from '../../src/core/pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Mock Framework Event
+// ---------------------------------------------------------------------------
+
+/** Simulated framework-specific event for testing */
+interface MockToolCallEvent {
+  toolName: string;
+  success: boolean;
+  errorMessage?: string;
+  sessionId: string;
+  agentId: string;
+  timestamp: string;
+}
+
+// ---------------------------------------------------------------------------
+// Test Adapter Implementation
+// ---------------------------------------------------------------------------
+
+/** Test adapter that translates MockToolCallEvent to PainSignal */
+const mockAdapter: PainSignalAdapter<MockToolCallEvent> = {
+  capture(event: MockToolCallEvent): PainSignal | null {
+    // Per D-02: pure translation. Only failed tool calls produce signals.
+    if (event.success) return null;
+
+    // Return null for malformed events
+    if (!event.toolName || !event.errorMessage) return null;
+
+    return {
+      source: 'tool_failure',
+      score: 75,
+      timestamp: event.timestamp,
+      reason: `Tool ${event.toolName} failed: ${event.errorMessage}`,
+      sessionId: event.sessionId,
+      agentId: event.agentId,
+      traceId: `test-${Date.now()}`,
+      triggerTextPreview: event.errorMessage.slice(0, 100),
+      domain: 'coding',
+      severity: 'high',
+      context: { toolName: event.toolName },
+    };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function mockToolFailure(overrides: Partial<MockToolCallEvent> = {}): MockToolCallEvent {
+  return {
+    toolName: 'edit_file',
+    success: false,
+    errorMessage: 'File not found: test.ts',
+    sessionId: 'session-001',
+    agentId: 'main',
+    timestamp: '2026-04-17T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('PainSignalAdapter', () => {
+  it('captures a failed tool call as PainSignal', () => {
+    const result = mockAdapter.capture(mockToolFailure());
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe('tool_failure');
+  });
+
+  it('returns null for successful tool calls', () => {
+    const result = mockAdapter.capture({ success: true } as MockToolCallEvent);
+    expect(result).toBeNull();
+  });
+
+  it('returns null for malformed events missing toolName', () => {
+    const result = mockAdapter.capture({
+      success: false,
+      toolName: '',
+      errorMessage: 'err',
+      sessionId: 's-1',
+      agentId: 'a-1',
+      timestamp: '2026-04-17T00:00:00.000Z',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for malformed events missing errorMessage', () => {
+    const result = mockAdapter.capture({
+      success: false,
+      toolName: 'edit',
+      errorMessage: undefined,
+      sessionId: 's-1',
+      agentId: 'a-1',
+      timestamp: '2026-04-17T00:00:00.000Z',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('produces signals that pass validatePainSignal', () => {
+    const signal = mockAdapter.capture(mockToolFailure());
+    expect(signal).not.toBeNull();
+    const result = validatePainSignal(signal!);
+    expect(result.valid).toBe(true);
+  });
+
+  it('satisfies the PainSignalAdapter interface type contract', () => {
+    const adapter: PainSignalAdapter<MockToolCallEvent> = mockAdapter;
+    expect(typeof adapter.capture).toBe('function');
+  });
+});

package/tests/core/pain-signal.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect } from 'vitest';
+import {
+  PainSignalSchema,
+  validatePainSignal,
+  deriveSeverity,
+  type PainSignal,
+} from '../../src/core/pain-signal.js';
+import { Value } from '@sinclair/typebox/value';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Produces a valid minimal PainSignal object. */
+function validSignal(overrides: Partial<PainSignal> = {}): PainSignal {
+  return {
+    source: 'tool_failure',
+    score: 75,
+    timestamp: '2026-04-17T00:00:00.000Z',
+    reason: 'Build failed with exit code 1',
+    sessionId: 'session-001',
+    agentId: 'main',
+    traceId: 'trace-abc',
+    triggerTextPreview: 'npm run build',
+    domain: 'coding',
+    severity: 'high',
+    context: {},
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PainSignalSchema
+// ---------------------------------------------------------------------------
+
+describe('PainSignalSchema', () => {
+  it('accepts a valid signal', () => {
+    const signal = validSignal();
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+
+  it('rejects signal with missing required source', () => {
+    const signal = validSignal();
+    delete (signal as Record<string, unknown>).source;
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects signal with missing required reason', () => {
+    const signal = validSignal();
+    delete (signal as Record<string, unknown>).reason;
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects score below 0', () => {
+    const signal = validSignal({ score: -1 });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects score above 100', () => {
+    const signal = validSignal({ score: 101 });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects empty source string', () => {
+    const signal = validSignal({ source: '' });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects empty optional fields (sessionId, agentId, traceId, triggerTextPreview)', () => {
+    const signal = validSignal({
+      sessionId: '',
+      agentId: '',
+      traceId: '',
+      triggerTextPreview: '',
+    });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('accepts any string for domain', () => {
+    const signal = validSignal({ domain: 'writing' });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+
+  it('accepts context with mixed value types', () => {
+    const signal = validSignal({ context: { filePath: '/src/index.ts', lineCount: 42 } });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deriveSeverity
+// ---------------------------------------------------------------------------
+
+describe('deriveSeverity', () => {
+  it('returns "low" for scores 0-39', () => {
+    expect(deriveSeverity(0)).toBe('low');
+    expect(deriveSeverity(20)).toBe('low');
+    expect(deriveSeverity(39)).toBe('low');
+  });
+
+  it('returns "medium" for scores 40-69', () => {
+    expect(deriveSeverity(40)).toBe('medium');
+    expect(deriveSeverity(55)).toBe('medium');
+    expect(deriveSeverity(69)).toBe('medium');
+  });
+
+  it('returns "high" for scores 70-89', () => {
+    expect(deriveSeverity(70)).toBe('high');
+    expect(deriveSeverity(80)).toBe('high');
+    expect(deriveSeverity(89)).toBe('high');
+  });
+
+  it('returns "critical" for scores 90-100', () => {
+    expect(deriveSeverity(90)).toBe('critical');
+    expect(deriveSeverity(95)).toBe('critical');
+    expect(deriveSeverity(100)).toBe('critical');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validatePainSignal
+// ---------------------------------------------------------------------------
+
+describe('validatePainSignal', () => {
+  it('validates a correct signal and returns it typed', () => {
+    const input = validSignal();
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+    expect(result.signal).toEqual(input);
+  });
+
+  it('fills default domain when missing', () => {
+    const input = validSignal();
+    delete (input as Record<string, unknown>).domain;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.domain).toBe('coding');
+  });
+
+  it('fills default severity from score when missing', () => {
+    const input = validSignal({ score: 45 });
+    delete (input as Record<string, unknown>).severity;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.severity).toBe('medium');
+  });
+
+  it('fills default context when missing', () => {
+    const input = validSignal();
+    delete (input as Record<string, unknown>).context;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.context).toEqual({});
+  });
+
+  it('rejects non-object input', () => {
+    const result = validatePainSignal('not an object');
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('rejects null input', () => {
+    const result = validatePainSignal(null);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('rejects array input', () => {
+    const result = validatePainSignal([1, 2, 3]);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('reports errors for missing required fields', () => {
+    const result = validatePainSignal({});
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('rejects invalid score type', () => {
+    const result = validatePainSignal({ ...validSignal(), score: 'high' });
+    expect(result.valid).toBe(false);
+  });
+
+  it('rejects invalid severity value', () => {
+    const result = validatePainSignal({ ...validSignal(), severity: 'extreme' });
+    expect(result.valid).toBe(false);
+  });
+});