principles-disciple 1.40.0 → 1.41.0

package/src/core/principle-compiler/code-validator.ts

@@ -0,0 +1,120 @@
+/**
+ * Code Validator — Validates LLM-generated rule implementation code
+ *
+ * PURPOSE: Ensure generated code is safe, syntactically correct, and exports
+ * the expected shape before it is stored as a rule implementation.
+ *
+ * CHECKS:
+ * 1. Syntax: code parses without errors
+ * 2. Forbidden patterns: no require, import, fetch, eval, Function, process, globalThis
+ * 3. Export check: sandbox loads and exports evaluate + meta
+ * 4. Return shape: evaluate(mockInput) returns { matched: boolean }
+ *
+ * Reuses loadRuleImplementationModule for sandbox execution (node:vm isolation).
+ */
+
+import { nodeVm } from '../../utils/node-vm-polyfill.js';
+import { loadRuleImplementationModule } from '../rule-implementation-runtime.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+const FORBIDDEN_PATTERNS: { pattern: RegExp; label: string }[] = [
+  { pattern: /\brequire\s*\(/, label: 'require' },
+  { pattern: /\bimport\s+/, label: 'import' },
+  { pattern: /\bfetch\s*\(/, label: 'fetch' },
+  { pattern: /\beval\s*\(/, label: 'eval' },
+  { pattern: /\bFunction\s*\(/, label: 'Function' },
+  { pattern: /\bprocess\b/, label: 'process' },
+  { pattern: /\bglobalThis\b/, label: 'globalThis' },
+  { pattern: /\bglobal\b/, label: 'global' },
+  { pattern: /\bReflect\b/, label: 'Reflect' },
+  { pattern: /\bProxy\b/, label: 'Proxy' },
+  { pattern: /\bconstructor\b/, label: 'constructor' },
+  { pattern: /\bBuffer\b/, label: 'Buffer' },
+  { pattern: /\bsetTimeout\b/, label: 'setTimeout' },
+  { pattern: /\bsetInterval\b/, label: 'setInterval' },
+  // Bracket notation access to globals
+  { pattern: /\[\s*['"](require|import|fetch|eval|process|globalThis|global|Reflect|Proxy|Buffer|Function)\s*['"]\s*\]/, label: 'bracket access to forbidden global' },
+];
+
+const MOCK_INPUT = {
+  action: {
+    toolName: 'bash',
+    normalizedPath: '/tmp/test.ts',
+    paramsSummary: { command: 'echo test' },
+  },
+  workspace: { isRiskPath: false, planStatus: 'NONE', hasPlanFile: false },
+  session: { sessionId: 'test', currentGfi: 0, recentThinking: false },
+  evolution: { epTier: 0 },
+  derived: { estimatedLineChanges: 0, bashRisk: 'safe' },
+};
+
+export function validateGeneratedCode(code: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // --- Check 1: Syntax ---
+  // Normalize export keywords so vm.Script can parse ES module source
+  const normalized = code
+    .replace(/export\s+const\s+/g, 'const ')
+    .replace(/export\s+function\s+/g, 'function ');
+  try {
+    new nodeVm.Script(normalized, { filename: 'code-validator-syntax.js' });
+  } catch (err) {
+    errors.push(`Syntax error: ${(err as Error).message}`);
+    return { valid: false, errors, warnings };
+  }
+
+  // --- Check 2: Forbidden patterns ---
+  for (const { pattern, label } of FORBIDDEN_PATTERNS) {
+    if (pattern.test(code)) {
+      errors.push(`Forbidden pattern: ${label}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+
+  // --- Check 3: Sandbox load + export check ---
+  let moduleExports: { meta?: unknown; evaluate?: unknown };
+  try {
+    moduleExports = loadRuleImplementationModule(code, 'code-validator-candidate.js');
+  } catch (err) {
+    errors.push(`Sandbox compilation error: ${(err as Error).message}`);
+    return { valid: false, errors, warnings };
+  }
+
+  if (!moduleExports.meta || typeof moduleExports.meta !== 'object') {
+    errors.push('Missing export: meta');
+  }
+
+  if (typeof moduleExports.evaluate !== 'function') {
+    errors.push('Missing export: evaluate');
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+
+  // --- Check 4: Return shape ---
+  try {
+    const result = (moduleExports.evaluate as (input: unknown) => unknown)(MOCK_INPUT);
+    if (!result || typeof result !== 'object') {
+      errors.push('evaluate must return an object');
+    } else if (typeof (result as Record<string, unknown>).matched !== 'boolean') {
+      errors.push('evaluate must return { matched: boolean }');
+    }
+  } catch (evalWarning) {
+    // evaluate throwing on mock input is acceptable — the function exists and
+    // has the right signature, it just can't handle our generic mock data.
+    // Track as a non-blocking warning so operators know the rule may be fragile.
+    warnings.push(`evaluate() threw on mock input: ${(evalWarning as Error).message}`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/core/principle-compiler/compiler.ts

@@ -0,0 +1,242 @@
+/**
+ * PrincipleCompiler — Orchestrator (Task 5)
+ *
+ * Orchestrates the full compilation flow:
+ *   ReflectionContextCollector.collect() → extract patterns → generateFromTemplate()
+ *   → validateGeneratedCode() → registerCompiledRule()
+ *
+ * DESIGN DECISIONS:
+ * - extractPatterns infers toolName from pain event reasons and session tool calls
+ * - Groups by toolName into PainPattern objects
+ * - If no patterns can be extracted, returns a 'no patterns' failure
+ */
+
+import { ReflectionContextCollector } from '../reflection/reflection-context.js';
+import { validateGeneratedCode } from './code-validator.js';
+import { generateFromTemplate, type PainPattern } from './template-generator.js';
+import { registerCompiledRule } from './ledger-registrar.js';
+import { createImplementationAssetDir } from '../code-implementation-storage.js';
+import type { TrajectoryDatabase } from '../trajectory.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CompileResult {
+  success: boolean;
+  principleId: string;
+  ruleId?: string;
+  implementationId?: string;
+  code?: string;
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Tool names to look for when scanning text for tool references */
+const KNOWN_TOOLS = ['bash', 'write', 'edit', 'read', 'grep', 'glob', 'mcp'] as const;
+
+/** Regex to extract file paths from reason text */
+const PATH_REGEX = /(?:\/[\w.-]+){2,}/;
+
+// ---------------------------------------------------------------------------
+// Pattern Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract PainPatterns from a ReflectionContext.
+ *
+ * Strategy:
+ * 1. Scan pain event reasons for known tool names
+ * 2. Extract file paths from reason text as pathRegex candidates
+ * 3. Cross-reference with sessionSnapshot toolCalls for failed tool calls
+ * 4. Group by toolName into PainPattern objects
+ */
+function extractPatterns(context: {
+  painEvents: Array<{ reason: string | null; source: string }>;
+  sessionSnapshot: {
+    toolCalls: Array<{
+      toolName: string;
+      outcome: string;
+      filePath: string | null;
+      errorType: string | null;
+    }>;
+  } | null;
+}): PainPattern[] {
+  const toolNameMap = new Map<string, PainPattern>();
+
+  // 1. Extract from pain event reasons
+  for (const pe of context.painEvents) {
+    const text = pe.reason ?? pe.source ?? '';
+    const toolName = inferToolName(text);
+    if (!toolName) continue;
+
+    const pathRegex = extractPathRegex(text);
+
+    if (!toolNameMap.has(toolName)) {
+      toolNameMap.set(toolName, { toolName });
+    }
+
+    const pattern = toolNameMap.get(toolName)!;
+    if (pathRegex && !pattern.pathRegex) {
+      pattern.pathRegex = pathRegex;
+    }
+  }
+
+  // 2. Extract from session snapshot tool calls (failed ones)
+  if (context.sessionSnapshot?.toolCalls) {
+    for (const tc of context.sessionSnapshot.toolCalls) {
+      // Focus on failed/blocked tool calls as they indicate pain
+      if (tc.outcome !== 'failure' && tc.outcome !== 'blocked') continue;
+
+      const toolName = tc.toolName;
+      if (!toolNameMap.has(toolName)) {
+        const pattern: PainPattern = { toolName };
+        if (tc.errorType) {
+          pattern.errorType = tc.errorType;
+        }
+        if (tc.filePath) {
+          pattern.pathRegex = escapeRegex(tc.filePath);
+        }
+        toolNameMap.set(toolName, pattern);
+      } else {
+        const existing = toolNameMap.get(toolName)!;
+        if (tc.errorType && !existing.errorType) {
+          existing.errorType = tc.errorType;
+        }
+        if (tc.filePath && !existing.pathRegex) {
+          existing.pathRegex = escapeRegex(tc.filePath);
+        }
+      }
+    }
+  }
+
+  return Array.from(toolNameMap.values());
+}
+
+/**
+ * Infer tool name from text by checking for known tool names.
+ * Returns the first matching known tool name, or null if none found.
+ */
+function inferToolName(text: string): string | null {
+  const lower = text.toLowerCase();
+  for (const tool of KNOWN_TOOLS) {
+    // Match as a standalone word to avoid false positives
+    // e.g., "bash" in "bash" or "bash command" but not in "ambush"
+    const regex = new RegExp(`\\b${tool}\\b`);
+    if (regex.test(lower)) {
+      return tool;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract a file path from text and return it as an escaped regex pattern.
+ * Returns the first path found, or null.
+ */
+function extractPathRegex(text: string): string | null {
+  const match = PATH_REGEX.exec(text);
+  if (match) {
+    return escapeRegex(match[0]);
+  }
+  return null;
+}
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ---------------------------------------------------------------------------
+// PrincipleCompiler
+// ---------------------------------------------------------------------------
+
+export class PrincipleCompiler {
+  private readonly stateDir: string;
+  private readonly collector: ReflectionContextCollector;
+
+  constructor(stateDir: string, trajectory: TrajectoryDatabase) {
+    this.stateDir = stateDir;
+    this.collector = new ReflectionContextCollector(stateDir, trajectory);
+  }
+
+  /**
+   * Compile a single principle into an auto-generated rule.
+   *
+   * Flow:
+   * 1. Collect reflection context
+   * 2. Extract pain patterns
+   * 3. Generate code from template
+   * 4. Validate generated code
+   * 5. Register in ledger
+   */
+  compileOne(principleId: string): CompileResult {
+    // Step 1: Collect context
+    const context = this.collector.collect(principleId);
+    if (!context) {
+      return { success: false, principleId, reason: 'no context' };
+    }
+
+    // Step 2: Extract patterns
+    const patterns = extractPatterns({
+      painEvents: context.painEvents,
+      sessionSnapshot: context.sessionSnapshot,
+    });
+
+    // Step 3: Generate code
+    const coversCondition = context.principle.triggerPattern || context.principle.text;
+    const code = generateFromTemplate(principleId, coversCondition, patterns);
+    if (!code) {
+      return { success: false, principleId, reason: 'no patterns' };
+    }
+
+    // Step 4: Validate
+    const validation = validateGeneratedCode(code);
+    if (!validation.valid) {
+      return {
+        success: false,
+        principleId,
+        reason: `validation failed: ${validation.errors.join('; ')}`,
+      };
+    }
+
+    // Step 5: Register
+    const registration = registerCompiledRule(this.stateDir, {
+      principleId,
+      codeContent: code,
+      coversCondition,
+    });
+
+    // Step 6: Persist code to disk so RuleHost can load it
+    createImplementationAssetDir(this.stateDir, registration.implementationId, '1', {
+      entrySource: code,
+    });
+
+    return {
+      success: true,
+      principleId,
+      ruleId: registration.ruleId,
+      implementationId: registration.implementationId,
+      code,
+    };
+  }
+
+  /**
+   * Compile all eligible principles (those with derivedFromPainIds).
+   */
+  compileAll(): CompileResult[] {
+    const contexts = this.collector.collectBatch();
+    return contexts.map((ctx) => {
+      try {
+        return this.compileOne(ctx.principle.id);
+      } catch (e) {
+        return { success: false, principleId: ctx.principle.id, reason: `unhandled: ${(e as Error).message}` };
+      }
+    });
+  }
+}

package/src/core/principle-compiler/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Principle Compiler — Barrel Export
+ *
+ * Re-exports all principle-compiler components for convenient importing.
+ */
+
+export { PrincipleCompiler, type CompileResult } from './compiler.js';
+export { validateGeneratedCode, type ValidationResult } from './code-validator.js';
+export { generateFromTemplate, type PainPattern } from './template-generator.js';
+export { registerCompiledRule, type RegisterInput, type RegisterResult } from './ledger-registrar.js';

package/src/core/principle-compiler/ledger-registrar.ts

@@ -0,0 +1,107 @@
+/**
+ * Ledger Registrar (Task 4)
+ *
+ * Registers a compiled rule into the principle tree ledger:
+ * 1. Creates a LedgerRule with type 'gate', enforcement 'block', status 'proposed'
+ * 2. Creates an Implementation with type 'code', lifecycleState 'candidate'
+ *
+ * IDEMPOTENCY: If the rule already exists, returns existing registration.
+ * ROLLBACK: If implementation creation fails after rule creation, attempts cleanup.
+ */
+
+import { createRule, createImplementation, loadLedger, deleteRule, type LedgerRule } from '../principle-tree-ledger.js';
+
+export interface RegisterInput {
+  principleId: string;
+  codeContent: string;
+  coversCondition: string;
+}
+
+export interface RegisterResult {
+  success: boolean;
+  ruleId: string;
+  implementationId: string;
+  codePath: string;
+}
+
+/**
+ * Register a compiled rule for a principle in the ledger.
+ *
+ * Idempotent: if rule already exists, returns existing registration.
+ * Atomic: if implementation creation fails, rolls back the rule.
+ */
+export function registerCompiledRule(stateDir: string, input: RegisterInput): RegisterResult {
+  const { principleId, codeContent, coversCondition } = input;
+
+  const ruleId = `R_${principleId}_auto`;
+  const implementationId = `IMPL_${principleId}_auto`;
+  const codePath = `compiled-rules/${principleId}/rule.ts`;
+
+  // Idempotency: skip if rule already exists
+  const existingLedger = loadLedger(stateDir);
+  if (existingLedger.tree.rules[ruleId]) {
+    const existingRule = existingLedger.tree.rules[ruleId];
+    return {
+      success: true,
+      ruleId,
+      implementationId: existingRule.implementationIds[0] ?? implementationId,
+      codePath,
+    };
+  }
+
+  const now = new Date().toISOString();
+
+  // Step 1: Create the rule
+  const rule: LedgerRule = {
+    id: ruleId,
+    version: 1,
+    name: `Auto-compiled rule for ${principleId}`,
+    description: `Automatically compiled gate rule generated from principle ${principleId}`,
+    type: 'gate',
+    triggerCondition: coversCondition,
+    enforcement: 'block',
+    action: codeContent,
+    principleId,
+    status: 'proposed',
+    coverageRate: 0,
+    falsePositiveRate: 0,
+    implementationIds: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  createRule(stateDir, rule);
+
+  // Step 2: Create the implementation (with rollback on failure)
+  try {
+    const implementation = {
+      id: implementationId,
+      ruleId,
+      type: 'code' as const,
+      path: codePath,
+      version: '1',
+      coversCondition,
+      coveragePercentage: 100,
+      lifecycleState: 'active' as const,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    createImplementation(stateDir, implementation);
+  } catch (implError) {
+    // Rollback: remove the orphaned rule
+    try {
+      deleteRule(stateDir, ruleId);
+    } catch {
+      // Best-effort rollback — log but don't mask the original error
+    }
+    throw implError;
+  }
+
+  return {
+    success: true,
+    ruleId,
+    implementationId,
+    codePath,
+  };
+}

package/src/core/principle-compiler/template-generator.ts

@@ -0,0 +1,108 @@
+/**
+ * Template Generator for Principle Compiler
+ *
+ * Generates RuleHost sandbox code from PainPattern descriptors.
+ * Produces self-contained JS modules with `export const meta` and
+ * `export function evaluate(input)` that can be loaded at runtime.
+ *
+ * SECURITY: All interpolated values use JSON.stringify or safe helpers
+ * to prevent code injection through principleId, coversCondition, or regex patterns.
+ */
+
+export interface PainPattern {
+  toolName: string;
+  pathRegex?: string;
+  commandRegex?: string;
+  contentRegex?: string;
+  errorType?: string;
+}
+
+/**
+ * Derives the auto-rule display name from a principle ID.
+ */
+function toAutoName(principleId: string): string {
+  return `Auto_${principleId}`;
+}
+
+/**
+ * Derives the auto-rule ID from a principle ID.
+ * Must match ledger-registrar convention: "P_066" => "R_P_066_auto"
+ */
+function toAutoRuleId(principleId: string): string {
+  return `R_${principleId}_auto`;
+}
+
+/**
+ * Builds a single `if` branch for a pain pattern.
+ *
+ * SECURITY: Uses `new RegExp(JSON.stringify(...))` instead of regex literals
+ * to prevent code injection through pathRegex/commandRegex/contentRegex values.
+ * principleId in reason uses JSON.stringify to prevent string breakout.
+ */
+function buildBranch(principleId: string, pattern: PainPattern): string {
+  const conditions: string[] = [];
+
+  conditions.push(`input.action.toolName === ${JSON.stringify(pattern.toolName)}`);
+
+  if (pattern.pathRegex) {
+    conditions.push(`new RegExp(${JSON.stringify(pattern.pathRegex)}).test(input.action.normalizedPath || '')`);
+  }
+
+  if (pattern.commandRegex) {
+    conditions.push(`new RegExp(${JSON.stringify(pattern.commandRegex)}).test(input.action.paramsSummary.command || '')`);
+  }
+
+  if (pattern.contentRegex) {
+    conditions.push(
+      `new RegExp(${JSON.stringify(pattern.contentRegex)}).test(input.action.paramsSummary.content || input.action.paramsSummary.new_string || '')`,
+    );
+  }
+
+  const guard = conditions.join(' && ');
+  const reason = `[${principleId}] Blocked by auto-generated rule`;
+
+  return (
+    `  if (${guard}) {\n` +
+    `    return { decision: 'block', matched: true, reason: ${JSON.stringify(reason)} };\n` +
+    `  }`
+  );
+}
+
+/**
+ * Generates sandbox-ready JS code from a principle ID and pain patterns.
+ *
+ * Returns `null` when `patterns` is empty.
+ */
+export function generateFromTemplate(
+  principleId: string,
+  coversCondition: string,
+  patterns: PainPattern[],
+): string | null {
+  if (patterns.length === 0) {
+    return null;
+  }
+
+  const name = toAutoName(principleId);
+  const ruleId = toAutoRuleId(principleId);
+  const compiledAt = new Date().toISOString();
+
+  const branches = patterns
+    .map((p) => buildBranch(principleId, p))
+    .join('\n');
+
+  return (
+    `// Auto-generated by Principle Compiler\n` +
+    `export const meta = {\n` +
+    `  name: ${JSON.stringify(name)},\n` +
+    `  version: '1.0.0',\n` +
+    `  ruleId: ${JSON.stringify(ruleId)},\n` +
+    `  coversCondition: ${JSON.stringify(coversCondition)},\n` +
+    `  compiledAt: ${JSON.stringify(compiledAt)},\n` +
+    `  sourcePrincipleId: ${JSON.stringify(principleId)},\n` +
+    `};\n\n` +
+    `export function evaluate(input) {\n` +
+    `${branches}\n` +
+    `  return { matched: false };\n` +
+    `}\n`
+  );
+}