Jira progress: loading…
TG-NORMALIZE-SIGNAL
TrustGate Signal Normalizer Engine
0. Identity
Loading identity…
Depends on module:
1. Purpose
The TrustGate Signal Normalizer Engine converts parsed inbound signals into canonical TrustGate runtime structures.
It is the second execution stage in the TrustGate micro-engine pipeline and receives parsed outputs from the Signal Parser Engine. Its role is to ensure that units, identifiers, timestamps, schema versions, numeric formats, country codes, currency references, and value structures are normalized before downstream validation, scoring, replay, DAL anchoring, and federation exchange.
The normalizer prevents downstream engines from having to interpret raw source-specific representations. All downstream TrustGate engines operate on normalized signals.
2. Position within TrustGate
External Signal
│
▼
Signal Parser Engine
│
▼
Signal Normalizer Engine
│
▼
Metadata Enrichment Engine
│
▼
Validation Engine
│
▼
Trust Scoring Engine
The normalizer SHALL execute after successful parsing and before metadata enrichment.
The normalizer SHALL NOT perform trust scoring, validation-rule execution, routing decisions, or assurance attestation generation. Those responsibilities belong to later engines.
3. Canonical Identity
| Property | Value |
|---|---|
| Engine Name | Signal Normalizer Engine |
| MEID | MEID_SIGNAL_NORMALIZE_NORMALIZER |
| Canonical CMI | vera.TG-NORM.ENGINE.NORMALIZER.1_0_0 |
| ZAR Code | TGN02 |
| CMI Kind | ENGINE |
| Owner Module | Verification & Assurance |
| Runtime Type | Micro-Engine |
| Execution Order | 2 |
| Replay Support | Native |
| DAL Anchoring | Yes |
| Federation Aware | Yes |
| Criticality | Critical |
3.1. MEID Binding
The MEID is stable across engine versions.
MEID_SIGNAL_NORMALIZE_NORMALIZER
├── vera.TG-NORM.ENGINE.NORMALIZER.1_0_0
├── vera.TG-NORM.ENGINE.NORMALIZER.1_1_0
└── vera.TG-NORM.ENGINE.NORMALIZER.2_0_0
The CMI changes whenever the executable implementation, normalization logic, supported schema mappings, or runtime behavior changes.
4. Runtime Responsibilities
The Signal Normalizer Engine is responsible for:
| Responsibility | Description |
|---|---|
| Unit normalization | Converts quantities into canonical UCUM or ZAYAZ-approved units. |
| Timestamp normalization | Converts timestamps into canonical UTC ISO 8601 format. |
| Identifier normalization | Normalizes supplier IDs, ECO Numbers, invoice IDs, source IDs, and registry identifiers. |
| Numeric normalization | Converts localized decimal separators, precision, scale, and numeric representations. |
| Currency normalization | Normalizes ISO 4217 currency codes and prepares currency conversion metadata. |
| Country normalization | Normalizes ISO 3166 country codes according to the active SSSR profile. |
| Schema version normalization | Resolves compatible schema versions and produces normalized schema metadata. |
| String canonicalization | Applies whitespace trimming, Unicode normalization, and stable casing rules. |
| Hash preparation | Produces canonicalized normalized payloads suitable for deterministic hashing. |
| Replay preparation | Emits replay-safe normalization metadata. |
The engine SHALL preserve the original parsed value in the runtime artifact when transformation loss or ambiguity is possible.
5. Inputs
5.1. CSI Inputs
TrustGate CSI identifiers SHALL follow the canonical CSI grammar:
<csi_module>.<csi_component>.<csi_kind>.<csi_name>.<csi_version_maj>_<csi_version_min>
| CSI | Required | Description |
|---|---|---|
vera.TG-PARSE.OUTPUT.PARSED-SIGNAL.v1_0 | Yes | Parsed canonical object emitted by the Signal Parser Engine. |
vera.TG-PARSE.OUTPUT.PARSE-METADATA.v1_0 | Yes | Parse diagnostics and source metadata. |
siss.SSSR.INPUT.SCHEMA-PROFILE.v1_0 | Yes | Active SSSR schema profile for the signal type. |
siss.SSSR.INPUT.UNIT-DICTIONARY.v1_0 | Conditional | Unit conversion mappings for numeric quantities. |
siss.ZAR.INPUT.ARTIFACT-METADATA.v1_0 | Conditional | ZAR metadata for originating parser, schema, or source connector. |
vera.ZSSR.INPUT.ROUTING-HINT.v1_0 | Optional | Routing hint passed from upstream routing context. |
5.2. Input Object
{
"event_id": "01JBF0W4Y5T2V5W3N5X7A1B2C",
"source_event_id": "01JBF0VRAW0000000000000001",
"eco_number": "ECO-A123",
"signal_type": "invoice",
"parsed_signal": {
"invoice_id": "INV-203948",
"supplier": {
"supplier_id": "eco-578-123-456-789",
"country": "NO"
},
"line": {
"quantity": {
"value": "100,00",
"unit": "kilogram"
},
"price": {
"amount": "2 500,50",
"currency": "eur"
}
},
"dates": {
"invoice_date": "30/09/2025"
}
},
"parse_metadata": {
"parser_cmi": "vera.TG-PARSE.ENGINE.SIGNAL.1_0_0",
"source_format": "json",
"input_hash": "sha256:8f91..."
}
}
6. Outputs
6.1. CSI Outputs
| CSI | Description |
|---|---|
vera.TG-NORM.OUTPUT.NORMALIZED-SIGNAL.v1_0 | Normalized TrustGate signal object. |
vera.TG-NORM.OUTPUT.NORMALIZATION-METADATA.v1_0 | Normalization diagnostics, rule references, and conversion metadata. |
vera.TG-NORM.OUTPUT.UNIT-CONSISTENCY.v1_0 | Unit consistency score and conversion evidence. |
vera.TG-NORM.OUTPUT.REPLAY-METADATA.v1_0 | Replay inputs required to reproduce normalization. |
siss.USO.OUTPUT.LINEAGE-EVENT.v1_0 | USO lineage event for the normalization operation. |
6.2. Output Object
{
"event_id": "01JBF0WNORM000000000000001",
"event_type": "trustgate.normalized",
"event_time": "2025-10-25T09:40:12Z",
"version": "1.0",
"input_ref": {
"source_event_id": "01JBF0W4Y5T2V5W3N5X7A1B2C",
"source_cmi": "vera.TG-PARSE.ENGINE.SIGNAL.1_0_0"
},
"eco_number": "ECO-A123",
"normalized_signal": {
"invoice_id": "INV-203948",
"supplier": {
"supplier_id": "ECO-578-123-456-789",
"country": "NOR"
},
"line": {
"quantity_si": {
"value": 100.0,
"unit": "kg"
},
"price": {
"amount": 2500.50,
"currency": "EUR"
}
},
"dates": {
"invoice_date": "2025-09-30T00:00:00Z"
}
},
"normalization_metadata": {
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"unit_ruleset_cmi": "siss.SSSR.RULESET.UNIT-MAP.1_0_0",
"country_ruleset_cmi": "siss.SSSR.RULESET.COUNTRY-MAP.1_0_0",
"normalization_status": "SUCCESS",
"unit_consistency": 1.0
}
}
7. Processing Pipeline
Receive Parsed Signal
│
▼
Load Active Schema Profile
│
▼
Normalize Identifiers
│
▼
Normalize Units
│
▼
Normalize Numbers and Currency
│
▼
Normalize Dates and Timestamps
│
▼
Canonicalize Strings
│
▼
Generate Normalization Metadata
│
▼
Emit Normalized Signal
│
▼
Emit Lineage Event
8. Runtime Algorithm
function normalize(parsed_event):
assert parsed_event.event_type in supported_event_types
schema_profile = load_sssr_profile(parsed_event.signal_type)
unit_dictionary = load_unit_dictionary(schema_profile)
identifier_rules = load_identifier_rules(schema_profile)
normalized = deep_copy(parsed_event.parsed_signal)
normalized.identifiers = normalize_identifiers(parsed_event.identifiers, identifier_rules)
normalized.units = normalize_units(parsed_event.units, unit_dictionary)
normalized.numbers = normalize_numbers(parsed_event.numbers)
normalized.timestamps = normalize_timestamps(parsed_event.timestamps)
normalized.strings = canonicalize_strings(parsed_event.strings)
metadata = build_normalization_metadata(
source_event_id = parsed_event.event_id,
engine_cmi = current_cmi,
schema_profile = schema_profile,
ruleset_refs = active_rulesets
)
output_hash = sha256(canonical_json(normalized))
emit_normalized_signal(normalized, metadata, output_hash)
emit_lineage_event(parsed_event, normalized, metadata)
return normalized
The algorithm SHALL be deterministic for identical input payloads, active rulesets, and CMI versions.
9. Runtime Configuration
{
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"strict_unit_normalization": true,
"strict_identifier_normalization": true,
"allow_lossy_conversion": false,
"canonical_timestamp_timezone": "UTC",
"country_code_standard": "ISO_3166_1_ALPHA_3",
"currency_code_standard": "ISO_4217",
"numeric_precision": {
"default_scale": 6,
"rounding_mode": "HALF_UP"
},
"accepted_unit_systems": [
"UCUM",
"SI",
"ZAYAZ_CANONICAL"
],
"preserve_original_values": true
}
10. Normalization Rules
10.1. Unit Normalization
Quantities SHALL be normalized into SSSR-approved canonical units.
| Input | Output | Rule |
|---|---|---|
kilogram | kg | UCUM canonical abbreviation |
tonne | t | Metric tonne mapping |
litre | L | UCUM liquid volume mapping |
kwh | kWh | Case canonicalization |
kg CO2e | kgCO2e | ZAYAZ canonical emissions unit |
10.2. Country Normalization
Country codes SHALL normalize to ISO 3166-1 alpha-3 unless overridden by a jurisdiction-specific profile.
| Input | Output |
|---|---|
NO | NOR |
Norway | NOR |
DE | DEU |
Germany | DEU |
10.3. Currency Normalization
Currency values SHALL normalize to ISO 4217 uppercase codes.
| Input | Output |
|---|---|
eur | EUR |
€ | EUR |
nok | NOK |
10.4. Date and Timestamp Normalization
Timestamps SHALL normalize to UTC ISO 8601.
| Input | Output |
|---|---|
30/09/2025 | 2025-09-30T00:00:00Z |
2025-09-30 | 2025-09-30T00:00:00Z |
2025-09-30T10:00:00+02:00 | 2025-09-30T08:00:00Z |
11. Produced USO Objects
| USO Object | Description |
|---|---|
NormalizedSignal | Canonical normalized signal object. |
NormalizationEvent | Runtime event describing normalization execution. |
UnitConversionEvent | Evidence of unit conversion where applicable. |
IdentifierNormalizationEvent | Evidence of identifier normalization. |
LineageEvent | USO lineage transition from parsed to normalized signal. |
11.1. USO Lineage Event
{
"uso_id": "01JBF0X0ABCDEF1234567890AB",
"record_id": "01JBF0WNORM000000000000001",
"parent_record_ids": [
"01JBF0W4Y5T2V5W3N5X7A1B2C"
],
"primary_origin_cmi": "vera.TG-PARSE.ENGINE.SIGNAL.1_0_0",
"current_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"origin_chain": [
"vera.TG-PARSE.ENGINE.SIGNAL.1_0_0",
"vera.TG-NORM.ENGINE.NORMALIZER.1_0_0"
],
"origin_chain_codes": [
"TGP01",
"TGN02"
],
"op_type": "NORMALIZE",
"born_at": "2025-10-25T09:40:12Z"
}
12. DAL Integration
The Signal Normalizer Engine SHALL prepare normalized artifacts for DAL anchoring.
DAL anchor candidates include:
- normalized signal hash;
- normalization metadata hash;
- active ruleset references;
- source parsed signal hash;
- output canonical hash;
- engine CMI;
- ZAR code;
- SSSR schema profile.
12.1. DAL Anchor Candidate
{
"artifact_type": "NormalizedSignal",
"artifact_hash": "sha256:aa31f3c9...",
"source_artifact_hash": "sha256:8f91...",
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"zar_code": "TGN02",
"meid": "MEID_SIGNAL_NORMALIZE_NORMALIZER",
"sssr_profile": "siss.SSSR.SCHEMA.TRUSTGATE-INVOICE.1_0_0",
"created_at": "2025-10-25T09:40:12Z"
}
13. Replay Behaviour
The Signal Normalizer Engine SHALL be fully replayable.
Replay SHALL require:
| Replay Input | Required |
|---|---|
| Parsed source signal | Yes |
| Engine CMI | Yes |
| Active SSSR schema profile | Yes |
| Unit dictionary version | Yes |
| Identifier mapping version | Yes |
| Runtime configuration hash | Yes |
Replay succeeds when:
sha256(canonical_json(replayed_normalized_signal))
==
sha256(canonical_json(original_normalized_signal))
13.1. Replay Result
{
"replay_id": "RPL-TG-NORM-2026-0001",
"meid": "MEID_SIGNAL_NORMALIZE_NORMALIZER",
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"source_event_id": "01JBF0W4Y5T2V5W3N5X7A1B2C",
"original_output_hash": "sha256:aa31f3c9...",
"replayed_output_hash": "sha256:aa31f3c9...",
"result": "PASS"
}
14. Federation Behaviour
The engine is federation-aware but does not directly exchange federation messages.
When normalized artifacts are exported through AFLE or EGFS, the engine SHALL preserve:
- original ECO Number;
- original DID where available;
- source hash;
- normalized hash;
- unit conversion evidence;
- schema profile reference;
- normalization ruleset CMI.
Federated consumers SHALL be able to verify that the same parsed signal normalizes into the same canonical representation under the same CMI and ruleset versions.
15. AI Integration
The normalizer does not perform AI scoring.
However, it MAY emit quality signals to DSAIL when normalization uncertainty is detected.
Examples:
- ambiguous unit;
- supplier identifier conflict;
- unrecognized country format;
- weak timestamp inference;
- non-standard currency representation.
15.1. DSAIL Feedback Event
{
"event_type": "trustgate.normalization.feedback",
"eco_number": "ECO-A123",
"meid": "MEID_SIGNAL_NORMALIZE_NORMALIZER",
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"issue_type": "AMBIGUOUS_UNIT",
"field_path": "$.line.quantity.unit",
"input_value": "tons",
"normalized_value": "t",
"confidence": 0.82
}
16. Error Handling
| Failure Mode | Severity | Action |
|---|---|---|
| Unknown unit | High | Emit normalization error and route to review. |
| Ambiguous unit | Medium | Normalize if confidence threshold met; otherwise review. |
| Invalid country code | Medium | Attempt registry lookup; if unresolved, review. |
| Invalid timestamp | High | Route to review. |
| Unsupported schema profile | Critical | Reject signal from downstream processing. |
| Lossy conversion required | High | Block unless policy explicitly permits. |
| Identifier conflict | High | Route to quarantine or manual review. |
16.1. Error Event
{
"event_type": "trustgate.normalization.error",
"event_id": "01JBF0WNERR000000000000001",
"source_event_id": "01JBF0W4Y5T2V5W3N5X7A1B2C",
"eco_number": "ECO-A123",
"error_code": "UNKNOWN_UNIT",
"field_path": "$.line.quantity.unit",
"input_value": "crate",
"severity": "HIGH",
"recommended_action": "manual_review"
}
17. Performance Targets
| Metric | Target |
|---|---|
| Normalization latency p95 | < 30 ms |
| Normalization latency p99 | < 75 ms |
| Throughput per instance | 10,000 signals/sec |
| Replay consistency | 100% |
| Unit conversion determinism | 100% |
| DAL anchor candidate generation | < 10 ms |
| Availability | 99.99% |
18. Security Considerations
The engine SHALL:
- avoid storing raw sensitive payloads unless explicitly configured;
- preserve source hashes for auditability;
- enforce tenant isolation;
- validate incoming parser CMI;
- reject unsigned federation-originated normalized inputs;
- mask configured sensitive fields during diagnostic logging;
- emit structured audit events.
18.1. Sensitive Field Handling
{
"privacy": {
"mask_fields": [
"$.supplier.bank_account",
"$.free_text",
"$.customer_name"
],
"store_original_values": false,
"store_hash_only": true
}
}
19. Runtime Events
19.1. Success Event
{
"event_type": "trustgate.normalization.completed",
"event_id": "01JBF0WNORM000000000000001",
"eco_number": "ECO-A123",
"meid": "MEID_SIGNAL_NORMALIZE_NORMALIZER",
"engine_cmi": "vera.TG-NORM.ENGINE.NORMALIZER.1_0_0",
"source_event_id": "01JBF0W4Y5T2V5W3N5X7A1B2C",
"output_hash": "sha256:aa31f3c9...",
"unit_consistency": 1.0,
"duration_ms": 18,
"status": "SUCCESS"
}
19.2. Warning Event
{
"event_type": "trustgate.normalization.warning",
"event_id": "01JBF0WNWARN000000000001",
"eco_number": "ECO-A123",
"warning_code": "LOW_UNIT_CONFIDENCE",
"field_path": "$.line.quantity.unit",
"input_value": "tons",
"normalized_value": "t",
"confidence": 0.82
}
20. Developer Notes
The Signal Normalizer Engine is a foundational dependency for downstream TrustGate engines.
Developers SHALL ensure that:
- all normalization rules are versioned;
- all rule references are included in replay metadata;
- all transformations are deterministic;
- original values are preserved where policy requires auditability;
- normalized outputs are canonicalized before hashing;
- new unit mappings are introduced through SSSR governance;
- schema upgrades are explicit and recorded through ZAR.
The engine should remain narrow in scope. It should normalize representation, not assess trust. Scoring and policy evaluation occur later in the TrustGate pipeline.