A system returns:
status = not_configured
A normalization layer turns that into:
enabled = false
The second value is easier for a policy engine to consume.
It is also not what the system originally returned.
Someone decided that not_configured should mean false.
That decision happened before policy evaluation.
If the evidence package keeps only the normalized value, the interpretation disappears while its consequence survives.
That is the problem.
Raw observation and normalized fact are different evidence layers
Most systems do not produce evidence in the format a control policy wants.
Commands return text. APIs use vendor-specific fields. Configuration files use their own syntax. One source may say enabled, another 1, another active.
Normalization is necessary.
A typical path looks like this:
raw evidence
→ normalized fact
→ derived fact
→ policy input
→ policy result
The public CodeYourCompliance Evidence Contract already separates these layers.
The distinction is not about data formatting.
It is about where interpretation enters the evidence chain.
The raw observation records what the source returned.
The normalized fact records how the pipeline chose to represent it.
Those are related objects.
They are not the same object.
The same observation can produce different facts
The new public Transformation Provenance Example isolates this problem.
The synthetic raw evidence is held constant:
status = not_configured
Normalization version 0.1.0 applies this rule:
MAP_NOT_CONFIGURED_TO_FALSE
and produces:
enabled = false
state = resolved
Version 0.2.0 uses a different rule:
PRESERVE_NOT_CONFIGURED_AS_UNKNOWN
and produces:
enabled = null
state = unknown
Same raw observation.
Different transformation logic.
Different normalized fact.
The synthetic example deliberately holds the raw observation and target-state identifier constant so that only the transformation changes.
It does not establish which normalization rule is correct.
It establishes a narrower point:
same raw observation
+ transformation difference
→ normalized fact changed
→ target-state change is not established
by this difference alone
That boundary matters whenever normalized facts are later compared for drift or fed into policy evaluation.
Transformation provenance should travel with the fact
The public Transformation Provenance Contract records the minimum context needed to inspect that path.
The current pattern includes fields such as:
transformation:
name:
version:
rule_id:
rule_version:
input_ref:
input_field:
input_value:
output_field:
output_value:
output_state:
executed_at_utc:
This means a reviewer does not only see:
enabled = false
They can also determine which raw observation was consumed, which rule performed the mapping, which implementation version ran, and what output it produced.
That is provenance.
It is not attestation.
Transformation provenance is not transformation correctness
A versioned rule can still be wrong.
A documented mapping can still be unsuitable for a particular control.
A normalizer can contain a bug.
Recording:
rule_version = 0.2.0
does not prove that version 0.2.0 interpreted the source correctly.
It only makes that interpretation identifiable.
This is the same boundary discussed in The Collector Is Part of the Evidence: preserving how something entered the evidence chain is different from proving that the mechanism was correct.
The collector can be wrong.
The transformation can be wrong.
Provenance gives the reviewer something concrete to challenge.
Integrity does not solve the semantic problem
Hashing solves another problem.
Suppose the pipeline records:
source value:
not_configured
normalization:
not_configured → false
integrity:
verified
The integrity check can show that the normalized evidence object has not changed after sealing.
It cannot tell us whether false was the right interpretation in the first place.
A perfectly intact evidence package can preserve a bad transformation.
So these two claims need to remain separate:
integrity verification
!=
semantic correctness
Hashing protects the preserved object.
Transformation provenance explains how that object acquired its meaning.
Policy evaluation starts later than it looks
OPA may receive a clean object such as:
{
"enabled": false
}
From OPA’s perspective, that input is simple.
From an evidence perspective, it already contains history.
A useful trace is closer to:
control result
→ policy input
→ normalized fact
→ transformation rule
→ raw observation
→ collector
→ source system
This also connects to the admissibility boundary described in Invalid Evidence Is Not a Failed Control.
The policy engine is not where the evidence story begins.
By the time evaluation starts, collection and interpretation have already happened.
If those steps disappear, the final result may still be deterministic while the path that produced its input is not inspectable.
MAS TRM-inspired means engineering interpretation
This is not a claim that MAS TRM requires transformation metadata, rule versions, normalization schemas, OPA, or this implementation pattern.
The engineering question is narrower:
Can a reviewer determine how a raw system observation became the fact that was actually evaluated?
If not, the pipeline preserves the control result more carefully than the interpretation that created its input.
Public reference artifacts
The transformation provenance boundary is implemented as a public engineering artifact in the codeyourcompliance/evidence-validation-pipeline repository.
Main references:
The repository currently models transformation provenance through structured metadata and synthetic examples.
It does not yet cryptographically bind transformation or rule digests to normalized facts. It also does not implement automated transformation-version equivalence or regression testing, or repo-wide transformation provenance schema enforcement.
Those are separate implementation steps.
Origin and scope
CodeYourCompliance
Website:
GitHub: https://github.com/codeyourcompliance
Attribution is requested for forks, references, adaptations and technical discussions.
MAS TRM-inspired means engineering interpretation. This project does not provide legal, regulatory, audit, certification or compliance advice.