Core Principles

The Sourceful energy system is built on fundamental principles that ensure data integrity, energy conservation, and system reliability. These principles are foundational and constitutional - they govern all modeling and accounting operations within the Sourceful ecosystem.

Foundational Principles

1. Energy is Primary

All modeling and accounting start with energy. Power is always derived as dE/dt. This hierarchy is never reversed.

2. The Site Boundary

Every calculation is framed relative to a clearly defined Site.

The Site is the thermodynamic control volume and, by default, the Point of Common Coupling (PCC) at the utility revenue/grid interconnection meter. All imports, exports, on-site generation, and storage are measured relative to this point.

If there are multiple service entrances, a single designated virtual Site must be declared, and all contributing meters explicitly mapped to it.

3. Canonical Sign Convention

• Positive = flow into the Site
• Negative = flow out of the Site

This rule applies universally across telemetry, metrics, and storage. Counters are always positive and monotonic, but are split into import and export streams.

4. Units and Base System

Internal representation uses only base SI units:

Unit conversions are performed only at ingestion or egress boundaries.

5. Determinism

Physics must be conserved in every layer. The signed sum of all power (or interval energies) at the Site must balance within epsilon. Any violation is a fault, not "just noise."

6. The Source of Time

Time is stamped at the first Sourceful-controlled collection point. This is the temporal authority for all measurements.

Gateway Time Requirements:

• All Sourceful gateways must maintain NTP synchronization
• Maximum acceptable drift: +/-100ms between any two gateways at a Site
• Timestamps applied as Unix epoch milliseconds in UTC
• Gateway health includes NTP sync status and last sync time

Example: An inverter reports 5247W but has a clock that's 3 hours off. Zap polls this inverter at 2024-01-15T14:30:00.000Z. The recorded measurement is:

{
  "power_W": 5247,
  "timestamp": 1705330200000,
  "gateway": "zap-0342",
  "source": "inverter-01"
}

7. Simplicity & Extensibility

The Core changes rarely and only with consensus. All extensions must conform to this document. The purpose of the Core is to set boundaries and invariants, not to prescribe implementation detail.

Conservation Example

Energy Balance at the PCC

The Point of Common Coupling (PCC) - the utility grid meter - is the gate of the Site. All energy must pass through this gate:

dE(PCC) = LOAD + PV + BATT + EV + ...

Every term is always added with a plus sign. The sign of the value encodes direction:

• Positive (+): energy flowing into the Site (import, consumption, charging)
• Negative (-): energy flowing out of the Site (export, generation, discharging)

Examples:

The math is always a sum. Engineers don't need to remember which channels are "subtracted" - the rule is universal: direction is in the sign.

This formulation is not arbitrary; it is energy conservation applied at the Site boundary. Any mismatch beyond tolerance means something is broken - a meter error, telemetry bug, or mis-signed flow. This is how physics itself becomes a validator for the system.