@goodandready/dsh-moa 0.2.75 → 0.2.77

package/lib/pipeline/mutation-tester.js

@@ -0,0 +1,323 @@
+/**
+ * DeepSeek Harness Mixture of Agents (MoA) — Mutation Testing Gate for Candidate Tests (#316)
+ *
+ * Injects deterministic AST-level fault mutations into candidate implementations and evaluates
+ * candidate test suites against mutants to calculate Mutation Score (killed vs survived mutants),
+ * eliminating false-positive and tautological tests before Judge arbitration.
+ */
+
+import vm from 'node:vm'
+import { MOA_EVENTS, emitEvent } from '../events.js'
+import { extractExecutableCode } from './runtime-profiler.js'
+
+/**
+ * Mutation operator patterns.
+ */
+export const MUTATION_OPERATORS = [
+  {
+    name: 'invert_strict_equality',
+    regex: /===/g,
+    replacement: '!==',
+    description: 'Replaced strict equality (===) with inequality (!==)',
+  },
+  {
+    name: 'invert_relational_lt',
+    regex: /<(?!=)/g,
+    replacement: '>=',
+    description: 'Replaced less-than (<) with greater-or-equal (>=)',
+  },
+  {
+    name: 'invert_relational_gt',
+    regex: />(?!=)/g,
+    replacement: '<=',
+    description: 'Replaced greater-than (>) with less-or-equal (<=)',
+  },
+  {
+    name: 'invert_logical_and',
+    regex: /&&/g,
+    replacement: '||',
+    description: 'Replaced logical AND (&&) with logical OR (||)',
+  },
+  {
+    name: 'invert_arithmetic_plus',
+    regex: /(?<=\w\s*)\+(?=\s*\w)/g,
+    replacement: '-',
+    description: 'Replaced addition (+) with subtraction (-)',
+  },
+  {
+    name: 'invert_boolean_true',
+    regex: /\btrue\b/g,
+    replacement: 'false',
+    description: 'Replaced literal true with false',
+  },
+  {
+    name: 'mutate_return_zero',
+    regex: /return\s+0;/g,
+    replacement: 'return 1;',
+    description: 'Mutated return 0 to return 1',
+  },
+]
+
+/**
+ * Generates an array of mutant variations from a single source code string.
+ *
+ * @param {string} sourceCode
+ * @param {object} [options]
+ * @returns {Array<object>} Up to maxMutants mutant objects
+ */
+export function generateMutants(sourceCode, options = {}) {
+  const maxMutants = Math.min(10, Math.max(1, options.maxMutants || 5))
+  const mutants = []
+  if (!sourceCode || typeof sourceCode !== 'string') return mutants
+
+  for (const op of MUTATION_OPERATORS) {
+    let match
+    const re = new RegExp(op.regex.source, op.regex.flags)
+    while ((match = re.exec(sourceCode)) !== null) {
+      const idx = match.index
+      const len = match[0].length
+      const mutantCode = sourceCode.slice(0, idx) + op.replacement + sourceCode.slice(idx + len)
+
+      mutants.push({
+        id: mutants.length + 1,
+        operator: op.name,
+        description: op.description,
+        originalSnippet: match[0],
+        replacementSnippet: op.replacement,
+        mutantCode,
+      })
+
+      if (mutants.length >= maxMutants) return mutants
+    }
+  }
+
+  return mutants
+}
+
+/**
+ * Runs a test script against an implementation in an isolated VM context.
+ *
+ * @param {string} codeToExecute
+ * @param {number} [timeoutMs=1000]
+ * @returns {{ ok: boolean, error: string | null }}
+ */
+function executeScript(codeToExecute, timeoutMs = 1000) {
+  const sandbox = {
+    console: { log: () => {}, warn: () => {}, error: () => {} },
+    assert: (cond, msg) => { if (!cond) throw new Error(msg || 'Assertion failed'); },
+    Math, Date, Array, Object, String, Number, Boolean, Set, Map, JSON,
+  }
+  sandbox.assert.equal = (a, b) => { if (a !== b) throw new Error(`Assertion failed: ${a} !== ${b}`); }
+  sandbox.assert.strictEqual = (a, b) => { if (a !== b) throw new Error(`Assertion failed: ${a} !== ${b}`); }
+  sandbox.assert.ok = (v) => { if (!v) throw new Error('Assertion failed: falsy value'); }
+
+  try {
+    const context = vm.createContext(sandbox)
+    const script = new vm.Script(codeToExecute)
+    script.runInContext(context, { timeout: timeoutMs })
+    return { ok: true, error: null }
+  } catch (err) {
+    return { ok: false, error: err.message }
+  }
+}
+
+/**
+ * Evaluates a candidate's implementation against generated mutants.
+ *
+ * @param {string} rawText - Candidate text containing code or tests
+ * @param {object} [options]
+ * @returns {object} Mutation testing report
+ */
+export function auditCandidateMutations(rawText, options = {}) {
+  const { minMutationScore = 0.7, maxMutants = 5, timeoutMs = 1000 } = options
+  const code = extractExecutableCode(rawText)
+
+  if (!code || !code.trim()) {
+    return {
+      passed: true,
+      mutationScore: 100,
+      totalMutants: 0,
+      killedCount: 0,
+      survivedCount: 0,
+      mutants: [],
+      summary: 'Mutation Testing: No code to mutate.',
+    }
+  }
+
+  // 1. Verify baseline executes cleanly
+  const baseline = executeScript(code, timeoutMs)
+  if (!baseline.ok) {
+    return {
+      passed: false,
+      mutationScore: 0,
+      totalMutants: 0,
+      killedCount: 0,
+      survivedCount: 0,
+      mutants: [],
+      error: `Baseline test execution failed: ${baseline.error}`,
+      summary: `Baseline execution failed (${baseline.error}).`,
+    }
+  }
+
+  // 2. Generate mutations on the code
+  const mutants = generateMutants(code, { maxMutants })
+  if (mutants.length === 0) {
+    return {
+      passed: true,
+      mutationScore: 100,
+      totalMutants: 0,
+      killedCount: 0,
+      survivedCount: 0,
+      mutants: [],
+      summary: 'Mutation Testing: Code contains no mutable operators.',
+    }
+  }
+
+  // 3. Test each mutant
+  let killedCount = 0
+  let survivedCount = 0
+  const evaluatedMutants = []
+
+  for (const m of mutants) {
+    const res = executeScript(m.mutantCode, timeoutMs)
+    if (!res.ok) {
+      // Mutant was killed (good! The test broke as expected)
+      killedCount++
+      evaluatedMutants.push({
+        ...m,
+        status: 'KILLED',
+        reason: res.error,
+      })
+    } else {
+      // Mutant survived (bad! Code was broken but test passed anyway)
+      survivedCount++
+      evaluatedMutants.push({
+        ...m,
+        status: 'SURVIVED',
+        reason: 'Test suite passed despite injected fault.',
+      })
+    }
+  }
+
+  const mutationRatio = Number((killedCount / mutants.length).toFixed(2))
+  const mutationScore = Math.round(mutationRatio * 100)
+  const passed = mutationRatio >= minMutationScore
+
+  const summary = passed
+    ? `🧬 Mutation Testing: PASSED (Score ${mutationScore}%). Killed ${killedCount}/${mutants.length} mutant(s).`
+    : `⚠️ Mutation Testing: WEAK TESTS (Score ${mutationScore}% < ${Math.round(minMutationScore * 100)}%). ${survivedCount} mutant(s) survived undetected.`
+
+  return {
+    passed,
+    mutationScore,
+    mutationRatio,
+    totalMutants: mutants.length,
+    killedCount,
+    survivedCount,
+    mutants: evaluatedMutants,
+    summary,
+  }
+}
+
+/**
+ * Runs the Mutation Testing Gate across all candidate solutions.
+ *
+ * @param {Array<object>} candidates
+ * @param {object} [options]
+ * @returns {object} Mutation gate report
+ */
+export function runMutationGate(candidates, options = {}) {
+  const { ctx, runId, onProgress, minMutationScore = 0.70 } = options
+  const results = []
+
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    return {
+      results: [],
+      passedCount: 0,
+      mutationDirective: null,
+    }
+  }
+
+  for (let i = 0; i < candidates.length; i++) {
+    const cand = candidates[i]
+    const text = typeof cand === 'string' ? cand : cand.output || cand.text || cand.code || ''
+    const report = auditCandidateMutations(text, { minMutationScore, ...options })
+
+    if (typeof cand === 'object' && cand !== null) {
+      cand.mutationReport = report
+      cand.mutationScore = report.mutationScore
+    }
+
+    results.push({
+      candidateIndex: i,
+      model: cand?.model || `Candidate ${i + 1}`,
+      report,
+    })
+
+    if (ctx) {
+      emitEvent(ctx, MOA_EVENTS.MUTATION_COMPLETE, {
+        runId,
+        candidateIndex: i,
+        mutationScore: report.mutationScore,
+        killedCount: report.killedCount,
+        totalMutants: report.totalMutants,
+        passed: report.passed,
+      })
+    }
+  }
+
+  const passedCount = results.filter((r) => r.report.passed).length
+
+  if (typeof onProgress === 'function' && results.length > 0) {
+    const summaryList = results.map((r) => `Ref ${r.candidateIndex + 1}: ${r.report.mutationScore}%`).join(', ')
+    onProgress(`🧬 *Mutation Testing Gate*: ${summaryList}\n`)
+  }
+
+  const mutationDirective = formatMutationDirective(results)
+
+  return {
+    results,
+    passedCount,
+    mutationDirective,
+  }
+}
+
+/**
+ * Formats mutation testing results into a prompt directive for the Judge.
+ *
+ * @param {Array<object>} results
+ * @returns {string|null}
+ */
+export function formatMutationDirective(results) {
+  if (!Array.isArray(results) || results.length === 0) return null
+
+  const lines = [
+    '### 🧬 RUNTIME MUTATION TESTING & FAULT INJECTION REPORT',
+    'Evaluation of test robustness against synthetic fault injection (killing code mutants):',
+  ]
+
+  for (const r of results) {
+    const label = `Candidate ${r.candidateIndex + 1}`
+    const rep = r.report
+    if (rep.totalMutants === 0) {
+      lines.push(`- **${label}**: ℹ️ No mutable operators found in test suite.`)
+    } else if (rep.passed) {
+      lines.push(
+        `- **${label}**: ✅ **RESILIENT TESTS** (Score ${rep.mutationScore}%) — Killed ${rep.killedCount}/${rep.totalMutants} fault mutants.`
+      )
+    } else {
+      lines.push(
+        `- **${label}**: ⚠️ **WEAK/TAUTOLOGICAL TESTS** (Score ${rep.mutationScore}%) — ${rep.survivedCount}/${rep.totalMutants} mutant(s) survived! The tests pass even when logic is inverted.`
+      )
+      for (const m of (rep.mutants || []).filter((m) => m.status === 'SURVIVED')) {
+        lines.push(`  * ${m.description} [Survived]`)
+      }
+    }
+  }
+
+  lines.push(
+    '\n**Judge Quality Mandate**: Prefer solutions whose test suites have a high Mutation Score. Solutions with surviving mutants have weak or tautological tests that do not genuinely verify behavior.'
+  )
+
+  return lines.join('\n')
+}

