Skip to main content
Jira progress: loading…

TRFM

Transformation Engines

1. Overview​

Transformation Engines (TRFM) are Micro Engines responsible for converting payloads between units, formats, and structural representations while preserving the semantic meaning of the signal.

TRFM engines are the “interoperability layer” of the computation chain: they normalize heterogeneous inputs into stable contracts and prepare outputs for aggregation, reporting, and federation exchange.

TRFM is an engine type in the MICE taxonomy. Concrete transformers are implemented as MEID-registered micro engines.

2. Design Principles​

  1. Semantic Preservation

    • Transformations may change representation (shape, units, encoding), but must not change what the signal means.

  2. Traceability

    • Every transformation must be traceable via contracts (schemas), options, and lineage stamps.
    • “What changed, why, and by which engine version” must be reconstructable.

  3. Deterministic

    • Same input + same transformer version + same options ⇒ same output.

  4. Reversible Where Possible

    • Some transforms are reversible (e.g., unit conversion).
    • When not reversible (e.g., classification), the engine must emit explicit mapping evidence.

3. Scope of Responsibility​

3.1 What TRFM engines do​

  • Unit conversion

    • e.g. kg → t, kWh → MWh, L → m³
    • Must preserve magnitude and declared unit metadata.

  • Format conversion

    • e.g. XML → JSON, CSV rows → JSON array, XLSX cell range → JSON payload.

  • Structural reshaping

    • Rename/re-key fields, unwrap/wrap nested structures, normalize time-series arrays.

  • Normalization

    • Harmonize naming conventions, canonicalize enums, enforce standard timestamp formats.

  • Classification / mapping (transform subtype)

    • e.g. EWC code → hazardous/non-hazardous label
    • Treatment codes → standardized treatment categories
    • These are transforms, but often tracked as classify/treatment operation tags.

3.2 What TRFM engines do not do​

  • ❌ Compute new business metrics (CALC)
  • ❌ Decide admissibility (VALI) — TRFM may prepare data, but validation is separate
  • ❌ Aggregate across entities (AGGR)
  • ❌ Estimate missing values (SEM)

Important: TRFM is allowed to change the payload representation.
VALI is not.

4. Where TRFM sits in execution chains​

Common placement patterns:

  • Before CALC: normalize heterogeneous input formats into canonical calculation contracts
  • After CALC: convert units/shape for reporting or aggregation layers
  • Federation boundary: map partner formats into ZAYAZ canonical signals/contracts

Example (conceptual):

INPUT → VALI(input contract)
     → TRFM(normalize units/shape)
     → CALC(compute)
     → TRFM(output shaping / unit harmonization)
     → VALI(output contract)
     → AGGR(roll-up)

5. Inputs​

TRFM engines typically receive:

  • A validated payload (raw input or computed output)
  • Transformation intent/options (target unit, target schema, mapping profile)
  • Registry references for mapping tables and schemas (ZAR addresses)

6. Outputs​

TRFM engines emit:

  • Transformed payload (canonical or target representation)
  • Transformation metadata (what mapping was applied)
  • Evidence hooks (mapping table refs, conversion factors, schema IDs)
  • Runtime provenance (lineage stamps, engine version)

TRFM outputs commonly feed:

  • CALC (normalized inputs)
  • AGGR (canonicalized measures)
  • Reporting pipelines (display-ready normalized payloads)
  • Federation exchange packs (portable normalized representations)

7. Canonical Identification​

  • Engine Type: TRFM
  • USO role: emits transformed representations of a signal while preserving semantics
  • Category: Micro Engine (MICE)

8. Registry view​

All engines tagged as transform:

Loading micro engines…

Note: some TRFM engines also carry operation tags such as classify, treatment, or adjust depending on the specific transformation semantics.

  • VALI — Validator Engines (admissibility and contract conformance)
  • CALC — Calculation Engines (produce metric values)
  • AGGR — Aggregation Engines (roll-ups across entities)
  • SEM — Stochastic Extrapolation Module (gap estimation)
Stable

GitHub RepoRequest for Change (RFC)