Server-set global variables like $::environment get overwritten by client facts

REPORTED PROBLEM
—
As per the docs (http://docs.puppetlabs.com/puppet/latest/reference/lang_facts_and_builtin_vars.html#variables-set-by-the-puppet-master) the puppet master sets the global $::environment variable to contain the name of the node's environment. However, if a node provides a fact with the name 'environment' that fact's value overrides the server-set environment.

The same happens with other server-set global variables, like $::servername and $::serverip.

As a result, modules can't reliably use these variables for whatever their intended purpose is.

If this is the intended behavior, then the docs should clarify this and discourage use of the server-set variables, because a misbehaving node can override them.

SOLUTION
—
After discussion with Eric Soerenson, we decided that it was best to make this an opt-in and that we are not adding a function - this for the sake of consistency between $facts, $trusted_facts, and $server_facts. This means:

At the same place where we currently set $trusted_facts we should also set $server_facts if users have opted in
The values set in $server_facts are the @server_facts set in the node by the compiler indirection + the current environment name
The user opts in by using the setting :trusted_server_facts
The setting is false by default
We issue a warning if any node parameter is overwritten
We need a ticket to add a deprecation for the opt-in being set to false
We need a ticket for 5.0.0 to remove the opt in and make $server_facts default, and to stop merging the server_facts into the node's parameters

When using puppet apply and trusted_server_facts is true, the $server_facts will be a hash with only the key environment set. The value for this key is the environment that was configured locally on the agent, or given on the command line (i.e. in this case there is no call to the master to compute what the master thinks the environment should be for the node).

an example $server_facts hash

{serverversion => 4.0.0, servername => v85ix8blah.delivery.puppetlabs.net, serverip => 10.32.115.182, environment => production}

QA
—
risk: high
probability: medium
severity: high (hard to debug, somewhat of a security issue, can spoof environment)
test layer: acceptance