RWAE
Resource Aggregation Engine
0. Identity
<Identity meid="MEID_UOM_001" />
Depends on module:
1. Purpose
The Resource Aggregation Engine is the foundational UOM Micro Engine responsible for aggregating accepted Resource Point measurements across the Universal Organizational Model graph. It answers questions such as:
How much electricity did this facility use?
How much water did all German sites consume?
What is total heating consumption for this legal entity?
What is total waste for this building during Q1?
The engine aggregates accepted values from canonical Resource Points rather than raw observations.
This means it consumes:
core_data.accepted_resource_measurements
not:
core_data.resource_observations
Raw observations are evidence. Accepted measurements are calculation-ready values.
Classification
Type: MICE Domain: UOM Engine ID: MEID_UOM_001 Primary Function: Resource aggregation Execution Mode: Stateless first, run logging optional later
2. Strategic Role
The Resource Aggregation Engine is the first foundational Micro Engine for the UOM and Resource Intelligence Layer.
It is required by:
MEID_UOM_002 Intensity Calculation Engine
MEID_UOM_004 Resource Coverage Engine
MEID_UOM_005 Measurement Completeness Engine
MEID_ESG_001 Scope Attribution Engine
MEID_ESG_003 Facility Benchmark Engine
Graph-Aware ESG Intelligence Layer
ZARA AI Facility Assistant
Reports Hub
The engine provides the trusted aggregate value that downstream engines normalize, compare, benchmark, attribute, or explain.
3. Core Concept
The engine starts from a selected UOM entity and traverses the UOM graph to identify relevant Resource Points.
Example:
Denver Office Facility
↓
Building A
↓
Resource Point: Main Electricity Feed
↓
Accepted Measurements
↓
Aggregate kWh
The engine does not directly inspect invoices, meters, sensors, or IoT feeds. Those are already reconciled upstream into accepted measurements.
4. Primary Use Cases
Facility Resource Aggregation
Input:
Facility = Denver Office
Resource Type = ELECTRICITY
Period = 2026-01-01 to 2026-12-31
Output:
Denver Office electricity = 1,240,000 kWh
Legal Entity Aggregation
Input:
Legal Entity = Viroway Ltd Norway
Resource Type = WATER
Period = 2026
Output:
Total water consumption = 18,450 m³
Country-Level Aggregation
Input:
Country = Germany
Resource Type = ELECTRICITY
Period = Q1 2026
Output:
German facilities electricity = 4,880,000 kWh
Building-Level Aggregation
Input:
Building = Paris Building A
Resource Type = HEAT
Period = March 2026
Output:
District heating = 92,000 kWh
5. Required Tables
Entity Graph
core_metadata.entity_registry
core_relations.entity_relationships
Resource Point Layer
core_metadata.resource_point_registry
core_relations.resource_point_relationships
Accepted Measurement Layer
core_data.accepted_resource_measurements
Additional Supporting Tables
core_metadata.facility_details
core_metadata.building_details
core_metadata.address_registry
core_metadata.lease_details
core_signals.resource_point_signal_map
These are not required for basic aggregation, but they enrich filtering and ESG context.
Input Contract
Minimal Request
{
"client_id": "uuid",
"entity_id": "uuid",
"resource_type": "ELECTRICITY",
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-12-31T23:59:59Z"
}
Extended Request
{
"client_id": "uuid",
"entity_id": "uuid",
"resource_type": "ELECTRICITY",
"resource_subtype": null,
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-12-31T23:59:59Z",
"unit": "kWh",
"include_child_entities": true,
"relationship_types": [
"MEASURES",
"SERVES",
"ALLOCATED_TO"
],
"reporting_boundary_status": "included",
"aggregation_method": "sum",
"include_estimates": true,
"include_unapproved": false
}
Output Contract
{
"client_id": "uuid",
"entity_id": "uuid",
"resource_type": "ELECTRICITY",
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-12-31T23:59:59Z",
"aggregated_value": 1240000,
"unit": "kWh",
"resource_point_count": 4,
"measurement_count": 48,
"confidence_score": 0.96,
"trust_score": 0.94,
"aggregation_method": "sum",
"included_resource_points": [
{
"resource_point_id": "uuid",
"resource_point_name": "Denver Building A Main Electricity Feed",
"value": 620000,
"unit": "kWh"
}
],
"warnings": [],
"evidence": {
"source_table": "core_data.accepted_resource_measurements",
"calculation_engine": "MEID_UOM_001",
"calculation_version": "0.1.0"
}
}
6. Aggregation Logic
Step 1 - Resolve Entity
The engine validates that the requested entity_id belongs to the supplied client_id.
SELECT *
FROM core_metadata.entity_registry
WHERE entity_id = :entity_id
AND client_id = :client_id
AND deleted_at IS NULL;
Step 2 - Resolve Resource Points
The engine finds Resource Points connected directly or indirectly to the requested entity.
Primary lookup:
core_relations.resource_point_relationships
Example relationship types:
MEASURES
SERVES
ALLOCATED_TO
USED_BY
ASSOCIATED_WITH
If include_child_entities = true, the engine may traverse:
core_relations.entity_relationships
to include child facilities, buildings, floors, rooms, departments, or assets.
Step 3 - Filter by Resource Type
The engine filters Resource Points by:
resource_type
resource_subtype
status
reporting_boundary_status
from:
core_metadata.resource_point_registry
Step 4 - Fetch Accepted Measurements
The engine fetches accepted measurements for the matching Resource Points and period.
SELECT *
FROM core_data.accepted_resource_measurements
WHERE client_id = :client_id
AND resource_point_id = ANY(:resource_point_ids)
AND period_start >= :period_start
AND period_end <= :period_end
AND deleted_at IS NULL;
By default, it should exclude:
approval_status = rejected
reporting_status = excluded_from_report
reporting_status = superseded
Step 5 - Apply Allocation
If a Resource Point is shared across entities, the engine applies allocation logic from:
core_relations.resource_point_relationships
Supported allocation methods:
DIRECT
FLOOR_AREA
FTE
HEADCOUNT
REVENUE
PRODUCTION_VOLUME
ENERGY_USE
WATER_USE
OPERATING_HOURS
MACHINE_HOURS
METERED_SUBALLOCATION
MANUAL_PERCENT
CUSTOM
For v0.1.0, supported allocation methods should be:
DIRECT
MANUAL_PERCENT
Other allocation methods should return a warning unless implemented.
Step 6 - Request Unit Normalization
If source units differ from the requested output unit, MICE-UOM-001 calls MEID_CORE_NORM. Resource Aggregation Engine must not implement its own unit conversion logic except temporary validation guards.
Step 7 - Aggregate
Default aggregation method:
sum
Other supported methods may include:
average
max
min
weighted_average
last_value
The default for resource consumption is always:
sum
Step 8 - Return Evidence
The response must include enough evidence to explain:
which Resource Points were included
which accepted measurements were used
which allocation logic was applied
which unit conversions were performed
which warnings occurred
7. Trust Logic
The engine should compute aggregate confidence based on:
accepted_resource_measurements.confidence_score
accepted_resource_measurements.trust_score
resource_point_relationships.source_confidence_score
resource_point_registry.source_confidence_score
Recommended v0.1.0 logic:
aggregate_confidence_score = weighted average of measurement confidence scores by accepted_value
aggregate_trust_score = weighted average of measurement trust scores by accepted_value
If confidence or trust is missing:
return null
or use a conservative default only if configured
8. Warning Conditions
The engine should return warnings for:
No Resource Points found
No accepted measurements found
Mixed units without conversion
Unsupported allocation method
Partially included reporting boundary
Estimated values included
Unapproved values included
Measurement period gaps
Low confidence scores
Resource Points with inactive status
Example:
{
"warning_code": "MIXED_UNITS",
"message": "Measurements include both kWh and MWh. Values were converted to kWh.",
"severity": "info"
}
9. Example Query
Question
How much electricity did the Denver office use in 2026?
ZARA Resolution
Denver office → entity_id
electricity → resource_type = ELECTRICITY
2026 → period_start / period_end
Engine Request
{
"client_id": "uuid",
"entity_id": "uuid",
"resource_type": "ELECTRICITY",
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-12-31T23:59:59Z",
"unit": "kWh",
"include_child_entities": true
}
Engine Output
{
"aggregated_value": 1240000,
"unit": "kWh",
"resource_point_count": 3,
"measurement_count": 36,
"confidence_score": 0.96,
"trust_score": 0.94
}
ZARA Response
The Denver office used 1,240,000 kWh of electricity in 2026 across 3 Resource Points. The aggregated trust score is 94%.
10. API Design
Recommended endpoint:
POST /api/mice/uom/resource-aggregation
Request:
{
"client_id": "uuid",
"entity_id": "uuid",
"resource_type": "ELECTRICITY",
"period_start": "2026-01-01T00:00:00Z",
"period_end": "2026-12-31T23:59:59Z",
"unit": "kWh",
"include_child_entities": true
}
Response:
{
"engine_id": "MEID_UOM_001",
"engine_version": "0.1.0",
"status": "success",
"result": {
"aggregated_value": 1240000,
"unit": "kWh",
"confidence_score": 0.96,
"trust_score": 0.94
}
}
11. Stateless First Design
The engine should initially be implemented as a stateless query/API engine.
This avoids premature persistence and keeps implementation simple.
Recommended v0.1.0:
No persistent run table required
Return calculation result directly
Log invocation through ALTD / telemetry
Optional future tables:
core_engine.resource_aggregation_runs
core_engine.resource_aggregation_results
These should only be added when the engine supports scheduled batch aggregation, caching, or report snapshot locking.
12. Governance Requirements
Every invocation must be traceable.
Minimum log fields:
engine_id
engine_version
client_id
requested_by
entity_id
resource_type
period_start
period_end
resource_points_used
accepted_measurements_used
warnings
confidence_score
trust_score
created_at
Critical outputs used in formal reports should be linked to:
ALTD
DaVE
DICE
VTE
Reports Hub
13. Non-Goals
The Resource Aggregation Engine does not:
read raw invoices
perform OCR
select accepted values
resolve duplicate sources
perform emissions calculations
perform intensity calculations
perform benchmarking
determine reporting boundaries
generate narrative explanations
Those responsibilities belong to other engines or layers.
14. Relationship to Other Engines
Upstream
Resource Reconciliation Engine
Accepted Measurement Selection Logic
DaVE / DICE validation
Downstream
Intensity Calculation Engine
Scope Attribution Engine
Facility Benchmark Engine
Graph-Aware ESG Intelligence Layer
ZARA
Reports Hub
15. v0.1.0 Implementation Scope
The first version should support:
Entity-level aggregation
Direct Resource Point relationships
Child entity traversal
Resource type filtering
Accepted measurements only
SUM aggregation
DIRECT allocation
MANUAL_PERCENT allocation
Basic unit validation
Evidence payload
Warnings
Confidence/trust rollup
Not required in v0.1.0:
Advanced graph traversal optimization
Complex allocation methods
Cached aggregation snapshots
Batch scheduling
Multi-currency or financial normalization
Production-volume allocation
Weather normalization
Benchmarking
Summary
The Resource Aggregation Engine is the first executable intelligence layer above the Universal Organizational Model.
It transforms accepted Resource Point measurements into entity-level resource totals.
It is the foundational dependency for facility analytics, intensity metrics, ESG benchmarking, Scope attribution, reporting, and ZARA natural-language ESG intelligence.