principles-disciple 1.52.0 → 1.53.0

package/src/core/observability.ts

@@ -0,0 +1,242 @@
+/**
+ * Observability Baselines for the Evolution SDK.
+ *
+ * Provides calculateBaselines() which measures the current state of the
+ * principle evolution system across four dimensions:
+ *
+ * 1. Principle Stock: total count of principles in the ledger
+ * 2. Structure: average sub-principles (rules) and implementations per principle
+ * 3. Association Rate: principles created / total pain events recorded
+ * 4. Internalization Rate: internalized principles / total principles
+ *
+ * Results are logged via SystemLogger and persisted to .state/baselines.json.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadLedger } from './principle-tree-ledger.js';
+import { SystemLogger } from './system-logger.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ObservabilityBaselines {
+  /** ISO 8601 timestamp when baselines were calculated */
+  calculatedAt: string;
+
+  /** Principle Stock: total count of principles in the ledger */
+  principleStock: number;
+
+  /** Total rules across all principles */
+  totalRules: number;
+
+  /** Total implementations across all rules */
+  totalImplementations: number;
+
+  /** Structure: average rules per principle (0 if no principles) */
+  avgRulesPerPrinciple: number;
+
+  /** Structure: average implementations per rule (0 if no rules) */
+  avgImplementationsPerRule: number;
+
+  /** Total pain events from trajectory DB (0 if DB unavailable) */
+  totalPainEvents: number;
+
+  /** Association Rate: principles / total pain events (0 if no pain events) */
+  associationRate: number;
+
+  /** Count of principles with internalizationStatus = 'internalized' */
+  internalizedCount: number;
+
+  /** Internalization Rate: internalized / total principles (0 if no principles) */
+  internalizationRate: number;
+
+  /** Distribution of principle statuses */
+  statusDistribution: Record<string, number>;
+
+  /** Distribution of principle priorities */
+  priorityDistribution: Record<string, number>;
+
+  /** Distribution of internalization statuses from training store */
+  internalizationDistribution: Record<string, number>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const BASELINES_FILE = 'baselines.json';
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate observability baselines for the principle evolution system.
+ *
+ * Reads the principle ledger from stateDir, computes metrics across four
+ * dimensions (Stock, Structure, Association, Internalization), logs a summary
+ * via SystemLogger, and persists results to .state/baselines.json.
+ *
+ * @param stateDir - The .state directory containing the principle ledger
+ * @param workspaceDir - Optional workspace dir for SystemLogger routing
+ * @returns The computed baselines
+ */
+export function calculateBaselines(
+  stateDir: string,
+  workspaceDir?: string,
+): ObservabilityBaselines {
+  const ledger = loadLedger(stateDir);
+  const { tree, trainingStore } = ledger;
+
+  const principles = Object.values(tree.principles);
+  const rules = Object.values(tree.rules);
+  const implementations = Object.values(tree.implementations);
+
+  const principleStock = principles.length;
+  const totalRules = rules.length;
+  const totalImplementations = implementations.length;
+
+  // Structure metrics
+  const avgRulesPerPrinciple = principleStock > 0
+    ? totalRules / principleStock
+    : 0;
+  const avgImplementationsPerRule = totalRules > 0
+    ? totalImplementations / totalRules
+    : 0;
+
+  // Count pain events from trajectory DB
+  const totalPainEvents = countPainEvents(stateDir);
+
+  // Association Rate: how many principles were created per pain event
+  const associationRate = totalPainEvents > 0
+    ? principleStock / totalPainEvents
+    : 0;
+
+  // Internalization Rate from training store
+  // Filter to only entries whose principleId still exists in the ledger tree
+  // to avoid orphaned/deleted entries inflating the ratio
+  const trainingEntries = Object.values(trainingStore);
+  const activePrincipleIds = new Set(Object.keys(tree.principles));
+  const activeEntries = trainingEntries.filter(
+    (entry) => activePrincipleIds.has(entry.principleId),
+  );
+  const internalizedCount = activeEntries.filter(
+    (entry) => entry.internalizationStatus === 'internalized',
+  ).length;
+  const internalizationRate = principleStock > 0
+    ? internalizedCount / principleStock
+    : 0;
+
+  // Status distribution
+  const statusDistribution: Record<string, number> = {};
+  for (const p of principles) {
+    statusDistribution[p.status] = (statusDistribution[p.status] ?? 0) + 1;
+  }
+
+  // Priority distribution
+  const priorityDistribution: Record<string, number> = {};
+  for (const p of principles) {
+    priorityDistribution[p.priority] = (priorityDistribution[p.priority] ?? 0) + 1;
+  }
+
+  // Internalization status distribution from training store
+  const internalizationDistribution: Record<string, number> = {};
+  for (const entry of trainingEntries) {
+    internalizationDistribution[entry.internalizationStatus] =
+      (internalizationDistribution[entry.internalizationStatus] ?? 0) + 1;
+  }
+
+  const baselines: ObservabilityBaselines = {
+    calculatedAt: new Date().toISOString(),
+    principleStock,
+    totalRules,
+    totalImplementations,
+    avgRulesPerPrinciple: roundTo3(avgRulesPerPrinciple),
+    avgImplementationsPerRule: roundTo3(avgImplementationsPerRule),
+    totalPainEvents,
+    associationRate: roundTo3(associationRate),
+    internalizedCount,
+    internalizationRate: roundTo3(internalizationRate),
+    statusDistribution,
+    priorityDistribution,
+    internalizationDistribution,
+  };
+
+  // Log summary
+  SystemLogger.log(
+    workspaceDir,
+    'OBSERVABILITY_BASELINES',
+    formatBaselineSummary(baselines),
+  );
+
+  // Persist to .state/baselines.json
+  persistBaselines(stateDir, baselines);
+
+  return baselines;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function roundTo3(n: number): number {
+  return Math.round(n * 1000) / 1000;
+}
+
+function formatBaselineSummary(b: ObservabilityBaselines): string {
+  return [
+    `Principle Stock: ${b.principleStock}`,
+    `Structure: ${b.avgRulesPerPrinciple} rules/principle, ${b.avgImplementationsPerRule} impls/rule`,
+    `Association Rate: ${b.associationRate} (${b.principleStock} principles / ${b.totalPainEvents} pain events)`,
+    `Internalization Rate: ${b.internalizationRate} (${b.internalizedCount}/${b.principleStock})`,
+  ].join(' | ');
+}
+
+/**
+ * Count pain events from the trajectory SQLite database.
+ * Returns 0 if the database is unavailable or the table doesn't exist.
+ */
+function countPainEvents(stateDir: string): number {
+  const dbPath = path.join(stateDir, 'trajectory.db');
+  if (!fs.existsSync(dbPath)) {
+    return 0;
+  }
+
+  try {
+    // Use dynamic import for better-sqlite3 to avoid hard dependency
+    // at module load time. If not available, return 0.
+     
+    const Database = require('better-sqlite3') as typeof import('better-sqlite3');
+    const db = new Database(dbPath, { readonly: true });
+
+    try {
+      const row = db.prepare('SELECT COUNT(*) as count FROM pain_events').get() as { count: number } | undefined;
+      return row?.count ?? 0;
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    // better-sqlite3 not available, or table doesn't exist — log and return 0
+    SystemLogger.log(stateDir, 'OBSERVABILITY_SQL_ERROR', `countPainEvents failed: ${String(err)}`);
+    return 0;
+  }
+}
+
+/**
+ * Persist baselines to .state/baselines.json atomically.
+ */
+function persistBaselines(stateDir: string, baselines: ObservabilityBaselines): void {
+  try {
+    const filePath = path.join(stateDir, BASELINES_FILE);
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    atomicWriteFileSync(filePath, JSON.stringify(baselines, null, 2));
+  } catch (err) {
+    // Baselines persistence is best-effort — don't crash the caller
+    // (the SystemLogger call above already logged the values)
+  }
+}

package/src/core/pain-signal-adapter.ts

@@ -0,0 +1,42 @@
+/**
+ * PainSignalAdapter interface for the Evolution SDK.
+ *
+ * This interface decouples the evolution engine from specific AI agent
+ * frameworks (OpenClaw, Claude Code, etc.). All modules that need to
+ * capture pain signals from tool failures should depend on this interface
+ * rather than importing framework-specific event types directly.
+ *
+ * The interface uses a generic type parameter for the raw framework event,
+ * so each framework implementation provides its own concrete type.
+ */
+import type { PainSignal } from './pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// PainSignalAdapter Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-agnostic adapter for capturing pain signals.
+ *
+ * @typeParam TRawEvent - The framework-specific event type
+ * (e.g., PluginHookAfterToolCallEvent for OpenClaw)
+ */
+export interface PainSignalAdapter<TRawEvent> {
+  /**
+   * Translate a framework-specific event into a universal PainSignal.
+   *
+   * Returns null when the event does not produce a pain signal (e.g., the
+   * event type is not a failure, or the event lacks required fields).
+   *
+   * This method performs pure translation only. Trigger decision logic
+   * (e.g., GFI threshold checks, tool name filtering) stays in the
+   * framework-side hook logic. Per D-02, capture() only translates.
+   *
+   * Translation failures (malformed events, missing required fields)
+   * return null rather than throwing. This keeps the adapter resilient.
+   *
+   * @param rawEvent - The framework-specific event to translate
+   * @returns A valid PainSignal, or null if the event does not produce one
+   */
+  capture(rawEvent: TRawEvent): PainSignal | null;
+}

package/src/core/pain-signal.ts

@@ -0,0 +1,136 @@
+/**
+ * Universal PainSignal schema for the Evolution SDK.
+ *
+ * This module defines a framework-agnostic pain signal that any AI agent
+ * framework can produce. It extends the existing PainFlagData format with
+ * additional structured fields (domain, severity, context) needed for
+ * cross-workspace evolution and multi-domain support.
+ *
+ * Validation uses @sinclair/typebox to match existing project patterns.
+ */
+import { Type, type Static } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+
+// ---------------------------------------------------------------------------
+// PainSignal Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Severity levels derived from pain score thresholds.
+ * - low:      0-39  (minor issue, informational)
+ * - medium:   40-69 (moderate error)
+ * - high:     70-89 (severe violation)
+ * - critical: 90-100 (systemic failure, spiral detected)
+ */
+export const PainSeverity = Type.Union([
+  Type.Literal('low'),
+  Type.Literal('medium'),
+  Type.Literal('high'),
+  Type.Literal('critical'),
+]);
+
+export type PainSeverity = Static<typeof PainSeverity>;
+
+/**
+ * TypeBox schema for a universal pain signal.
+ *
+ * Every signal MUST have: source, score, timestamp, reason, sessionId,
+ * agentId, traceId, triggerTextPreview. Optional fields (domain, severity,
+ * context) default during validation.
+ */
+export const PainSignalSchema = Type.Object({
+  /** What triggered this pain signal (e.g., 'tool_failure', 'human_intervention') */
+  source: Type.String({ minLength: 1 }),
+  /** Pain score 0-100 */
+  score: Type.Number({ minimum: 0, maximum: 100 }),
+  /** ISO 8601 timestamp */
+  timestamp: Type.String({ minLength: 1 }),
+  /** Human-readable reason / error description */
+  reason: Type.String({ minLength: 1 }),
+  /** Session ID — identifies which conversation this happened in */
+  sessionId: Type.String({ minLength: 1 }),
+  /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
+  agentId: Type.String({ minLength: 1 }),
+  /** Correlation trace ID for linking events across the pipeline */
+  traceId: Type.String({ minLength: 1 }),
+  /** Preview of the text that triggered this pain */
+  triggerTextPreview: Type.String(),
+  /** Domain context (e.g., 'coding', 'writing', 'analysis') */
+  domain: Type.String({ default: 'coding' }),
+  /** Severity level derived from score */
+  severity: PainSeverity,
+  /** Additional structured context payload */
+  context: Type.Record(Type.String(), Type.Unknown()),
+});
+
+export type PainSignal = Static<typeof PainSignalSchema>;
+
+// ---------------------------------------------------------------------------
+// Default Derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derives severity from a numeric pain score.
+ */
+export function deriveSeverity(score: number): PainSeverity {
+  if (score >= 90) return 'critical';
+  if (score >= 70) return 'high';
+  if (score >= 40) return 'medium';
+  return 'low';
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface PainSignalValidationResult {
+  valid: boolean;
+  errors: string[];
+  signal?: PainSignal;
+}
+
+/**
+ * Validates an arbitrary object against the PainSignal schema.
+ *
+ * Returns a structured result with:
+ * - `valid`: whether the input conforms to the schema
+ * - `errors`: human-readable list of validation failures
+ * - `signal`: the typed signal (only present when valid)
+ *
+ * Missing optional fields (domain, severity, context) are filled with defaults
+ * before validation so callers get a fully-formed signal back.
+ */
+export function validatePainSignal(input: unknown): PainSignalValidationResult {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    return { valid: false, errors: ['Input must be a non-null object'] };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // Apply defaults for optional fields before validation
+  const hydrated = {
+    ...raw,
+    domain: raw.domain ?? 'coding',
+    severity: raw.severity ?? deriveSeverity(
+      typeof raw.score === 'number' ? raw.score : 0,
+    ),
+    context: raw.context ?? {},
+  };
+
+  // Collect TypeBox errors
+  const errors = [...Value.Errors(PainSignalSchema, hydrated)];
+  if (errors.length > 0) {
+    return {
+      valid: false,
+      errors: errors.map(
+        (e) => `${e.path ? `${e.path}: ` : ''}${e.message}`,
+      ),
+    };
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    signal: Value.Cast(PainSignalSchema, hydrated) as PainSignal,
+  };
+}

package/src/core/principle-injection.ts

@@ -0,0 +1,208 @@
+/**
+ * Principle Injection — Budget-Aware Principle Selection
+ * ========================================================
+ *
+ * PURPOSE: Select principles for prompt injection within a character budget,
+ * prioritizing by priority tier (P0 > P1 > P2) and recency, while ensuring
+ * at least one P0 principle is included when available.
+ *
+ * DESIGN:
+ *  - Sorts principles by priority (P0 first, then P1, then P2)
+ *  - Within same priority, sorts by recency (createdAt descending)
+ *  - Selects principles until the cumulative character budget is exceeded
+ *  - Guarantees at least one P0 principle is included if any exist
+ *  - Returns the selected principles and total character usage
+ *
+ * This replaces the previous hardcoded slice(-3)/slice(0,5) approach in
+ * prompt.ts with a budget-aware, priority-respecting selection algorithm.
+ */
+
+import type { PrinciplePriority } from '../types/principle-tree-schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal principle shape required for injection selection.
+ * Accepts both evolution-types.Principle and principle-tree-schema.Principle.
+ */
+export interface InjectablePrinciple {
+  id: string;
+  text: string;
+  /** Priority level. Defaults to 'P1' if not set by the source. */
+  priority?: PrinciplePriority;
+  createdAt: string;
+}
+
+/**
+ * Result of principle selection for injection.
+ */
+export interface PrincipleSelectionResult {
+  /** Selected principles in injection order (priority-first, then recency) */
+  selected: InjectablePrinciple[];
+  /** Total character count of selected principles' formatted output */
+  totalChars: number;
+  /** Number of principles by priority tier */
+  breakdown: {
+    p0: number;
+    p1: number;
+    p2: number;
+  };
+  /** Whether at least one P0 principle was included */
+  hasP0: boolean;
+  /** Whether the selection was truncated due to budget */
+  wasTruncated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Priority Ordering
+// ---------------------------------------------------------------------------
+
+const PRIORITY_ORDER: Record<PrinciplePriority, number> = {
+  P0: 0,
+  P1: 1,
+  P2: 2,
+};
+
+/**
+ * Compare two principles for sorting.
+ * Primary: priority (P0 < P1 < P2 — lower is higher priority).
+ * Secondary: recency (newer createdAt first).
+ */
+function comparePrinciples(a: InjectablePrinciple, b: InjectablePrinciple): number {
+  const priorityA = PRIORITY_ORDER[a.priority ?? 'P1'] ?? 99;
+  const priorityB = PRIORITY_ORDER[b.priority ?? 'P1'] ?? 99;
+
+  if (priorityA !== priorityB) {
+    return priorityA - priorityB;
+  }
+
+  // Same priority: sort by recency (newer first)
+  return b.createdAt.localeCompare(a.createdAt);
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a single principle for injection.
+ * Returns the formatted string including ID and text.
+ *
+ * Format: "- [ID] text" (matches existing prompt.ts format)
+ */
+export function formatPrinciple(p: InjectablePrinciple): string {
+  return `- [${p.id}] ${p.text}`;
+}
+
+/**
+ * Calculate the character length of a formatted principle, including newline.
+ */
+function formattedLength(p: InjectablePrinciple): number {
+  return formatPrinciple(p).length + 1; // +1 for newline separator
+}
+
+// ---------------------------------------------------------------------------
+// Selection Algorithm
+// ---------------------------------------------------------------------------
+
+/**
+ * Select principles for prompt injection within a character budget.
+ *
+ * Algorithm:
+ *  1. Sort all principles by priority (P0 > P1 > P2), then by recency
+ *  2. Iterate through sorted principles, accumulating character count
+ *  3. Stop when adding the next principle would exceed budgetChars
+ *  4. Ensure at least one P0 principle is included (even if it exceeds budget)
+ *
+ * @param principles - All available principles to select from
+ * @param budgetChars - Maximum character budget for formatted output
+ * @returns Selection result with chosen principles and metadata
+ */
+export function selectPrinciplesForInjection(
+  principles: InjectablePrinciple[],
+  budgetChars: number,
+): PrincipleSelectionResult {
+  if (principles.length === 0) {
+    return {
+      selected: [],
+      totalChars: 0,
+      breakdown: { p0: 0, p1: 0, p2: 0 },
+      hasP0: false,
+      wasTruncated: false,
+    };
+  }
+
+  // Sort by priority then recency
+  const sorted = [...principles].sort(comparePrinciples);
+
+  const selected: InjectablePrinciple[] = [];
+  let totalChars = 0;
+  let p0Included = false;
+  let wasTruncated = false;
+
+  for (const principle of sorted) {
+    const cost = formattedLength(principle);
+
+    // Check if adding this principle would exceed budget
+    if (totalChars + cost > budgetChars) {
+      // Special case: if no P0 has been included yet, force-include the first P0
+      // even if it exceeds the budget (P0 principles are critical)
+      if (!p0Included && principle.priority === 'P0') {
+        selected.push(principle);
+        totalChars += cost;
+        p0Included = true;
+        wasTruncated = true;
+        // Continue to try to fit more principles after this forced inclusion
+        continue;
+      }
+
+      wasTruncated = true;
+      break;
+    }
+
+    selected.push(principle);
+    totalChars += cost;
+    if (principle.priority === 'P0') {
+      p0Included = true;
+    }
+  }
+
+  // Safety net: if we went through all principles and still no P0 included
+  // (because P0 was beyond budget threshold), force-include the first P0
+  if (!p0Included) {
+    const firstP0 = sorted.find(p => p.priority === 'P0');
+    if (firstP0 && !selected.includes(firstP0)) {
+      // Insert P0 at the beginning of selected (highest priority)
+      selected.unshift(firstP0);
+      totalChars += formattedLength(firstP0);
+      p0Included = true;
+    }
+  }
+
+  const breakdown = {
+    p0: selected.filter(p => (p.priority ?? 'P1') === 'P0').length,
+    p1: selected.filter(p => (p.priority ?? 'P1') === 'P1').length,
+    p2: selected.filter(p => (p.priority ?? 'P1') === 'P2').length,
+  };
+
+  return {
+    selected,
+    totalChars,
+    breakdown,
+    hasP0: p0Included,
+    wasTruncated,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Default Budget
+// ---------------------------------------------------------------------------
+
+/**
+ * Default character budget for principle injection.
+ * 4000 characters is ~800 tokens, leaving ample room for other prompt sections
+ * within the 10K character injection limit.
+ */
+export const DEFAULT_PRINCIPLE_BUDGET = 4000;