package/lib/pipeline/runner.js

@@ -18,6 +18,10 @@ import { stageSynthesis } from './synthesis.js'
 import { stagePromotion } from './promotion.js'
 import { applySyntaxFilter, formatSyntaxDirective } from './syntax-filter.js'
 import { stageEarlyConsensus } from './early-consensus.js'
+import { runSecurityAuditGate } from './security-fuzzer.js'
+import { runCoveVerificationGate } from './cove-verifier.js'
+import { runProfilerGate } from './runtime-profiler.js'
+import { runMutationGate } from './mutation-tester.js'
 import { emitEvent, MOA_EVENTS } from '../events.js'
 
 export async function runMoAPipeline({
@@ -199,6 +203,72 @@ export async function runMoAPipeline({
     return { error: new Error('Turn aborted') }
   }
 
+  // Pre-Stage 5.8: Chain-of-Verification (CoVe) Fact-Checking Gate (#314)
+  let coveDirective = null
+  let coveGateResult = null
+  if (preset?.cove_verification_enabled) {
+    coveGateResult = runCoveVerificationGate(
+      syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      ctxStage,
+      {
+        ctx,
+        runId,
+        onProgress,
+        maxQuestions: preset.cove_max_questions || 5,
+      }
+    )
+    coveDirective = coveGateResult.coveDirective
+  }
+
+  // Pre-Stage 5.9: Adversarial White-Hat Security Fuzzing Gate (#302)
+  let securityDirective = null
+  let securityGateResult = null
+  if (preset?.security_gate_enabled) {
+    securityGateResult = runSecurityAuditGate(
+      syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      {
+        ctx,
+        runId,
+        onProgress,
+        strictVeto: preset.security_gate_strict_veto !== false,
+      }
+    )
+    securityDirective = securityGateResult.securityDirective
+  }
+
+  // Pre-Stage 5.10: Runtime CPU & Memory Profiler Gate (#315)
+  let profilerDirective = null
+  let profilerGateResult = null
+  if (preset?.profiler_gate_enabled) {
+    profilerGateResult = runProfilerGate(
+      syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      {
+        ctx,
+        runId,
+        onProgress,
+        iterations: preset.profiler_iterations || 100,
+        timeoutMs: preset.profiler_timeout_ms || 2000,
+      }
+    )
+    profilerDirective = profilerGateResult.profilerDirective
+  }
+
+  // Pre-Stage 5.11: Mutation Testing & Fault Injection Gate (#316)
+  let mutationDirective = null
+  let mutationGateResult = null
+  if (preset?.mutation_testing_enabled) {
+    mutationGateResult = runMutationGate(
+      syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+      {
+        ctx,
+        runId,
+        onProgress,
+        minMutationScore: preset.min_mutation_score ?? 0.70,
+      }
+    )
+    mutationDirective = mutationGateResult.mutationDirective
+  }
+
   // Pre-Stage 6: Dynamic Consensus Threshold & Multi-Judge Escalation (#300)
   const escalationResult = evaluateJudgeEscalation({
     candidateOutputs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
@@ -249,7 +319,7 @@ export async function runMoAPipeline({
     preset: effectivePreset,
     successfulRefs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
     referenceOutputs, primaryJudge: effectivePrimaryJudge,
-    userPrompt, judgeCriteria: ctxStage.judgeCriteria, prices, maxTokens: ctxStage.maxTokens,
+    userPrompt, judgeCriteria: [ctxStage.judgeCriteria, coveDirective, securityDirective, profilerDirective, mutationDirective].filter(Boolean).join('\n\n'), prices, maxTokens: ctxStage.maxTokens,
     callLlm, signal, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     isFastMode: ctxStage.isFastMode, collectedCtx: ctxStage.collectedCtx, startTime,
   })
@@ -307,7 +377,7 @@ export async function runMoAPipeline({
     }
   }
 
-  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, pruningDirective, ctxStage.stackAwareDirective, ctxStage.developerPreferencesDirective].filter(Boolean).join("\n\n") || null
+  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, coveDirective, securityDirective, profilerDirective, mutationDirective, pruningDirective, ctxStage.stackAwareDirective, ctxStage.developerPreferencesDirective].filter(Boolean).join("\n\n") || null
 
   // Stage 7: Synthesis Phase
   const synthRes = await stageSynthesis({

package/lib/pipeline/runtime-profiler.js

@@ -0,0 +1,270 @@
+/**
+ * DeepSeek Harness Mixture of Agents (MoA) — Runtime CPU & Memory Profiler Gate (#315)
+ *
+ * Micro-benchmarks candidate code execution duration, ops/sec throughput, and heap memory usage
+ * in an isolated sandbox with hard timeout protection to guide Judge selection towards
+ * algorithmically optimal solutions.
+ */
+
+import vm from 'node:vm'
+import { MOA_EVENTS, emitEvent } from '../events.js'
+
+/**
+ * Extracts executable JavaScript code from markdown fences or raw code.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function extractExecutableCode(text) {
+  if (!text || typeof text !== 'string') return ''
+  const jsFenceMatch = text.match(/```(?:javascript|js|node)\s*\n([\s\S]*?)\n```/i)
+  if (jsFenceMatch && jsFenceMatch[1]) {
+    return jsFenceMatch[1]
+  }
+  const anyFenceMatch = text.match(/```\w*\s*\n([\s\S]*?)\n```/)
+  if (anyFenceMatch && anyFenceMatch[1]) {
+    return anyFenceMatch[1]
+  }
+  return text
+}
+
+/**
+ * Profiles code execution in an isolated VM sandbox.
+ *
+ * @param {string} rawCode - Candidate source code or markdown
+ * @param {object} [options]
+ * @returns {object} Profiler report
+ */
+export function profileCodeExecution(rawCode, options = {}) {
+  const {
+    iterations = 100,
+    timeoutMs = 2000,
+  } = options
+
+  const code = extractExecutableCode(rawCode)
+  if (!code || !code.trim()) {
+    return {
+      passed: false,
+      durationMs: 0,
+      heapBytesUsed: 0,
+      opsPerSec: 0,
+      iterations: 0,
+      error: 'Empty or unexecutable code provided for profiling.',
+      summary: 'Profiler skipped: no executable code.',
+    }
+  }
+
+  // Initial sandbox built-ins to ignore when scanning for user functions
+  const initialKeys = new Set([
+    'console', 'Math', 'Date', 'Array', 'Object', 'String', 'Number',
+    'Boolean', 'Set', 'Map', 'JSON', 'parseInt', 'parseFloat',
+    'globalThis', 'global', '__mainFn', '__benchFn', '__benchArg'
+  ])
+
+  const sandbox = {
+    console: { log: () => {}, warn: () => {}, error: () => {} },
+    Math,
+    Date,
+    Array,
+    Object,
+    String,
+    Number,
+    Boolean,
+    Set,
+    Map,
+    JSON,
+    parseInt,
+    parseFloat,
+  }
+  sandbox.globalThis = sandbox
+  sandbox.global = sandbox
+
+  // Convert export declarations to var / global assignments
+  const cleanCode = code
+    .replace(/^\s*export\s+default\s+/gm, 'globalThis.__mainFn = ')
+    .replace(/^\s*export\s+(?:async\s+)?function\s+([a-zA-Z0-9_]+)/gm, 'function $1')
+    .replace(/^\s*export\s+const\s+([a-zA-Z0-9_]+)/gm, 'var $1')
+    .replace(/^\s*import\s+.*?;?\s*$/gm, '// [import stripped for benchmark]')
+
+  try {
+    const context = vm.createContext(sandbox)
+    // Run candidate code once to evaluate top-level declarations
+    const setupScript = new vm.Script(cleanCode)
+    setupScript.runInContext(context, { timeout: Math.min(1000, timeoutMs) })
+
+    // Find entrypoint function: either __mainFn or any user-defined function on sandbox
+    let targetFn = sandbox.__mainFn
+    if (typeof targetFn !== 'function') {
+      const userKeys = Object.keys(sandbox).filter((k) => !initialKeys.has(k) && typeof sandbox[k] === 'function')
+      if (userKeys.length > 0) {
+        targetFn = sandbox[userKeys[userKeys.length - 1]]
+      }
+    }
+
+    sandbox.__benchFn = targetFn || null
+    sandbox.__benchArg = 10
+
+    let benchScript
+    if (typeof sandbox.__benchFn === 'function') {
+      benchScript = new vm.Script(`
+        try {
+          __benchFn();
+        } catch (_) {
+          try { __benchFn(__benchArg); } catch (__) {}
+        }
+      `)
+    } else {
+      benchScript = new vm.Script(`(() => { ${cleanCode} })()`)
+    }
+
+    // Warm-up run
+    benchScript.runInContext(context, { timeout: Math.min(1000, timeoutMs) })
+
+    // Measure memory and time
+    const startMem = process.memoryUsage().heapUsed
+    const startHr = process.hrtime.bigint()
+
+    for (let i = 0; i < iterations; i++) {
+      benchScript.runInContext(context, { timeout: Math.min(500, timeoutMs) })
+    }
+
+    const endHr = process.hrtime.bigint()
+    const endMem = process.memoryUsage().heapUsed
+
+    const totalNs = Number(endHr - startHr)
+    const durationMs = Number((totalNs / 1_000_000).toFixed(3))
+    const avgLatencyMs = Number((durationMs / iterations).toFixed(4))
+    const heapBytesUsed = Math.max(0, endMem - startMem)
+    const opsPerSec = durationMs > 0 ? Math.round((iterations / (durationMs / 1000))) : 0
+
+    return {
+      passed: true,
+      durationMs,
+      avgLatencyMs,
+      heapBytesUsed,
+      opsPerSec,
+      iterations,
+      error: null,
+      summary: `⚡ Profiler: ${iterations} iter in ${durationMs}ms (${opsPerSec.toLocaleString()} ops/sec, ~${Math.round(heapBytesUsed / 1024)}KB heap).`,
+    }
+  } catch (err) {
+    const isTimeout = err.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT' || err.message?.includes('timed out')
+    return {
+      passed: false,
+      durationMs: isTimeout ? timeoutMs : 0,
+      avgLatencyMs: 0,
+      heapBytesUsed: 0,
+      opsPerSec: 0,
+      iterations: 0,
+      error: isTimeout ? `Execution timed out after ${timeoutMs}ms (possible infinite loop or catastrophic complexity)` : err.message,
+      summary: isTimeout ? `🚨 Profiler: TIMEOUT (${timeoutMs}ms exceeded)` : `⚠️ Profiler Error: ${err.message}`,
+    }
+  }
+}
+
+/**
+ * Runs runtime performance profiling across all candidate solutions.
+ *
+ * @param {Array<object>} candidates
+ * @param {object} [options]
+ * @returns {object} Profiler gate result
+ */
+export function runProfilerGate(candidates, options = {}) {
+  const {
+    ctx,
+    runId,
+    onProgress,
+    iterations = 100,
+    timeoutMs = 2000,
+  } = options
+
+  const results = []
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    return {
+      results: [],
+      fastestCandidate: null,
+      profilerDirective: null,
+    }
+  }
+
+  for (let i = 0; i < candidates.length; i++) {
+    const cand = candidates[i]
+    const text = typeof cand === 'string' ? cand : cand.output || cand.text || cand.code || ''
+    const report = profileCodeExecution(text, { iterations, timeoutMs })
+
+    if (typeof cand === 'object' && cand !== null) {
+      cand.profilerReport = report
+    }
+
+    results.push({
+      candidateIndex: i,
+      model: cand?.model || `Candidate ${i + 1}`,
+      report,
+    })
+
+    if (ctx) {
+      emitEvent(ctx, MOA_EVENTS.PROFILER_COMPLETE, {
+        runId,
+        candidateIndex: i,
+        durationMs: report.durationMs,
+        heapBytesUsed: report.heapBytesUsed,
+        opsPerSec: report.opsPerSec,
+        passed: report.passed,
+        error: report.error,
+      })
+    }
+  }
+
+  // Sort passing candidates by throughput (opsPerSec) descending
+  const valid = results.filter((r) => r.report.passed).sort((a, b) => b.report.opsPerSec - a.report.opsPerSec)
+  const fastestCandidate = valid[0] || null
+
+  if (typeof onProgress === 'function' && results.length > 0) {
+    const summaryList = results.map((r) => `Ref ${r.candidateIndex + 1}: ${r.report.passed ? `${r.report.durationMs}ms` : 'TIMEOUT'}`).join(', ')
+    onProgress(`⚡ *Runtime Profiler Gate*: ${summaryList}\n`)
+  }
+
+  const profilerDirective = formatProfilerDirective(results)
+
+  return {
+    results,
+    fastestCandidate,
+    profilerDirective,
+  }
+}
+
+/**
+ * Formats profiler benchmarks into a clear prompt directive for the Judge.
+ *
+ * @param {Array<object>} results
+ * @returns {string|null}
+ */
+export function formatProfilerDirective(results) {
+  if (!Array.isArray(results) || results.length === 0) return null
+
+  const lines = [
+    '### ⚡ RUNTIME PERFORMANCE & CPU/MEMORY PROFILER REPORT',
+    'Objective micro-benchmarks across candidates (100 iterations in isolated sandbox):',
+  ]
+
+  for (const r of results) {
+    const label = `Candidate ${r.candidateIndex + 1}`
+    const rep = r.report
+    if (rep.passed) {
+      const kb = Math.round(rep.heapBytesUsed / 1024)
+      lines.push(
+        `- **${label}**: ⏱️ **${rep.durationMs}ms** total (~${rep.avgLatencyMs}ms/op) | **${rep.opsPerSec.toLocaleString()} ops/sec** | Heap: ~${kb} KB`
+      )
+    } else {
+      lines.push(
+        `- **${label}**: ❌ **PERFORMANCE FAILURE**: ${rep.error}`
+      )
+    }
+  }
+
+  lines.push(
+    '\n**Judge Performance Guideline**: Penalize solutions with excessive latency or timeout failures. Prefer implementations demonstrating clean algorithmic scalability and minimal memory footprint.'
+  )
+
+  return lines.join('\n')
+}