principles-disciple 1.52.0 → 1.53.0

package/src/core/principle-injector.ts

@@ -0,0 +1,84 @@
+/**
+ * PrincipleInjector interface for the Evolution SDK.
+ *
+ * Wraps the existing principle injection logic into a framework-agnostic
+ * contract. Per D-05, this delegates to selectPrinciplesForInjection and
+ * formatPrinciple without any behavioral changes.
+ *
+ * Per D-06, InjectionContext contains only generic fields (domain, sessionId,
+ * budgetChars) -- no framework-specific fields.
+ */
+import type { InjectablePrinciple } from './principle-injection.js';
+import { selectPrinciplesForInjection, formatPrinciple } from './principle-injection.js';
+
+// ---------------------------------------------------------------------------
+// InjectionContext
+// ---------------------------------------------------------------------------
+
+/** Generic injection context -- no framework-specific fields. */
+export interface InjectionContext {
+  /** Domain context (e.g., 'coding', 'writing', 'analysis') */
+  domain: string;
+  /** Session identifier */
+  sessionId: string;
+  /** Maximum characters allowed for injected principles */
+  budgetChars: number;
+}
+
+// ---------------------------------------------------------------------------
+// PrincipleInjector Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-agnostic principle injection interface.
+ *
+ * Wraps the existing budget-aware selection and formatting logic.
+ * Framework adapters convert their context to InjectionContext before calling.
+ */
+export interface PrincipleInjector {
+  /**
+   * Select principles relevant for injection within a character budget.
+   * Delegates to selectPrinciplesForInjection from principle-injection.ts.
+   *
+   * @param principles - All available principles to select from
+   * @param context - Generic injection context with budget constraint
+   * @returns Selected principles in injection order
+   */
+  getRelevantPrinciples(
+    principles: InjectablePrinciple[],
+    context: InjectionContext,
+  ): InjectablePrinciple[];
+
+  /**
+   * Format a single principle for prompt injection.
+   * Delegates to formatPrinciple from principle-injection.ts.
+   *
+   * Format: "- [ID] text"
+   *
+   * @param principle - The principle to format
+   * @returns Formatted string for prompt injection
+   */
+  formatForInjection(principle: InjectablePrinciple): string;
+}
+
+// ---------------------------------------------------------------------------
+// Default Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Default implementation that delegates to existing functions.
+ * Zero rewrite risk -- behavior is identical to calling the functions directly.
+ */
+export class DefaultPrincipleInjector implements PrincipleInjector {
+  getRelevantPrinciples(
+    principles: InjectablePrinciple[],
+    context: InjectionContext,
+  ): InjectablePrinciple[] {
+    const result = selectPrinciplesForInjection(principles, context.budgetChars);
+    return result.selected;
+  }
+
+  formatForInjection(principle: InjectablePrinciple): string {
+    return formatPrinciple(principle);
+  }
+}

package/src/core/storage-adapter.ts

