principles-disciple 1.52.0 → 1.54.0

package/src/service/evolution-worker.ts

@@ -18,6 +18,7 @@ import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import type { PrincipleEvaluability } from '../types/principle-tree-schema.js';
 export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { validatePainSignal, type PainSignalValidationResult } from '../core/pain-signal.js';
 
 // Re-export queue I/O (extracted to queue-io.ts)
 export { loadEvolutionQueue, saveEvolutionQueue, withQueueLock, acquireQueueLock, requireQueueLock } from './queue-io.js';
@@ -51,6 +52,7 @@ import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
 import { classifyFailure, type ClassifiableTaskKind } from './failure-classifier.js';
 import { recordPersistentFailure, resetFailureState, isTaskKindInCooldown } from './cooldown-strategy.js';
 import { reconcileStartup } from './startup-reconciler.js';
+import { clearPainFlag } from '../core/pain-lifecycle.js';
 import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
 import { OpenClawTrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
 
@@ -330,6 +332,27 @@ async function doEnqueuePainTask(
         return result;
     }
 
+    // Validate pain signal through TypeBox schema before enqueuing.
+    // Malformed signals are logged and skipped — they never enter the queue.
+    const signalInput = {
+        source: v.source,
+        score: v.score,
+        timestamp: new Date().toISOString(),
+        reason: v.reason,
+        sessionId: v.sessionId ?? undefined,
+        agentId: v.agentId ?? undefined,
+        traceId: v.traceId ?? undefined,
+        triggerTextPreview: v.preview,
+    };
+    const validation: PainSignalValidationResult = validatePainSignal(signalInput);
+    if (!validation.valid) {
+        result.skipped_reason = `invalid_pain_signal (${validation.errors.join('; ')})`;
+        if (logger) logger.warn(`[PD:EvolutionWorker] Pain signal validation failed, skipping enqueue: ${validation.errors.join('; ')}`);
+        SystemLogger.log(wctx.workspaceDir, 'PAIN_SIGNAL_INVALID', `Validation errors: ${validation.errors.join('; ')} | source=${v.source} score=${v.score}`);
+        clearPainFlag(wctx.workspaceDir);
+        return result;
+    }
+
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     const releaseLock = await requireQueueLock(queuePath, logger, 'checkPainFlag');
     try {
@@ -344,6 +367,7 @@ async function doEnqueuePainTask(
             result.enqueued = true;
             result.skipped_reason = 'duplicate';
             if (logger) logger.info(`[PD:EvolutionWorker] Duplicate pain task skipped for source=${v.source} preview=${v.preview || 'N/A'}`);
+            clearPainFlag(wctx.workspaceDir);
             return result;
         }
 
@@ -387,6 +411,7 @@ async function doEnqueuePainTask(
             enqueuedAt: nowIso,
         });
     } finally { releaseLock(); }
+    clearPainFlag(wctx.workspaceDir);
     return result;
 }
 
@@ -419,6 +444,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             if (isQueued) {
                 result.skipped_reason = 'already_queued';
                 if (logger) logger.info(`[PD:EvolutionWorker] Pain flag already queued (score=${score}, source=${source})`);
+                clearPainFlag(wctx.workspaceDir, painEventId);
                 return result;
             }
 
@@ -432,6 +458,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             result.exists = true;
             result.skipped_reason = `invalid_pain_flag (${contract.missingFields.join(', ') || contract.format})`;
             if (logger) logger.warn(`[PD:EvolutionWorker] Invalid pain flag skipped: ${result.skipped_reason}`);
+            clearPainFlag(wctx.workspaceDir);
             return result;
         }
 
@@ -472,6 +499,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
                     result.enqueued = true;
                     result.skipped_reason = 'already_queued';
                     if (logger) logger.info(`[PD:EvolutionWorker] Pain flag already queued (score=${jsonScore}, source=${jsonSource})`);
+                    clearPainFlag(wctx.workspaceDir, jsonPain.pain_event_id ? parseInt(jsonPain.pain_event_id, 10) : undefined);
                     return result;
                 }
 
