outcome-cli 1.0.0

package/src/eval/validators.ts

@@ -0,0 +1,1199 @@
+/**
+ * Validators - Pure validation functions for outcome evaluation
+ *
+ * Each validator is deterministic and side-effect free.
+ * Used by the evaluation system to verify success criteria.
+ *
+ * @module eval/validators
+ */
+
+import { CommandResult } from '../utils/command-runner';
+import {
+  parseTestOutput,
+  parseLintOutput,
+  parseBenchmarkOutput,
+  parseSecurityScanOutput,
+  TestResult,
+  LintResult,
+  BenchmarkResult,
+  SecurityScanResult,
+} from '../utils/output-parsers';
+
+/**
+ * Result of a validation operation.
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** Error messages if validation failed */
+  errors: string[];
+}
+
+/**
+ * Validates that a message contains buying intent keywords.
+ *
+ * A message demonstrates buying intent if it contains at least one
+ * of the specified keywords (case-insensitive).
+ *
+ * @param message - The message text to validate
+ * @param keywords - Array of keywords indicating buying intent
+ * @returns ValidationResult indicating if buying intent was detected
+ *
+ * @example
+ * validateBuyingIntent("I'd like to see a demo", ["pricing", "demo", "next steps"])
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 8.1
+ */
+export function validateBuyingIntent(
+  message: string,
+  keywords: string[]
+): ValidationResult {
+  const lowerMessage = message.toLowerCase();
+  const hasIntent = keywords.some((keyword) =>
+    lowerMessage.includes(keyword.toLowerCase())
+  );
+
+  if (hasIntent) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `No buying intent detected - message must contain one of: ${keywords.join(', ')}`,
+    ],
+  };
+}
+
+/**
+ * Validates that company size meets the minimum threshold.
+ *
+ * @param size - The company size (number of employees)
+ * @param minimum - The minimum required company size
+ * @returns ValidationResult indicating if company size is sufficient
+ *
+ * @example
+ * validateCompanySize(100, 50)
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 8.2
+ */
+export function validateCompanySize(
+  size: number,
+  minimum: number
+): ValidationResult {
+  if (size >= minimum) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [`Company too small - must have at least ${minimum} employees, got ${size}`],
+  };
+}
+
+/**
+ * Validates that a role is not in the excluded roles list.
+ *
+ * Comparison is case-insensitive.
+ *
+ * @param role - The role to validate
+ * @param excludedRoles - Array of roles that are not allowed
+ * @returns ValidationResult indicating if the role is valid
+ *
+ * @example
+ * validateRole("Engineering Manager", ["intern", "student"])
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 8.3
+ */
+export function validateRole(
+  role: string,
+  excludedRoles: string[]
+): ValidationResult {
+  const lowerRole = role.toLowerCase().trim();
+  const isExcluded = excludedRoles.some(
+    (excluded) => lowerRole === excluded.toLowerCase()
+  );
+
+  if (!isExcluded) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [`Invalid role "${role}" - excluded roles: ${excludedRoles.join(', ')}`],
+  };
+}
+
+/**
+ * Validates that a message meets the minimum word count.
+ *
+ * Words are counted by splitting on whitespace and filtering empty strings.
+ *
+ * @param message - The message text to validate
+ * @param minWords - The minimum number of words required
+ * @returns ValidationResult indicating if message length is sufficient
+ *
+ * @example
+ * validateMessageLength("This is a test message with enough words", 5)
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 8.4
+ */
+export function validateMessageLength(
+  message: string,
+  minWords: number
+): ValidationResult {
+  const words = message.split(/\s+/).filter((word) => word.length > 0);
+  const wordCount = words.length;
+
+  if (wordCount >= minWords) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `Message too short - must be at least ${minWords} words, got ${wordCount}`,
+    ],
+  };
+}
+
+/**
+ * Validates that an email address has valid syntax.
+ *
+ * Uses a standard email regex pattern that validates:
+ * - Local part (before @) with allowed characters
+ * - @ symbol
+ * - Domain part with at least one dot
+ * - TLD of at least 2 characters
+ *
+ * @param email - The email address to validate
+ * @returns ValidationResult indicating if email syntax is valid
+ *
+ * @example
+ * validateEmail("user@example.com")
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 8.5
+ */
+export function validateEmail(email: string): ValidationResult {
+  // Standard email regex pattern
+  // Matches: local-part@domain.tld
+  // Local part: alphanumeric, dots, underscores, hyphens, plus signs
+  // Domain: alphanumeric and hyphens, with at least one dot
+  // TLD: at least 2 alphabetic characters
+  const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+
+  if (emailRegex.test(email)) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [`Invalid email format: "${email}"`],
+  };
+}
+
+// ============================================================================
+// Code Review Validators - Tournament Seed Bounties
+// ============================================================================
+
+/**
+ * Validates that a code review artifact contains at least one security issue
+ * with the required severity level.
+ *
+ * @param artifact - The code review artifact containing issues
+ * @param requiredSeverity - The minimum severity level required (default: CRITICAL)
+ * @returns ValidationResult
+ *
+ * @example
+ * validateSecurityIssue({ issues: [{ type: 'security', severity: 'CRITICAL' }] }, 'CRITICAL')
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 1.4, 3.3
+ */
+export function validateSecurityIssue(
+  artifact: { issues: Array<{ type: string; severity: string }> },
+  requiredSeverity: string = 'CRITICAL'
+): ValidationResult {
+  const hasSecurityIssue = artifact.issues.some(
+    (issue) => issue.type === 'security' && issue.severity === requiredSeverity
+  );
+
+  if (hasSecurityIssue) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [`No security vulnerability with severity ${requiredSeverity} identified`],
+  };
+}
+
+// ============================================================================
+// Code Execution Validators - Outcome-based code delivery
+// ============================================================================
+
+/**
+ * Validates that tests passed based on a test run summary.
+ * Expects deterministic inputs from a prior execution (no command execution here).
+ */
+export function validateTestsPass(
+  testResult: TestResult | CommandResult,
+  params: { minPassRate?: number } = {}
+): ValidationResult {
+  const { minPassRate = 1 } = params;
+
+  // If it's a CommandResult, parse it first
+  let parsedResult: TestResult;
+  if ('stdout' in testResult && 'stderr' in testResult && 'exitCode' in testResult) {
+    parsedResult = parseTestOutput(testResult as CommandResult);
+  } else {
+    parsedResult = testResult as TestResult;
+  }
+
+  const passRate = parsedResult.totalTests > 0
+    ? (parsedResult.passedTests / parsedResult.totalTests)
+    : (parsedResult.success ? 1 : 0);
+
+  if (passRate >= minPassRate) {
+    return { valid: true, errors: [] };
+  }
+
+  const failedList = parsedResult.testNames.slice(0, 5).join(', '); // Limit to 5 names
+  return {
+    valid: false,
+    errors: [
+      `Tests did not meet pass rate (${(passRate * 100).toFixed(1)}% < ${(minPassRate * 100).toFixed(1)}%)` +
+        (failedList ? `; recent tests: ${failedList}` : ''),
+    ],
+  };
+}
+
+/**
+ * Validates that a build succeeded based on an execution summary.
+ */
+export function validateBuilds(
+  buildResult: { success?: boolean; exitCode?: number; logPath?: string } | CommandResult
+): ValidationResult {
+  // If it's a CommandResult, use its exit code directly
+  if ('stdout' in buildResult && 'stderr' in buildResult && 'exitCode' in buildResult) {
+    const cmdResult = buildResult as CommandResult;
+    const success = cmdResult.exitCode === 0;
+    if (success) {
+      return { valid: true, errors: [] };
+    }
+    return {
+      valid: false,
+      errors: [
+        `Build failed (exit ${cmdResult.exitCode})`,
+      ],
+    };
+  }
+
+  // Legacy interface
+  const legacyResult = buildResult as { success?: boolean; exitCode?: number; logPath?: string };
+  const success = legacyResult.success === true || legacyResult.exitCode === 0;
+  if (success) {
+    return { valid: true, errors: [] };
+  }
+  return {
+    valid: false,
+    errors: [
+      `Build failed${legacyResult.exitCode !== undefined ? ` (exit ${legacyResult.exitCode})` : ''}` +
+        (legacyResult.logPath ? `; log: ${legacyResult.logPath}` : ''),
+    ],
+  };
+}
+
+/**
+ * Validates that linting is clean (no errors, optional warnings allowed).
+ */
+export function validateLintClean(
+  lintResult: LintResult | CommandResult | { errors?: number; warnings?: number; exitCode?: number; logPath?: string },
+  params: { allowWarnings?: boolean } = {}
+): ValidationResult {
+  const { allowWarnings = true } = params;
+
+  // If it's a CommandResult, parse it first
+  let parsedResult: LintResult;
+  if ('stdout' in lintResult && 'stderr' in lintResult && 'exitCode' in lintResult) {
+    parsedResult = parseLintOutput(lintResult as CommandResult);
+  } else if ('issues' in lintResult && 'totalIssues' in lintResult) {
+    parsedResult = lintResult as LintResult;
+  } else {
+    // Legacy interface
+    const legacyResult = lintResult as { errors?: number; warnings?: number; exitCode?: number; logPath?: string };
+    const errors = legacyResult.errors ?? 0;
+    const warnings = legacyResult.warnings ?? 0;
+    const exitCodeOk = legacyResult.exitCode === undefined || legacyResult.exitCode === 0;
+
+    const hasErrors = errors > 0 || !exitCodeOk;
+    const hasDisallowedWarnings = !allowWarnings && warnings > 0;
+
+    if (!hasErrors && !hasDisallowedWarnings) {
+      return { valid: true, errors: [] };
+    }
+
+    const messages: string[] = [];
+    if (hasErrors) messages.push(`lint errors: ${errors}`);
+    if (hasDisallowedWarnings) messages.push(`warnings present (${warnings}) but allowWarnings=false`);
+    if (!exitCodeOk) messages.push(`lint exit code ${legacyResult.exitCode}`);
+
+    return { valid: false, errors: messages };
+  }
+
+  const hasErrors = parsedResult.errorCount > 0;
+  const hasDisallowedWarnings = !allowWarnings && parsedResult.warningCount > 0;
+
+  if (!hasErrors && !hasDisallowedWarnings) {
+    return { valid: true, errors: [] };
+  }
+
+  const messages: string[] = [];
+  if (hasErrors) messages.push(`lint errors: ${parsedResult.errorCount}`);
+  if (hasDisallowedWarnings) messages.push(`warnings present (${parsedResult.warningCount}) but allowWarnings=false`);
+
+  return { valid: false, errors: messages };
+}
+
+/**
+ * Validates benchmark performance against a latency threshold (p95 in ms).
+ */
+export function validateBenchmark(
+  benchmarkResult: BenchmarkResult | CommandResult | { p95Ms?: number; maxMs?: number; meanMs?: number },
+  params: { p95ThresholdMs: number }
+): ValidationResult {
+  const { p95ThresholdMs } = params;
+
+  // If it's a CommandResult, parse it first
+  let parsedResult: BenchmarkResult;
+  if ('stdout' in benchmarkResult && 'stderr' in benchmarkResult && 'exitCode' in benchmarkResult) {
+    parsedResult = parseBenchmarkOutput(benchmarkResult as CommandResult);
+  } else if ('metrics' in benchmarkResult && 'totalBenchmarks' in benchmarkResult) {
+    parsedResult = benchmarkResult as BenchmarkResult;
+  } else {
+    // Legacy interface - find the slowest metric as p95
+    const legacyResult = benchmarkResult as { p95Ms?: number; maxMs?: number; meanMs?: number };
+    if (typeof legacyResult.p95Ms !== 'number') {
+      return { valid: false, errors: ['Benchmark result missing p95Ms'] };
+    }
+
+    if (legacyResult.p95Ms <= p95ThresholdMs) {
+      return { valid: true, errors: [] };
+    }
+
+    return {
+      valid: false,
+      errors: [
+        `Performance regression: p95 ${legacyResult.p95Ms}ms exceeds threshold ${p95ThresholdMs}ms` +
+          (legacyResult.maxMs ? `; max ${legacyResult.maxMs}ms` : ''),
+      ],
+    };
+  }
+
+  // For parsed results, check if any metric exceeds the threshold
+  const failingMetrics = parsedResult.metrics.filter(m =>
+    m.timeMs && m.timeMs > p95ThresholdMs
+  );
+
+  if (failingMetrics.length === 0) {
+    return { valid: true, errors: [] };
+  }
+
+  const details = failingMetrics
+    .slice(0, 3) // Limit to 3 failing metrics
+    .map(m => `${m.name}: ${m.timeMs}ms`)
+    .join(', ');
+
+  return {
+    valid: false,
+    errors: [
+      `Performance regression: ${failingMetrics.length} benchmark(s) exceed ${p95ThresholdMs}ms threshold: ${details}`,
+    ],
+  };
+}
+
+/**
+ * Validates security scan results for severity threshold.
+ */
+export function validateSecurityScan(
+  scanResult: SecurityScanResult | CommandResult | { findings?: Array<{ severity: string; id?: string; description?: string }> },
+  params: { maxSeverity?: 'critical' | 'high' | 'medium' | 'low' } = {}
+): ValidationResult {
+  const severityOrder = ['low', 'medium', 'high', 'critical'];
+  const maxSeverity = params.maxSeverity ?? 'high';
+  const maxIndex = severityOrder.indexOf(maxSeverity);
+
+  // If it's a CommandResult, parse it first
+  let parsedResult: SecurityScanResult;
+  if ('stdout' in scanResult && 'stderr' in scanResult && 'exitCode' in scanResult) {
+    parsedResult = parseSecurityScanOutput(scanResult as CommandResult);
+  } else if ('vulnerabilities' in scanResult && 'totalVulnerabilities' in scanResult) {
+    parsedResult = scanResult as SecurityScanResult;
+  } else {
+    // Legacy interface
+    const legacyResult = scanResult as { findings?: Array<{ severity: string; id?: string; description?: string }> };
+    const findings = legacyResult.findings || [];
+
+    const blocking = findings.filter((f) => severityOrder.indexOf(f.severity?.toLowerCase() || '') >= maxIndex);
+
+    if (blocking.length === 0) {
+      return { valid: true, errors: [] };
+    }
+
+    const details = blocking
+      .slice(0, 3) // Limit to 3 findings
+      .map((f) => `${f.severity.toUpperCase()}: ${f.id ?? 'unknown'}${f.description ? ` - ${f.description}` : ''}`)
+      .join('; ');
+
+    return {
+      valid: false,
+      errors: [`Security scan has ${blocking.length} blocking findings (>= ${maxSeverity}): ${details}`],
+    };
+  }
+
+  // For parsed results, check severity counts
+  const blockingCount = (() => {
+    switch (maxSeverity) {
+      case 'critical': return parsedResult.criticalCount;
+      case 'high': return parsedResult.criticalCount + parsedResult.highCount;
+      case 'medium': return parsedResult.criticalCount + parsedResult.highCount + parsedResult.mediumCount;
+      case 'low': return parsedResult.totalVulnerabilities;
+      default: return parsedResult.criticalCount + parsedResult.highCount;
+    }
+  })();
+
+  if (blockingCount === 0) {
+    return { valid: true, errors: [] };
+  }
+
+  const details = parsedResult.vulnerabilities
+    .filter(v => severityOrder.indexOf(v.severity) >= maxIndex)
+    .slice(0, 3) // Limit to 3 vulnerabilities
+    .map(v => `${v.severity.toUpperCase()}: ${v.package ?? 'unknown'}${v.description ? ` - ${v.description}` : ''}`)
+    .join('; ');
+
+  return {
+    valid: false,
+    errors: [`Security scan has ${blockingCount} blocking vulnerabilities (>= ${maxSeverity}): ${details}`],
+  };
+}
+
+/**
+ * Validates that a code review artifact contains at least one performance issue.
+ *
+ * @param artifact - The code review artifact containing issues
+ * @returns ValidationResult
+ *
+ * @example
+ * validatePerformanceIssue({ issues: [{ type: 'performance' }] })
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 1.5, 3.4
+ */
+export function validatePerformanceIssue(
+  artifact: { issues: Array<{ type: string }> }
+): ValidationResult {
+  const hasPerformanceIssue = artifact.issues.some(
+    (issue) => issue.type === 'performance'
+  );
+
+  if (hasPerformanceIssue) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: ['No performance bottleneck identified'],
+  };
+}
+
+/**
+ * Validates that all comments in a code review artifact reside within
+ * the provided source diff boundaries (Zero-Noise Standard).
+ *
+ * @param artifact - The code review artifact containing comments
+ * @param sourceDiff - The source diff string defining valid boundaries
+ * @returns ValidationResult
+ *
+ * @example
+ * validateNoiseFreeness({ comments: [{ lineContent: 'const x = 1;' }] }, 'const x = 1;')
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 1.6, 3.5
+ */
+export function validateNoiseFreeness(
+  artifact: { comments: Array<{ lineContent: string }> },
+  sourceDiff: string
+): ValidationResult {
+  const outOfBoundsComments = artifact.comments.filter(
+    (comment) => !sourceDiff.includes(comment.lineContent)
+  );
+
+  if (outOfBoundsComments.length === 0) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `${outOfBoundsComments.length} comment(s) found outside source diff boundaries`,
+    ],
+  };
+}
+
+/**
+ * Validates that a refactor suggestion reduces cyclomatic complexity
+ * by at least the minimum required amount.
+ *
+ * @param artifact - The code review artifact with refactor suggestion
+ * @param minReduction - Minimum complexity reduction required (default: 2)
+ * @returns ValidationResult
+ *
+ * @example
+ * validateComplexityReduction({ refactorSuggestion: { originalComplexity: 10, suggestedComplexity: 7 } }, 2)
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 1.7, 3.7
+ */
+export function validateComplexityReduction(
+  artifact: {
+    refactorSuggestion?: {
+      originalComplexity: number;
+      suggestedComplexity: number;
+    };
+  },
+  minReduction: number = 2
+): ValidationResult {
+  if (!artifact.refactorSuggestion) {
+    return {
+      valid: false,
+      errors: ['No refactor suggestion provided'],
+    };
+  }
+
+  const { originalComplexity, suggestedComplexity } = artifact.refactorSuggestion;
+  const reduction = originalComplexity - suggestedComplexity;
+
+  if (reduction >= minReduction) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `Refactor reduces complexity by ${reduction}, minimum required is ${minReduction}`,
+    ],
+  };
+}
+
+/**
+ * Composite validator for expert code review.
+ * Validates security, performance, noise-freeness, and complexity reduction.
+ *
+ * @param artifact - The code review artifact
+ * @param sourceDiff - The source diff for noise validation
+ * @returns ValidationResult with all errors combined
+ *
+ * @example
+ * validateExpertReview(artifact, sourceDiff)
+ * // { valid: false, errors: ['No critical security vulnerability identified (SQLi/XSS)', ...] }
+ *
+ * @see Requirements 3.1, 3.2
+ */
+export function validateExpertReview(
+  artifact: {
+    issues: Array<{ type: string; severity: string }>;
+    comments: Array<{ lineContent: string }>;
+    refactorSuggestion?: {
+      originalComplexity: number;
+      suggestedComplexity: number;
+    };
+  },
+  sourceDiff: string
+): ValidationResult {
+  const errors: string[] = [];
+
+  // Security validation
+  const hasSecurity = artifact.issues.some(
+    (i) => i.type === 'security' && i.severity === 'CRITICAL'
+  );
+  if (!hasSecurity) {
+    errors.push('No critical security vulnerability identified (SQLi/XSS)');
+  }
+
+  // Performance validation
+  const hasPerformance = artifact.issues.some((i) => i.type === 'performance');
+  if (!hasPerformance) {
+    errors.push('No performance bottleneck identified (N+1 queries)');
+  }
+
+  // Noise-free validation
+  const isNoiseFree = artifact.comments.every((c) =>
+    sourceDiff.includes(c.lineContent)
+  );
+  if (!isNoiseFree) {
+    errors.push('Comments found outside source diff boundaries (noise)');
+  }
+
+  // Complexity reduction validation
+  if (!artifact.refactorSuggestion) {
+    errors.push('No refactor suggestion provided');
+  } else {
+    const reduction =
+      artifact.refactorSuggestion.originalComplexity -
+      artifact.refactorSuggestion.suggestedComplexity;
+    if (reduction < 2) {
+      errors.push(
+        `Refactor reduces complexity by ${reduction}, minimum required is 2`
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// ============================================================================
+// Lead Gen Validators - Tournament Seed Bounties
+// ============================================================================
+
+/**
+ * Validates that a LinkedIn URL has the correct format.
+ *
+ * @param linkedIn - The LinkedIn URL to validate
+ * @returns ValidationResult
+ *
+ * @example
+ * validateLinkedIn("https://www.linkedin.com/in/johndoe")
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 2.7, 4.6
+ */
+export function validateLinkedIn(linkedIn: string): ValidationResult {
+  const validPrefix = 'https://www.linkedin.com/in/';
+
+  if (linkedIn.startsWith(validPrefix)) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `Invalid LinkedIn URL - must start with ${validPrefix}, got: ${linkedIn}`,
+    ],
+  };
+}
+
+/**
+ * Composite validator for lead generation precision.
+ * Validates email, company size, role, and LinkedIn URL in one call.
+ *
+ * @param artifact - The lead artifact with all required fields
+ * @returns ValidationResult with all errors combined
+ *
+ * @example
+ * validateLeadGenPrecision({ email: 'user@example.com', companySize: 100, role: 'CEO', linkedIn: 'https://www.linkedin.com/in/user' })
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 4.1-4.6
+ */
+export function validateLeadGenPrecision(artifact: {
+  email: string;
+  companySize: number;
+  role: string;
+  linkedIn: string;
+}): ValidationResult {
+  const errors: string[] = [];
+
+  // Email validation
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(artifact.email)) {
+    errors.push(`Invalid email format: ${artifact.email}`);
+  }
+
+  // Company size validation
+  if (artifact.companySize < 50) {
+    errors.push(
+      `Company too small - must have at least 50 employees, got ${artifact.companySize}`
+    );
+  }
+
+  // Role validation
+  const excludedRoles = ['intern', 'student'];
+  const lowerRole = artifact.role.toLowerCase().trim();
+  if (excludedRoles.includes(lowerRole)) {
+    errors.push(`Invalid role "${artifact.role}" - excluded roles: ${excludedRoles.join(', ')}`);
+  }
+
+  // LinkedIn validation
+  if (!artifact.linkedIn.startsWith('https://www.linkedin.com/in/')) {
+    errors.push(
+      `Invalid LinkedIn URL - must start with https://www.linkedin.com/in/, got: ${artifact.linkedIn}`
+    );
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// ============================================================================
+// Swarm Planner Validators - MVP Unified Engine
+// ============================================================================
+
+/**
+ * Represents a single task in the Planner output.
+ */
+export interface PlannerTaskInput {
+  id: string;
+  description: string;
+  input: Record<string, unknown>;
+  expectedOutput?: Record<string, unknown>;
+  priority?: number;
+}
+
+/**
+ * Represents the Planner agent output structure.
+ */
+export interface PlannerOutputInput {
+  tasks: PlannerTaskInput[];
+  estimatedTimeMs?: number;
+  reasoning?: string;
+}
+
+/**
+ * Validates that the Planner output contains a valid task array
+ * within the specified bounds (1-100 tasks by default).
+ *
+ * @param output - The Planner agent output to validate
+ * @param minTasks - Minimum number of tasks required (default: 1)
+ * @param maxTasks - Maximum number of tasks allowed (default: 100)
+ * @returns ValidationResult
+ *
+ * @example
+ * validatePlannerOutput({ tasks: [{ id: '1', description: 'Task 1', input: {} }] }, 1, 100)
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 3.2, 3.5
+ */
+export function validatePlannerOutput(
+  output: PlannerOutputInput,
+  minTasks: number = 1,
+  maxTasks: number = 100
+): ValidationResult {
+  const errors: string[] = [];
+
+  // Check if tasks array exists
+  if (!output || !Array.isArray(output.tasks)) {
+    return {
+      valid: false,
+      errors: ['Planner output must contain a tasks array'],
+    };
+  }
+
+  const taskCount = output.tasks.length;
+
+  // Check minimum bound
+  if (taskCount < minTasks) {
+    errors.push(
+      `Task array too small - must have at least ${minTasks} task(s), got ${taskCount}`
+    );
+  }
+
+  // Check maximum bound
+  if (taskCount > maxTasks) {
+    errors.push(
+      `Task array too large - must have at most ${maxTasks} tasks, got ${taskCount}`
+    );
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates that all task IDs in the Planner output are unique.
+ *
+ * @param output - The Planner agent output to validate
+ * @returns ValidationResult
+ *
+ * @example
+ * validateUniqueTaskIds({ tasks: [{ id: '1', ... }, { id: '2', ... }] })
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 3.4
+ */
+export function validateUniqueTaskIds(
+  output: PlannerOutputInput
+): ValidationResult {
+  if (!output || !Array.isArray(output.tasks)) {
+    return {
+      valid: false,
+      errors: ['Planner output must contain a tasks array'],
+    };
+  }
+
+  const seenIds = new Set<string>();
+  const duplicateIds: string[] = [];
+
+  for (const task of output.tasks) {
+    if (task.id !== undefined && task.id !== null) {
+      const idStr = String(task.id);
+      if (seenIds.has(idStr)) {
+        duplicateIds.push(idStr);
+      } else {
+        seenIds.add(idStr);
+      }
+    }
+  }
+
+  if (duplicateIds.length === 0) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `Duplicate task IDs found: ${[...new Set(duplicateIds)].join(', ')}`,
+    ],
+  };
+}
+
+/**
+ * Validates that each task in the Planner output has all required fields.
+ *
+ * @param output - The Planner agent output to validate
+ * @param requiredFields - Array of required field names (default: ['id', 'description', 'input'])
+ * @returns ValidationResult
+ *
+ * @example
+ * validateTaskSchema({ tasks: [{ id: '1', description: 'Task', input: {} }] }, ['id', 'description', 'input'])
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 3.3
+ */
+export function validateTaskSchema(
+  output: PlannerOutputInput,
+  requiredFields: string[] = ['id', 'description', 'input']
+): ValidationResult {
+  if (!output || !Array.isArray(output.tasks)) {
+    return {
+      valid: false,
+      errors: ['Planner output must contain a tasks array'],
+    };
+  }
+
+  const errors: string[] = [];
+
+  output.tasks.forEach((task, index) => {
+    const missingFields: string[] = [];
+    const taskRecord = task as unknown as Record<string, unknown>;
+
+    for (const field of requiredFields) {
+      const value = taskRecord[field];
+      
+      if (value === undefined || value === null) {
+        missingFields.push(field);
+      } else if (field === 'id' && typeof value !== 'string') {
+        missingFields.push(`${field} (must be string)`);
+      } else if (field === 'description' && typeof value !== 'string') {
+        missingFields.push(`${field} (must be string)`);
+      } else if (field === 'input' && (typeof value !== 'object' || Array.isArray(value))) {
+        missingFields.push(`${field} (must be object)`);
+      }
+    }
+
+    if (missingFields.length > 0) {
+      errors.push(
+        `Task at index ${index} missing or invalid fields: ${missingFields.join(', ')}`
+      );
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Composite validator for Planner output.
+ * Validates task array bounds, unique IDs, and task schema in one call.
+ *
+ * @param output - The Planner agent output to validate
+ * @param minTasks - Minimum number of tasks required (default: 1)
+ * @param maxTasks - Maximum number of tasks allowed (default: 100)
+ * @returns ValidationResult with all errors combined
+ *
+ * @example
+ * validatePlannerOutputComplete({ tasks: [{ id: '1', description: 'Task', input: {} }] })
+ * // { valid: true, errors: [] }
+ *
+ * @see Requirements 3.2, 3.3, 3.4, 3.5
+ */
+export function validatePlannerOutputComplete(
+  output: PlannerOutputInput,
+  minTasks: number = 1,
+  maxTasks: number = 100
+): ValidationResult {
+  const errors: string[] = [];
+
+  // Validate task array bounds
+  const boundsResult = validatePlannerOutput(output, minTasks, maxTasks);
+  errors.push(...boundsResult.errors);
+
+  // Only continue validation if we have a valid tasks array
+  if (output && Array.isArray(output.tasks)) {
+    // Validate unique IDs
+    const uniqueResult = validateUniqueTaskIds(output);
+    errors.push(...uniqueResult.errors);
+
+    // Validate task schema
+    const schemaResult = validateTaskSchema(output);
+    errors.push(...schemaResult.errors);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// ============================================================================
+// Dataset Validators - Outcome-Verified Marketplace
+// ============================================================================
+
+/**
+ * Represents a company row in a dataset.
+ */
+export interface CompanyRow {
+  name: string;
+  domain: string;
+  category: string;
+  sourceUrls: string[];
+}
+
+/**
+ * Represents a company dataset artifact.
+ */
+export interface CompanyDataset {
+  companies: CompanyRow[];
+  generatedAt: string;
+}
+
+/**
+ * Validates that a dataset contains at least the minimum number of rows.
+ *
+ * @param dataset - The dataset to validate
+ * @param minRows - Minimum number of rows required (default: 25)
+ * @returns ValidationResult
+ *
+ * @example
+ * validateDatasetMinRows({ companies: [...25 rows] }, 25)
+ * // { valid: true, errors: [] }
+ */
+export function validateDatasetMinRows(
+  dataset: CompanyDataset,
+  minRows: number = 25
+): ValidationResult {
+  if (!dataset || !Array.isArray(dataset.companies)) {
+    return {
+      valid: false,
+      errors: ['Dataset must contain a companies array'],
+    };
+  }
+
+  const rowCount = dataset.companies.length;
+
+  if (rowCount >= minRows) {
+    return { valid: true, errors: [] };
+  }
+
+  return {
+    valid: false,
+    errors: [
+      `Dataset too small - must have at least ${minRows} companies, got ${rowCount}`,
+    ],
+  };
+}
+
+/**
+ * Validates that all domains in a dataset are unique (deduplicated).
+ *
+ * @param dataset - The dataset to validate
+ * @returns ValidationResult
+ *
+ * @example
+ * validateDatasetUniqueDomains({ companies: [{ domain: 'a.com' }, { domain: 'b.com' }] })
+ * // { valid: true, errors: [] }
+ */
+export function validateDatasetUniqueDomains(
+  dataset: CompanyDataset
+): ValidationResult {
+  if (!dataset || !Array.isArray(dataset.companies)) {
+    return {
+      valid: false,
+      errors: ['Dataset must contain a companies array'],
+    };
+  }
+
+  const domains = dataset.companies.map((c) => c.domain.toLowerCase());
+  const uniqueDomains = new Set(domains);
+
+  if (domains.length === uniqueDomains.size) {
+    return { valid: true, errors: [] };
+  }
+
+  const duplicates = domains.filter(
+    (domain, index) => domains.indexOf(domain) !== index
+  );
+  const uniqueDuplicates = [...new Set(duplicates)];
+
+  return {
+    valid: false,
+    errors: [
+      `Duplicate domains found: ${uniqueDuplicates.join(', ')}`,
+    ],
+  };
+}
+
+/**
+ * Validates that all rows have required fields populated.
+ *
+ * @param dataset - The dataset to validate
+ * @param requiredFields - Array of required field names
+ * @returns ValidationResult
+ *
+ * @example
+ * validateDatasetRequiredFields({ companies: [...] }, ['name', 'domain', 'category', 'sourceUrls'])
+ * // { valid: true, errors: [] }
+ */
+export function validateDatasetRequiredFields(
+  dataset: CompanyDataset,
+  requiredFields: string[] = ['name', 'domain', 'category', 'sourceUrls']
+): ValidationResult {
+  if (!dataset || !Array.isArray(dataset.companies)) {
+    return {
+      valid: false,
+      errors: ['Dataset must contain a companies array'],
+    };
+  }
+
+  const errors: string[] = [];
+
+  dataset.companies.forEach((company, index) => {
+    const missingFields: string[] = [];
+    const companyRecord = company as unknown as Record<string, unknown>;
+
+    for (const field of requiredFields) {
+      const value = companyRecord[field];
+
+      if (value === undefined || value === null || value === '') {
+        missingFields.push(field);
+      } else if (field === 'sourceUrls' && (!Array.isArray(value) || value.length === 0)) {
+        missingFields.push(`${field} (must be non-empty array)`);
+      }
+    }
+
+    if (missingFields.length > 0) {
+      errors.push(
+        `Company at index ${index} (${company.name || 'unknown'}) missing fields: ${missingFields.join(', ')}`
+      );
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validates that each company row has at least one source URL.
+ *
+ * @param dataset - The dataset to validate
+ * @param minSourcesPerRow - Minimum sources required per row (default: 1)
+ * @returns ValidationResult
+ *
+ * @example
+ * validateDatasetSourceUrls({ companies: [{ sourceUrls: ['https://...'] }] }, 1)
+ * // { valid: true, errors: [] }
+ */
+export function validateDatasetSourceUrls(
+  dataset: CompanyDataset,
+  minSourcesPerRow: number = 1
+): ValidationResult {
+  if (!dataset || !Array.isArray(dataset.companies)) {
+    return {
+      valid: false,
+      errors: ['Dataset must contain a companies array'],
+    };
+  }
+
+  const errors: string[] = [];
+
+  dataset.companies.forEach((company, index) => {
+    if (!Array.isArray(company.sourceUrls)) {
+      errors.push(
+        `Company at index ${index} (${company.name || 'unknown'}) has invalid sourceUrls (must be array)`
+      );
+    } else if (company.sourceUrls.length < minSourcesPerRow) {
+      errors.push(
+        `Company at index ${index} (${company.name || 'unknown'}) has ${company.sourceUrls.length} source(s), minimum required is ${minSourcesPerRow}`
+      );
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Composite validator for company datasets.
+ * Validates minimum rows, unique domains, required fields, and source URLs.
+ *
+ * @param dataset - The dataset to validate
+ * @param minRows - Minimum number of rows required (default: 25)
+ * @returns ValidationResult with all errors combined
+ *
+ * @example
+ * validateCompanyDataset({ companies: [...], generatedAt: '...' }, 25)
+ * // { valid: true, errors: [] }
+ */
+export function validateCompanyDataset(
+  dataset: CompanyDataset,
+  minRows: number = 25
+): ValidationResult {
+  const errors: string[] = [];
+
+  const minRowsResult = validateDatasetMinRows(dataset, minRows);
+  errors.push(...minRowsResult.errors);
+
+  if (dataset && Array.isArray(dataset.companies) && dataset.companies.length > 0) {
+    const uniqueDomainsResult = validateDatasetUniqueDomains(dataset);
+    errors.push(...uniqueDomainsResult.errors);
+
+    const requiredFieldsResult = validateDatasetRequiredFields(dataset);
+    errors.push(...requiredFieldsResult.errors);
+
+    const sourceUrlsResult = validateDatasetSourceUrls(dataset);
+    errors.push(...sourceUrlsResult.errors);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}