principles-disciple 1.40.0 → 1.41.0

package/src/core/reflection/reflection-context.ts

@@ -0,0 +1,228 @@
+/**
+ * ReflectionContextCollector — Unified Pipeline Input
+ * ====================================================
+ *
+ * PURPOSE: Collect all grounding context for a principle into a single
+ * ReflectionContext object. This is the input to the nocturnal reflection
+ * pipeline: principle + painEvents + sessionSnapshot + lineage.
+ *
+ * DESIGN DECISIONS:
+ * - If a principle has no derivedFromPainIds, collect() returns null
+ *   (nothing to ground code on).
+ * - painId -> sessionId resolution is a known gap. For now, we attempt
+ *   best-effort lookup but return what we have with sessionSnapshot = null
+ *   if we can't resolve.
+ *
+ * REUSES:
+ * - principle-tree-ledger: loadLedger() for principle lookup
+ * - nocturnal-trajectory-extractor: for session snapshots
+ * - trajectory: TrajectoryDatabase for pain event queries
+ */
+
+import { loadLedger, type LedgerPrinciple } from '../principle-tree-ledger.js';
+import {
+  NocturnalTrajectoryExtractor,
+  type NocturnalPainEvent,
+  type NocturnalSessionSnapshot,
+} from '../nocturnal-trajectory-extractor.js';
+import type { TrajectoryDatabase } from '../trajectory.js';
+import type { Principle } from '../../types/principle-tree-schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Unified reflection context for the nocturnal pipeline.
+ */
+export interface ReflectionContext {
+  /** The principle being reflected upon */
+  principle: Principle;
+  /** Pain events associated with this principle (via derivedFromPainIds) */
+  painEvents: NocturnalPainEvent[];
+  /** Session snapshot if resolvable, null otherwise */
+  sessionSnapshot: NocturnalSessionSnapshot | null;
+  /** Lineage metadata connecting principle to source pain signals */
+  lineage: {
+    sourcePainIds: string[];
+    sessionId: string | null;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Collector
+// ---------------------------------------------------------------------------
+
+/**
+ * Collects ReflectionContext for principles by joining ledger data with
+ * trajectory data.
+ */
+export class ReflectionContextCollector {
+  private readonly stateDir: string;
+  private readonly trajectory: TrajectoryDatabase;
+
+  constructor(stateDir: string, trajectory: TrajectoryDatabase) {
+    this.stateDir = stateDir;
+    this.trajectory = trajectory;
+  }
+
+  /**
+   * Collect full reflection context for a single principle.
+   *
+   * Returns null if:
+   * - The principle is not found in the ledger
+   * - The principle has no derivedFromPainIds (nothing to ground on)
+   */
+  collect(principleId: string): ReflectionContext | null {
+    const ledger = loadLedger(this.stateDir);
+    const principle = ledger.tree.principles[principleId];
+
+    if (!principle) {
+      return null;
+    }
+
+    if (!principle.derivedFromPainIds || principle.derivedFromPainIds.length === 0) {
+      return null;
+    }
+
+    return this.buildContext(principle);
+  }
+
+  /**
+   * Collect reflection contexts for multiple principles, optionally filtered.
+   *
+   * Skips principles without derivedFromPainIds.
+   */
+  collectBatch(filter?: { status?: string }): ReflectionContext[] {
+    const ledger = loadLedger(this.stateDir);
+    const principles = Object.values(ledger.tree.principles);
+
+    const results: ReflectionContext[] = [];
+
+    for (const principle of principles) {
+      // Apply status filter if provided
+      if (filter?.status && principle.status !== filter.status) {
+        continue;
+      }
+
+      // Skip principles without pain grounding
+      if (!principle.derivedFromPainIds || principle.derivedFromPainIds.length === 0) {
+        continue;
+      }
+
+      const ctx = this.buildContext(principle);
+      if (ctx) {
+        results.push(ctx);
+      }
+    }
+
+    return results;
+  }
+
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build a ReflectionContext from a principle.
+   *
+   * Attempts to resolve painIds to sessions via best-effort lookup.
+   * Since painId -> sessionId mapping is a known gap, we may return
+   * empty painEvents and null sessionSnapshot.
+   */
+  private buildContext(principle: LedgerPrinciple): ReflectionContext {
+    const sourcePainIds = principle.derivedFromPainIds;
+
+    // Best-effort: try to find a session containing pain events related to this principle.
+    // The pain_events table uses auto-increment IDs, not the string painIds stored in
+    // derivedFromPainIds. This is the known gap — for now we attempt session resolution
+    // but gracefully handle the case where we can't match.
+    const { painEvents, sessionId } = this.resolvePainEvents(sourcePainIds);
+
+    // If we found a session, get the snapshot
+    let sessionSnapshot: NocturnalSessionSnapshot | null = null;
+    if (sessionId) {
+      const extractor = new NocturnalTrajectoryExtractor(this.trajectory);
+      sessionSnapshot = extractor.getNocturnalSessionSnapshot(sessionId);
+    }
+
+    return {
+      principle,
+      painEvents,
+      sessionSnapshot,
+      lineage: {
+        sourcePainIds,
+        sessionId,
+      },
+    };
+  }
+
+  /**
+   * Attempt to resolve painIds to actual pain events and a session.
+   *
+   * Two-phase strategy:
+   * 1. Exact ID match: sourcePainIds are stringified pain_events row IDs.
+   *    If any match String(pe.id) exactly, use those and stop.
+   * 2. Heuristic fallback: substring match on reason/origin fields.
+   *    Only used when no exact matches are found.
+   */
+  private resolvePainEvents(sourcePainIds: string[]): {
+    painEvents: NocturnalPainEvent[];
+    sessionId: string | null;
+  } {
+    const sessions = this.trajectory.listRecentSessions({ limit: 100 });
+    const sourcePainIdSet = new Set(sourcePainIds);
+
+    const exactMatches: NocturnalPainEvent[] = [];
+    const heuristicMatches: NocturnalPainEvent[] = [];
+    let exactSessionId: string | null = null;
+    let heuristicSessionId: string | null = null;
+
+    for (const session of sessions) {
+      const sessionPainEvents = this.trajectory.listPainEventsForSession(session.sessionId);
+
+      for (const pe of sessionPainEvents) {
+        // Phase 1: exact ID match
+        if (sourcePainIdSet.has(String(pe.id))) {
+          exactMatches.push({
+            source: pe.source,
+            score: pe.score,
+            severity: pe.severity,
+            reason: pe.reason,
+            createdAt: pe.createdAt,
+          });
+          if (!exactSessionId) {
+            exactSessionId = session.sessionId;
+          }
+          continue;
+        }
+
+        // Phase 2: heuristic substring match on reason/origin only
+        const peText = [pe.reason, pe.origin].filter(Boolean);
+        const isMatch = sourcePainIds.some((painId) =>
+          peText.some((field) => field?.includes(painId)),
+        );
+
+        if (isMatch) {
+          heuristicMatches.push({
+            source: pe.source,
+            score: pe.score,
+            severity: pe.severity,
+            reason: pe.reason,
+            createdAt: pe.createdAt,
+          });
+          if (!heuristicSessionId) {
+            heuristicSessionId = session.sessionId;
+          }
+        }
+      }
+    }
+
+    // Prefer exact matches over heuristic matches
+    if (exactMatches.length > 0) {
+      return { painEvents: exactMatches, sessionId: exactSessionId };
+    }
+
+    return { painEvents: heuristicMatches, sessionId: heuristicSessionId };
+  }
+}

package/tests/core/code-validator.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import { validateGeneratedCode } from '../../src/core/principle-compiler/code-validator.js';
+
+describe('validateGeneratedCode', () => {
+  // --- Valid code ---
+
+  it('accepts valid rule implementation with evaluate and meta', () => {
+    const code = `
+export const meta = {
+  name: 'test-rule',
+  version: '1.0.0',
+  ruleId: 'R-001',
+  coversCondition: 'test condition'
+};
+
+export function evaluate(input) {
+  return {
+    matched: input.action.toolName === 'bash',
+    reason: 'checked toolName'
+  };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('accepts evaluate that returns matched: false', () => {
+    const code = `
+export const meta = { name: 'never-match', version: '1.0.0', ruleId: 'R-002', coversCondition: 'none' };
+
+export function evaluate(_input) {
+  return { matched: false, reason: 'never matches' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+
+  // --- Syntax check ---
+
+  it('rejects code with syntax errors', () => {
+    const code = `function broken( {`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /syntax/i.test(e))).toBe(true);
+  });
+
+  // --- Forbidden patterns ---
+
+  it('rejects code containing require(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { const fs = require('fs'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /require/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing import statement', () => {
+    const code = `import { something } from 'module';
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /import/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing fetch(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { fetch('http://evil.com'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /fetch/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing eval(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { eval('42'); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /eval/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing Function(', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { new Function('return 1')(); return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /Function/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing process', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { const x = process.env; return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /process/i.test(e))).toBe(true);
+  });
+
+  it('rejects code containing globalThis', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { globalThis.foo = 'bar'; return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /globalThis/i.test(e))).toBe(true);
+  });
+
+  it('reports all forbidden patterns at once', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() {
+  require('fs');
+  fetch('http://x');
+  eval('1');
+  process.env;
+  return { matched: false, reason: '' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThanOrEqual(4);
+  });
+
+  // --- Export check ---
+
+  it('rejects code that does not export evaluate', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+// no evaluate function at all
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /evaluate/i.test(e))).toBe(true);
+  });
+
+  it('rejects code that does not export meta', () => {
+    const code = `
+// no meta at all
+export function evaluate() { return { matched: false, reason: '' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /meta/i.test(e))).toBe(true);
+  });
+
+  // --- Return shape check ---
+
+  it('rejects evaluate that returns object without matched', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate() { return { reason: 'no matched field' }; }
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /matched/i.test(e))).toBe(true);
+  });
+
+  it('accepts evaluate even when it throws on mock input', () => {
+    // evaluate throws because it accesses a nested property that doesn't exist in mock
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate(input) {
+  if (input.action.toolName === 'bash') {
+    return { matched: true, reason: 'ok' };
+  }
+  throw new Error('unexpected input');
+}
+`;
+    // The mock input has toolName: 'bash', so it returns successfully
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts evaluate that throws as long as it has correct shape when it returns', () => {
+    const code = `
+export const meta = { name: 'x', version: '1', ruleId: 'R', coversCondition: 'c' };
+export function evaluate(_input) {
+  return { matched: true, reason: 'ok' };
+}
+`;
+    const result = validateGeneratedCode(code);
+    expect(result.valid).toBe(true);
+  });
+});

package/tests/core/ledger-registrar.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Ledger Registrar Tests (Task 4)
+ *
+ * TDD test suite for registerCompiledRule — creates a gate rule + code
+ * implementation in the principle tree ledger for a compiled principle.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { safeRmDir } from '../test-utils.js';
+import {
+  loadLedger,
+  saveLedger,
+  type HybridLedgerStore,
+  type LedgerPrinciple,
+  type LedgerRule,
+} from '../../src/core/principle-tree-ledger.js';
+import { registerCompiledRule, type RegisterInput, type RegisterResult } from '../../src/core/principle-compiler/ledger-registrar.js';
+
+describe('ledger-registrar', () => {
+  let tempDir: string;
+  let stateDir: string;
+
+  beforeAll(() => {
+    tempDir = fs.mkdtempSync(path.join(process.env.TMP || '/tmp', 'pd-registrar-'));
+    stateDir = path.join(tempDir, '.state');
+    fs.mkdirSync(stateDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    safeRmDir(tempDir);
+  });
+
+  afterEach(() => {
+    const stateFile = path.join(stateDir, 'principle_training_state.json');
+    if (fs.existsSync(stateFile)) {
+      fs.unlinkSync(stateFile);
+    }
+  });
+
+  // Helper: Create a minimal ledger principle
+  function createLedgerPrinciple(principleId: string, overrides: Partial<LedgerPrinciple> = {}): LedgerPrinciple {
+    return {
+      id: principleId,
+      version: 1,
+      text: `Test principle ${principleId}`,
+      triggerPattern: 'test',
+      action: 'test action',
+      status: 'active',
+      priority: 'P1',
+      scope: 'general',
+      evaluability: 'deterministic',
+      valueScore: 0,
+      adherenceRate: 0,
+      painPreventedCount: 0,
+      derivedFromPainIds: [],
+      ruleIds: [],
+      conflictsWithPrincipleIds: [],
+      createdAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      ...overrides,
+    };
+  }
+
+  // Helper: Setup ledger with a single principle
+  function setupLedgerWithPrinciple(principleId: string): void {
+    const tree = {
+      principles: {} as Record<string, LedgerPrinciple>,
+      rules: {} as Record<string, LedgerRule>,
+      implementations: {},
+      metrics: {},
+      lastUpdated: new Date().toISOString(),
+    };
+
+    tree.principles[principleId] = createLedgerPrinciple(principleId);
+
+    const store: HybridLedgerStore = {
+      trainingStore: {},
+      tree,
+    };
+
+    saveLedger(stateDir, store);
+  }
+
+  describe('registerCompiledRule', () => {
+    it('creates a gate rule and code implementation in the ledger', () => {
+      setupLedgerWithPrinciple('P_001');
+
+      const input: RegisterInput = {
+        principleId: 'P_001',
+        codeContent: 'export function check() { return true; }',
+        coversCondition: 'file_write',
+      };
+
+      const result = registerCompiledRule(stateDir, input);
+
+      // Verify result structure
+      expect(result.success).toBe(true);
+      expect(result.ruleId).toBe('R_P_001_auto');
+      expect(result.implementationId).toBe('IMPL_P_001_auto');
+
+      // Verify rule in ledger
+      const ledger = loadLedger(stateDir);
+      const rule = ledger.tree.rules['R_P_001_auto'];
+      expect(rule).toBeDefined();
+      expect(rule.id).toBe('R_P_001_auto');
+      expect(rule.type).toBe('gate');
+      expect(rule.enforcement).toBe('block');
+      expect(rule.status).toBe('proposed');
+      expect(rule.principleId).toBe('P_001');
+      expect(rule.implementationIds).toContain('IMPL_P_001_auto');
+
+      // Verify implementation in ledger
+      const impl = ledger.tree.implementations['IMPL_P_001_auto'];
+      expect(impl).toBeDefined();
+      expect(impl.id).toBe('IMPL_P_001_auto');
+      expect(impl.ruleId).toBe('R_P_001_auto');
+      expect(impl.type).toBe('code');
+      expect(impl.coversCondition).toBe('file_write');
+      expect(impl.lifecycleState).toBe('active');
+
+      // Verify principle linked to rule
+      const principle = ledger.tree.principles['P_001'];
+      expect(principle.ruleIds).toContain('R_P_001_auto');
+    });
+
+    it('returns the codePath in the result', () => {
+      setupLedgerWithPrinciple('P_042');
+
+      const input: RegisterInput = {
+        principleId: 'P_042',
+        codeContent: '// some code',
+        coversCondition: 'git_push',
+      };
+
+      const result = registerCompiledRule(stateDir, input);
+
+      expect(result.success).toBe(true);
+      expect(result.codePath).toContain('P_042');
+      expect(result.codePath).toMatch(/\.ts$/);
+    });
+
+    it('throws if the principle does not exist', () => {
+      // Empty ledger — no principles
+      const store: HybridLedgerStore = {
+        trainingStore: {},
+        tree: {
+          principles: {},
+          rules: {},
+          implementations: {},
+          metrics: {},
+          lastUpdated: new Date().toISOString(),
+        },
+      };
+      saveLedger(stateDir, store);
+
+      const input: RegisterInput = {
+        principleId: 'P_NONEXISTENT',
+        codeContent: 'export function check() { return true; }',
+        coversCondition: 'test',
+      };
+
+      expect(() => registerCompiledRule(stateDir, input)).toThrow(/missing principle.*P_NONEXISTENT/);
+    });
+
+    it('sets correct timestamps on rule and implementation', () => {
+      setupLedgerWithPrinciple('P_100');
+
+      const before = new Date().toISOString();
+      const input: RegisterInput = {
+        principleId: 'P_100',
+        codeContent: 'export const x = 1;',
+        coversCondition: 'test_condition',
+      };
+
+      const result = registerCompiledRule(stateDir, input);
+      const after = new Date().toISOString();
+
+      expect(result.success).toBe(true);
+
+      const ledger = loadLedger(stateDir);
+      const rule = ledger.tree.rules['R_P_100_auto'];
+      const impl = ledger.tree.implementations['IMPL_P_100_auto'];
+
+      // Timestamps should be between before and after
+      expect(rule.createdAt >= before).toBe(true);
+      expect(rule.createdAt <= after).toBe(true);
+      expect(rule.updatedAt).toBe(rule.createdAt);
+
+      expect(impl.createdAt >= before).toBe(true);
+      expect(impl.createdAt <= after).toBe(true);
+      expect(impl.updatedAt).toBe(impl.createdAt);
+    });
+
+    it('handles multiple registrations for different principles', () => {
+      // Setup ledger with two principles
+      const tree = {
+        principles: {} as Record<string, LedgerPrinciple>,
+        rules: {} as Record<string, LedgerRule>,
+        implementations: {},
+        metrics: {},
+        lastUpdated: new Date().toISOString(),
+      };
+      tree.principles['P_001'] = createLedgerPrinciple('P_001');
+      tree.principles['P_002'] = createLedgerPrinciple('P_002');
+
+      const store: HybridLedgerStore = { trainingStore: {}, tree };
+      saveLedger(stateDir, store);
+
+      const result1 = registerCompiledRule(stateDir, {
+        principleId: 'P_001',
+        codeContent: '// code 1',
+        coversCondition: 'cond_1',
+      });
+      const result2 = registerCompiledRule(stateDir, {
+        principleId: 'P_002',
+        codeContent: '// code 2',
+        coversCondition: 'cond_2',
+      });
+
+      expect(result1.success).toBe(true);
+      expect(result2.success).toBe(true);
+      expect(result1.ruleId).toBe('R_P_001_auto');
+      expect(result2.ruleId).toBe('R_P_002_auto');
+
+      const ledger = loadLedger(stateDir);
+      expect(Object.keys(ledger.tree.rules)).toHaveLength(2);
+      expect(Object.keys(ledger.tree.implementations)).toHaveLength(2);
+    });
+  });
+});