@@ -0,0 +1,65 @@
+/**
+ * StorageAdapter interface for the Evolution SDK.
+ *
+ * This interface decouples the evolution engine from specific persistence
+ * implementations (file system, SQLite, remote API). All higher-level
+ * modules that need to read or mutate the principle ledger should depend
+ * on this interface rather than importing principle-tree-ledger directly.
+ *
+ * The interface uses HybridLedgerStore from principle-tree-ledger as the
+ * canonical store shape, but future adapters can map alternative backends
+ * to this shape.
+ */
+import type { HybridLedgerStore } from './principle-tree-ledger.js';
+
+// ---------------------------------------------------------------------------
+// StorageAdapter Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Abstract storage adapter for the principle ledger.
+ *
+ * Implementations must guarantee:
+ * - Atomic writes (no partial/corrupted state on crash)
+ * - Thread-safe concurrent access (locking or equivalent)
+ * - Consistent read-after-write visibility
+ *
+ * The `mutateLedger` method is the preferred way to perform read-modify-write
+ * cycles. It encapsulates locking so callers never need to manage it.
+ */
+export interface StorageAdapter {
+  /**
+   * Load the current ledger state from persistence.
+   *
+   * If no persisted state exists (first run), returns an empty store.
+   */
+  loadLedger(): Promise<HybridLedgerStore>;
+
+  /**
+   * Persist the full ledger state.
+   *
+   * Must be atomic — partial writes must never be visible to readers.
+   */
+  saveLedger(store: HybridLedgerStore): Promise<void>;
+
+  /**
+   * Perform a read-modify-write cycle with automatic locking.
+   *
+   * The `mutate` function receives the current store and may return a
+   * value synchronously or via Promise. The store is persisted after
+   * the mutate function resolves, regardless of its return value.
+   *
+   * If two concurrent `mutateLedger` calls overlap, one must wait for
+   * the other to complete (pessimistic locking) or retry on conflict
+   * (optimistic locking). The choice is left to the implementation.
+   *
+   * @example
+   * ```ts
+   * const count = await adapter.mutateLedger((store) => {
+   *   store.tree.principles['p-1'] = newPrinciple;
+   *   return Object.keys(store.tree.principles).length;
+   * });
+   * ```
+   */
+  mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T>;
+}

package/src/core/telemetry-event.ts

@@ -0,0 +1,109 @@
+/**
+ * TelemetryEvent schema for the Evolution SDK.
+ *
+ * TypeBox schema describing the shape of in-process evolution events.
+ * Per D-07, this is a documentation artifact -- the existing EvolutionLogger
+ * output should conform to this schema. No new TelemetryService is created.
+ *
+ * Per D-08, covers the 3 core events aligned with EvolutionHook:
+ * - pain_detected (maps to EvolutionStage 'pain_detected')
+ * - principle_candidate_created (maps to EvolutionStage 'principle_generated')
+ * - principle_promoted (maps to EvolutionStage 'completed')
+ *
+ * Injection and storage events are out of scope for this phase.
+ */
+import { Type, type Static } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+
+// ---------------------------------------------------------------------------
+// Event Type Union
+// ---------------------------------------------------------------------------
+
+/**
+ * The 3 core telemetry event types, aligned with EvolutionHook methods.
+ *
+ * Mapping to existing EvolutionLogger stages:
+ * - pain_detected -> EvolutionStage 'pain_detected'
+ * - principle_candidate_created -> EvolutionStage 'principle_generated'
+ * - principle_promoted -> EvolutionStage 'completed'
+ */
+export const TelemetryEventType = Type.Union([
+  Type.Literal('pain_detected'),
+  Type.Literal('principle_candidate_created'),
+  Type.Literal('principle_promoted'),
+]);
+
+export type TelemetryEventType = Static<typeof TelemetryEventType>;
+
+// ---------------------------------------------------------------------------
+// TelemetryEvent Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for an in-process telemetry event.
+ *
+ * Fields align with existing EvolutionLogEntry:
+ * - traceId <-> EvolutionLogEntry.traceId
+ * - timestamp <-> EvolutionLogEntry.timestamp
+ * - sessionId <-> EvolutionLogEntry.sessionId
+ * - payload <-> EvolutionLogEntry.metadata
+ *
+ * No PII fields. The agentId field is optional and contains only
+ * system identifiers (e.g., 'main', 'builder'), never user data.
+ */
+export const TelemetryEventSchema = Type.Object({
+  /** Event type (one of the 3 core types) */
+  eventType: TelemetryEventType,
+  /** Correlation trace ID for linking events across the pipeline */
+  traceId: Type.String({ minLength: 1 }),
+  /** ISO 8601 timestamp */
+  timestamp: Type.String({ minLength: 1 }),
+  /** Session identifier */
+  sessionId: Type.String(),
+  /** Agent identifier (system identifier only, no PII) */
+  agentId: Type.Optional(Type.String()),
+  /** Event-specific payload */
+  payload: Type.Record(Type.String(), Type.Unknown()),
+});
+
+export type TelemetryEvent = Static<typeof TelemetryEventSchema>;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface TelemetryEventValidationResult {
+  valid: boolean;
+  errors: string[];
+  event?: TelemetryEvent;
+}
+
+/**
+ * Validates an arbitrary object against the TelemetryEvent schema.
+ *
+ * Returns a structured result with:
+ * - `valid`: whether the input conforms to the schema
+ * - `errors`: human-readable list of validation failures
+ * - `event`: the typed event (only present when valid)
+ */
+export function validateTelemetryEvent(input: unknown): TelemetryEventValidationResult {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    return { valid: false, errors: ['Input must be a non-null object'] };
+  }
+
+  const errors = [...Value.Errors(TelemetryEventSchema, input)];
+  if (errors.length > 0) {
+    return {
+      valid: false,
+      errors: errors.map(
+        (e) => `${e.path ? `${e.path}: ` : ''}${e.message}`,
+      ),
+    };
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    event: Value.Cast(TelemetryEventSchema, input) as TelemetryEvent,
+  };
+}