@@ -763,9 +791,38 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
         }
 
         // V2: Migrate queue to current schema if needed
-        const queue: EvolutionQueueItem[] = migrateQueueToV2(rawQueue) as unknown as EvolutionQueueItem[];
+        let queue: EvolutionQueueItem[] = migrateQueueToV2(rawQueue) as unknown as EvolutionQueueItem[];
+
+        // Validate queue items — filter out malformed entries before processing.
+        // Malformed items are logged + skipped; they never crash the evolution cycle.
+        const beforeValidation = queue.length;
+        queue = queue.filter((item) => {
+            const errors: string[] = [];
+            if (!item.id || typeof item.id !== 'string') errors.push('missing/invalid id');
+            if (!item.source || typeof item.source !== 'string') errors.push('missing/invalid source');
+            if (typeof item.score !== 'number') errors.push('missing/invalid score');
+            if (!item.status || typeof item.status !== 'string') errors.push('missing/invalid status');
+            if (!item.taskKind || typeof item.taskKind !== 'string') errors.push('missing/invalid taskKind');
+            else {
+                const validTaskKinds = ['pain_diagnosis', 'sleep_reflection', 'model_eval', 'keyword_optimization'];
+                if (!validTaskKinds.includes(item.taskKind)) {
+                    errors.push(`invalid taskKind value '${item.taskKind}' (expected one of: ${validTaskKinds.join(', ')})`);
+                }
+            }
+            if (typeof item.retryCount !== 'number') errors.push('missing/invalid retryCount');
+            if (typeof item.maxRetries !== 'number') errors.push('missing/invalid maxRetries');
+            if (errors.length > 0) {
+                logger?.warn?.(`[PD:EvolutionWorker] Skipping malformed queue item: ${errors.join(', ')} | ${JSON.stringify(item).slice(0, 200)}`);
+                SystemLogger.log(wctx.workspaceDir, 'QUEUE_ITEM_MALFORMED', `Skipped: ${errors.join(', ')} | id=${item.id || 'N/A'}`);
+                return false;
+            }
+            return true;
+        });
+        if (queue.length < beforeValidation) {
+            logger?.info?.(`[PD:EvolutionWorker] Filtered ${beforeValidation - queue.length} malformed queue item(s)`);
+        }
 
-        let queueChanged = rawQueue.some(isLegacyQueueItem);
+        let queueChanged = rawQueue.some(isLegacyQueueItem) || queue.length < beforeValidation;
 
         // Guard: Skip keyword_optimization if one is already pending/in-progress (CORR-08)
         if (hasPendingTask(queue, 'keyword_optimization')) {

package/tests/core/evolution-hook.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import type { EvolutionHook, PrincipleCreatedEvent, PrinciplePromotedEvent } from '../../src/core/evolution-hook.js';
+import { noOpEvolutionHook } from '../../src/core/evolution-hook.js';
+import type { PainSignal } from '../../src/core/pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function validPainSignal(overrides: Partial<PainSignal> = {}): PainSignal {
+  return {
+    source: 'tool_failure',
+    score: 75,
+    timestamp: '2026-04-17T00:00:00.000Z',
+    reason: 'File not found',
+    sessionId: 'session-001',
+    agentId: 'main',
+    traceId: 'trace-001',
+    triggerTextPreview: 'File not found: test.ts',
+    domain: 'coding',
+    severity: 'high',
+    context: {},
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('EvolutionHook', () => {
+  it('implements all 3 methods', () => {
+    const calls: string[] = [];
+    const hook: EvolutionHook = {
+      onPainDetected(signal: PainSignal): void { calls.push(`pain:${signal.source}`); },
+      onPrincipleCreated(event: PrincipleCreatedEvent): void { calls.push(`created:${event.id}`); },
+      onPrinciplePromoted(event: PrinciplePromotedEvent): void { calls.push(`promoted:${event.id}`); },
+    };
+
+    hook.onPainDetected(validPainSignal());
+    hook.onPrincipleCreated({ id: 'p-1', text: 'Test principle', trigger: 'tool failure' });
+    hook.onPrinciplePromoted({ id: 'p-1', from: 'candidate', to: 'active' });
+
+    expect(calls).toEqual(['pain:tool_failure', 'created:p-1', 'promoted:p-1']);
+  });
+
+  it('onPainDetected receives a PainSignal', () => {
+    let received: PainSignal | undefined;
+    const hook: EvolutionHook = {
+      ...noOpEvolutionHook,
+      onPainDetected(signal: PainSignal): void { received = signal; },
+    };
+
+    const signal = validPainSignal();
+    hook.onPainDetected(signal);
+    expect(received).toEqual(signal);
+  });
+
+  it('onPrincipleCreated receives a PrincipleCreatedEvent', () => {
+    let received: PrincipleCreatedEvent | undefined;
+    const hook: EvolutionHook = {
+      ...noOpEvolutionHook,
+      onPrincipleCreated(event: PrincipleCreatedEvent): void { received = event; },
+    };
+
+    const event = { id: 'p-1', text: 'Test principle', trigger: 'tool failure' };
+    hook.onPrincipleCreated(event);
+    expect(received).toEqual(event);
+  });
+
+  it('onPrinciplePromoted receives a PrinciplePromotedEvent', () => {
+    let received: PrinciplePromotedEvent | undefined;
+    const hook: EvolutionHook = {
+      ...noOpEvolutionHook,
+      onPrinciplePromoted(event: PrinciplePromotedEvent): void { received = event; },
+    };
+
+    const event = { id: 'p-1', from: 'candidate', to: 'active' };
+    hook.onPrinciplePromoted(event);
+    expect(received).toEqual(event);
+  });
+});
+
+describe('noOpEvolutionHook', () => {
+  it('implements all 3 methods as no-ops', () => {
+    expect(() => {
+      noOpEvolutionHook.onPainDetected(validPainSignal());
+      noOpEvolutionHook.onPrincipleCreated({ id: 'p-1', text: 'Test', trigger: 'test' });
+      noOpEvolutionHook.onPrinciplePromoted({ id: 'p-1', from: 'candidate', to: 'active' });
+    }).not.toThrow();
+  });
+
+  it('can be spread to override individual methods', () => {
+    const calls: string[] = [];
+    const hook: EvolutionHook = {
+      ...noOpEvolutionHook,
+      onPainDetected(_signal: PainSignal): void { calls.push('pain'); },
+    };
+
+    hook.onPainDetected(validPainSignal());
+    hook.onPrincipleCreated({ id: 'p-1', text: 'Test', trigger: 'test' });
+
+    expect(calls).toEqual(['pain']);
+  });
+});
+
+describe('PrincipleCreatedEvent', () => {
+  it('has required fields: id, text, trigger', () => {
+    const event: PrincipleCreatedEvent = { id: 'p-1', text: 'Always verify', trigger: 'tool failure' };
+    expect(event.id).toBe('p-1');
+    expect(event.text).toBe('Always verify');
+    expect(event.trigger).toBe('tool failure');
+  });
+});
+
+describe('PrinciplePromotedEvent', () => {
+  it('has required fields: id, from, to', () => {
+    const event: PrinciplePromotedEvent = { id: 'p-1', from: 'candidate', to: 'active' };
+    expect(event.id).toBe('p-1');
+    expect(event.from).toBe('candidate');
+    expect(event.to).toBe('active');
+  });
+});

package/tests/core/file-storage-adapter.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { FileStorageAdapter } from '../../src/core/file-storage-adapter.js';
+import type { HybridLedgerStore } from '../../src/core/principle-tree-ledger.js';
+import { TREE_NAMESPACE, loadLedger } 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-file-storage-adapter-test-'));
+}
+
+function createEmptyStore(): HybridLedgerStore {
+  return {
+    trainingStore: {},
+    tree: {
+      principles: {},
+      rules: {},
+      implementations: {},
+      metrics: {},
+      lastUpdated: new Date(0).toISOString(),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('FileStorageAdapter', () => {
+  let tmpDir: string;
+  let adapter: FileStorageAdapter;
+
+  beforeEach(() => {
+    tmpDir = createTmpDir();
+    adapter = new FileStorageAdapter(tmpDir, tmpDir);
+  });
+
+  afterEach(() => {
+    safeRmDir(tmpDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // loadLedger
+  // -------------------------------------------------------------------------
+
+  describe('loadLedger', () => {
+    it('returns empty store when no file exists', async () => {
+      const store = await adapter.loadLedger();
+      expect(store.trainingStore).toEqual({});
+      expect(store.tree.principles).toEqual({});
+      expect(store.tree.rules).toEqual({});
+    });
+
+    it('loads existing persisted store', async () => {
+      const original = createEmptyStore();
+      original.tree.principles['P-001'] = {
+        id: 'P-001',
+        version: 1,
+        text: 'Write before delete',
+        triggerPattern: 'delete',
+        action: 'write first',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: 'deterministic',
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: '2026-04-17T00:00:00.000Z',
+        updatedAt: '2026-04-17T00:00:00.000Z',
+      };
+
+      // Persist using the low-level ledger to seed the file
+      await adapter.saveLedger(original);
+      const loaded = await adapter.loadLedger();
+      expect(loaded.tree.principles['P-001']).toBeDefined();
+      expect(loaded.tree.principles['P-001'].text).toBe('Write before delete');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // saveLedger
+  // -------------------------------------------------------------------------
+
+  describe('saveLedger', () => {
+    it('persists store to disk', async () => {
+      const store = createEmptyStore();
+      store.trainingStore['test-principle'] = {
+        principleId: 'test-principle',
+        evaluability: 'manual_only',
+        applicableOpportunityCount: 0,
+        observedViolationCount: 0,
+        complianceRate: 0,
+        violationTrend: 0,
+        generatedSampleCount: 0,
+        approvedSampleCount: 0,
+        includedTrainRunIds: [],
+        deployedCheckpointIds: [],
+        internalizationStatus: 'prompt_only',
+      };
+
+      await adapter.saveLedger(store);
+
+      // Verify file exists and contains the data
+      const filePath = path.join(tmpDir, 'principle_training_state.json');
+      expect(fs.existsSync(filePath)).toBe(true);
+      const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      expect(raw['test-principle']).toBeDefined();
+      expect(raw[TREE_NAMESPACE]).toBeDefined();
+    });
+
+    it('round-trips data through save and load', async () => {
+      const store = createEmptyStore();
+      store.trainingStore['p-1'] = {
+        principleId: 'p-1',
+        evaluability: 'weak_heuristic',
+        applicableOpportunityCount: 5,
+        observedViolationCount: 2,
+        complianceRate: 0.6,
+        violationTrend: -0.1,
+        generatedSampleCount: 3,
+        approvedSampleCount: 2,
+        includedTrainRunIds: ['run-1'],
+        deployedCheckpointIds: [],
+        internalizationStatus: 'in_training',
+      };
+
+      await adapter.saveLedger(store);
+      const loaded = await adapter.loadLedger();
+      expect(loaded.trainingStore['p-1'].evaluability).toBe('weak_heuristic');
+      expect(loaded.trainingStore['p-1'].applicableOpportunityCount).toBe(5);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // mutateLedger
+  // -------------------------------------------------------------------------
+
+  describe('mutateLedger', () => {
+    it('reads, mutates, and writes atomically', async () => {
+      // Start with empty store
+      await adapter.saveLedger(createEmptyStore());
+
+      const result = await adapter.mutateLedger((store) => {
+        store.tree.principles['P-002'] = {
+          id: 'P-002',
+          version: 1,
+          text: 'Test principle',
+          triggerPattern: 'test',
+          action: 'do something',
+          status: 'candidate',
+          priority: 'P2',
+          scope: 'general',
+          evaluability: 'manual_only',
+          valueScore: 0,
+          adherenceRate: 0,
+          painPreventedCount: 0,
+          derivedFromPainIds: [],
+          ruleIds: [],
+          conflictsWithPrincipleIds: [],
+          createdAt: '2026-04-17T00:00:00.000Z',
+          updatedAt: '2026-04-17T00:00:00.000Z',
+        };
+        return 42;
+      });
+
+      expect(result).toBe(42);
+      const loaded = await adapter.loadLedger();
+      expect(loaded.tree.principles['P-002']).toBeDefined();
+      expect(loaded.tree.principles['P-002'].text).toBe('Test principle');
+    });
+
+    it('returns the value from the mutate function', async () => {
+      await adapter.saveLedger(createEmptyStore());
+
+      const count = await adapter.mutateLedger((store) => {
+        return Object.keys(store.tree.principles).length;
+      });
+
+      expect(count).toBe(0);
+    });
+
+    it('supports async mutate functions', async () => {
+      await adapter.saveLedger(createEmptyStore());
+
+      const result = await adapter.mutateLedger(async (store) => {
+        // Simulate async work
+        await new Promise((r) => setTimeout(r, 10));
+        store.trainingStore['async-test'] = {
+          principleId: 'async-test',
+          evaluability: 'deterministic',
+          applicableOpportunityCount: 1,
+          observedViolationCount: 0,
+          complianceRate: 1.0,
+          violationTrend: 0,
+          generatedSampleCount: 0,
+          approvedSampleCount: 0,
+          includedTrainRunIds: [],
+          deployedCheckpointIds: [],
+          internalizationStatus: 'prompt_only',
+        };
+        return 'async-done';
+      });
+
+      expect(result).toBe('async-done');
+      const loaded = await adapter.loadLedger();
+      expect(loaded.trainingStore['async-test']).toBeDefined();
+    });
+
+    it('persists via atomicWriteFileSync (file is not corrupted)', async () => {
+      await adapter.saveLedger(createEmptyStore());
+
+      await adapter.mutateLedger((store) => {
+        store.tree.principles['P-003'] = {
+          id: 'P-003',
+          version: 1,
+          text: 'Atomic write test',
+          triggerPattern: 'test',
+          action: 'verify atomicity',
+          status: 'candidate',
+          priority: 'P1',
+          scope: 'general',
+          evaluability: 'manual_only',
+          valueScore: 0,
+          adherenceRate: 0,
+          painPreventedCount: 0,
+          derivedFromPainIds: [],
+          ruleIds: [],
+          conflictsWithPrincipleIds: [],
+          createdAt: '2026-04-17T00:00:00.000Z',
+          updatedAt: '2026-04-17T00:00:00.000Z',
+        };
+      });
+
+      // Verify no leftover temp file
+      const filePath = path.join(tmpDir, 'principle_training_state.json');
+      expect(fs.existsSync(filePath + '.tmp')).toBe(false);
+      expect(fs.existsSync(filePath)).toBe(true);
+
+      // File is valid JSON
+      const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      expect(raw[TREE_NAMESPACE].principles['P-003']).toBeDefined();
+    });
+
+    it('is compatible with low-level loadLedger', async () => {
+      await adapter.saveLedger(createEmptyStore());
+
+      await adapter.mutateLedger((store) => {
+        store.tree.principles['P-COMPAT'] = {
+          id: 'P-COMPAT',
+          version: 1,
+          text: 'Compatibility test',
+          triggerPattern: 'compat',
+          action: 'verify',
+          status: 'active',
+          priority: 'P1',
+          scope: 'general',
+          evaluability: 'deterministic',
+          valueScore: 10,
+          adherenceRate: 0.8,
+          painPreventedCount: 5,
+          derivedFromPainIds: ['pain-1'],
+          ruleIds: [],
+          conflictsWithPrincipleIds: [],
+          createdAt: '2026-04-17T00:00:00.000Z',
+          updatedAt: '2026-04-17T00:00:00.000Z',
+        };
+      });
+
+      // Load with the low-level function — should see the same data
+      const ledger = loadLedger(tmpDir);
+      expect(ledger.tree.principles['P-COMPAT']).toBeDefined();
+      expect(ledger.tree.principles['P-COMPAT'].text).toBe('Compatibility test');
+    });
+  });
+});