package/src/hooks/prompt.ts

@@ -11,6 +11,7 @@ import { classifyTask, type RoutingInput } from '../core/local-worker-routing.js
 import { extractSummary, getHistoryVersions, parseWorkingMemorySection, workingMemoryToInjection, autoCompressFocus, safeReadCurrentFocus } from '../core/focus-history.js';
 import { EmpathyObserverWorkflowManager, empathyObserverWorkflowSpec, isExpectedSubagentError } from '../service/subagent-workflow/index.js';
 import { PathResolver } from '../core/path-resolver.js';
+import { selectPrinciplesForInjection, DEFAULT_PRINCIPLE_BUDGET } from '../core/principle-injection.js';
 import { isSubagentRuntimeAvailable } from '../utils/subagent-probe.js';
 import { getPendingDiagnosticianTasks } from '../core/diagnostician-task-store.js';
 import {
@@ -901,12 +902,26 @@ ${taskBlocks}${processingNote}
   }
 
 
-  // Evolution principles injection (active + probation summary)
+  // Evolution principles injection — budget-aware selection (SDK-QUAL-04)
   let evolutionPrinciplesContent = '';
   try {
     const reducer = wctx.evolutionReducer;
-    const active = reducer.getActivePrinciples().slice(-3);
-    const probation = reducer.getProbationPrinciples().slice(0, 5);
+    const allActive = reducer.getActivePrinciples();
+    const allProbation = reducer.getProbationPrinciples();
+
+    // Budget-aware selection: prioritize P0>P1>P2 and recency
+    const activeSelection = selectPrinciplesForInjection(allActive, DEFAULT_PRINCIPLE_BUDGET);
+    const active = activeSelection.selected;
+
+    // Probation principles get a smaller sub-budget (1000 chars)
+    const probationBudget = 1000;
+    const probationSelection = selectPrinciplesForInjection(allProbation, probationBudget);
+    const probation = probationSelection.selected;
+
+    if (activeSelection.wasTruncated || probationSelection.wasTruncated) {
+      logger?.info?.(`[PD:Prompt] Principles truncated: active=${activeSelection.breakdown.p0 + activeSelection.breakdown.p1 + activeSelection.breakdown.p2}/${allActive.length} (${activeSelection.totalChars}c), probation=${probation.length}/${allProbation.length} (${probationSelection.totalChars}c)`);
+    }
+
     if (ctx.sessionId) {
       if (probation.length > 0) {
         setInjectedProbationIds(ctx.sessionId, probation.map((p) => p.id), workspaceDir);

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';
@@ -330,6 +331,26 @@ 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 || '',
+        agentId: v.agentId || '',
+        traceId: v.traceId || '',
+        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}`);
+        return result;
+    }
+
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     const releaseLock = await requireQueueLock(queuePath, logger, 'checkPainFlag');
     try {
@@ -763,9 +784,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');
+  });
+});