DEV Community: Jeremiah Say

The "Audit Trail" Pattern: Architecture for Immutable Sustainability Data

Jeremiah Say — Fri, 29 May 2026 03:06:36 +0000

In standard CRUD apps, if a user updates their profile name, you overwrite the database row. No big deal. But in CSRD (Corporate Sustainability Reporting Directive) software, overwriting a row is a compliance nightmare.

If an auditor asks, "Why did your Scope 1 emissions for 2024 change between July and October?" and your answer is "A dev ran a migration that updated the emission factors," you've just failed the audit.

To build a compliant carbon engine, you have to move away from "Current State" databases and toward Immutable Data Architectures. This is the pattern I use at GreenCalculus.com to ensure that once a report is "frozen," the data stays frozen—even if the underlying code or emission factors change.

The Problem: The "Floating" Emission Factor

Most carbon calculations look like this in the backend:

$$E = A \times EF$$

Where $E$ is emissions ($tCO_2e$), $A$ is activity data (e.g., liters of diesel), and $EF$ is the Emission Factor.

The mistake is storing only $A$ and looking up $EF$ at runtime. Emission factor sets (like DEFRA or IEA) are updated annually. If you update your factors table to the 2026 set, your 2024 calculations will suddenly change because the runtime lookup finds a new value. This is called Data Drift, and it's an auditor's biggest red flag.

The Solution: The Snapshot Pattern

Instead of linking to a factor, you must persist the snapshot of the calculation at the moment it occurred. You don't just store the result; you store the "receipt" of the math.

The JSON Data Structure

{
  "activity_id": "fuel_log_789",
  "calculated_at": "2026-05-29T10:00:00Z",
  "inputs": {
    "value": 500,
    "unit": "liters"
  },
  "snapshot": {
    "factor_used": 2.6765,
    "factor_source": "DEFRA_2025",
    "gwp_basis": "AR6",
    "formula_version": "v2.1.0"
  },
  "output_tco2e": 1.33825,
  "checksum": "a1b2c3d4..." 
}

Implementation: The Three-Tier Storage Strategy

To achieve this in a standard PHP/JavaScript stack, you need to separate your raw data from your calculated disclosures.

1. The Activity Ledger (Source of Truth)

The ledger stores the raw evidence (e.g., "Invoice #123: 500L Diesel"). Once an entry is verified, it becomes Append-Only. Any corrections are handled via "reversal entries" (credit/debit style), exactly like a financial ledger.

2. The Factor Registry (The Library)

Never delete or UPDATE an old emission factor. Your database schema should treat factors as immutable versions:

CREATE TABLE emission_factors (
    id UUID PRIMARY KEY,
    label TEXT, -- e.g. "Diesel (Average Biofuel Blend)"
    value DECIMAL,
    year INTEGER,
    version_start TIMESTAMP,
    version_end TIMESTAMP -- Null if current
);

3. The Calculation Archive (The Receipt)

This table stores every "point-in-time" result. When an auditor asks for the numbers, you query this table, not a live calculation function.

The Code: A PHP/Laravel Implementation

When a calculation is triggered, we don't just return a number; we return a CalculationReceipt object that contains the entire context, including a hash of the code version used.

class CarbonCalculator {
    public function calculate(Activity $activity): CalculationReceipt {
        // Find the factor that was active at the time the fuel was consumed
        $factor = $this->registry->getFactorFor($activity->type, $activity->consumed_at);

        $total = $activity->value * $factor->value;

        // We store the literal values used, NOT just a foreign key
        return CalculationReceipt::create([
            'activity_id'   => $activity->id,
            'tco2e'         => $total,
            'meta_snapshot' => [
                'factor_name'  => $factor->label,
                'factor_value' => $factor->value,
                'gwp_basis'    => 'AR6',
                'logic_hash'   => hash_file('md5', __FILE__), // Proves which code version ran this
            ],
            'is_frozen' => true
        ]);
    }
}

Audit-Proofing the Frontend

When a user views their "2025 Inventory," the frontend should never trigger a fresh calculation. It should fetch the stored receipts.

However, if a methodology changes (e.g., the EU updates the ESRS E1 guidance), you can run a "What-If" check. If the system detects that a factor has been updated since the receipt was generated, you display a Discrepancy Warning:

⚠️ Methodology Change: A newer emission factor (DEFRA 2026) is available. Your current report uses DEFRA 2025. [Recalculate and Re-verify?]

This puts the power in the hands of the sustainability officer to decide when to "re-state" their figures—a formal requirement in CSRD reporting.

What this architecture prevents

Silent Drifts: You avoid the "Why is our total different than it was yesterday?" slack message.
Audit Failure: You can produce a "lineage report" for every single gram of $CO_2$ in the system.
Regression Bugs: A bug introduced in a new feature won't accidentally corrupt historical data because historical data is physically separated from the calculation engine.

The Golden Rule for CSRD Devs: In carbon accounting, an "edited" record is a liability. Build for the trail, not just the total.

I'm building the data integrity layer for GreenCalculus.com. If you're working on CSRD or ESRS compliance, let's swap notes in the comments.

Floating-point will quietly corrupt your emissions math, and 0.1 + 0.2 already warned you

Jeremiah Say — Sat, 23 May 2026 00:04:20 +0000

Every developer has seen this:

0.1 + 0.2
// 0.30000000000000004

It's the most-shared bug in programming. You learn it, you nod, you move on — because in most code the error is so far down the decimal that nothing notices. A pixel is off by a billionth. A timer fires a nanosecond late. Nobody files a ticket.

Then you build a system whose entire job is to add thousands of numbers together and produce a total that has to match a figure someone calculated by hand. And the rounding error you waved away in the tutorial becomes a line in an audit report that says: the system total does not reconcile to the source data.

That's where I met this bug for real, building the calculation layer at GreenCalculus.com. It runs over a thousand emissions calculators, and every one of them has the same hard requirement: the number the engine produces must reconcile, to the last reported digit, against the number a practitioner gets when they check the math themselves. "Close enough" is a finding. This post is the set of rules that get you from the math looks right to the math reconciles.

Why this bites harder in measurement code than anywhere else

Most software treats numbers as means to an end — coordinates, counters, ratios feeding a render. The exact value rarely is the deliverable.

In emissions accounting, the number is the deliverable. A reported figure of 1,240.37 tCO2e is the product. If an auditor recomputes it and gets 1,240.41, the 0.04 isn't noise — it's an unexplained discrepancy, and unexplained discrepancies are exactly what an audit exists to surface. You don't get to say "floating-point." You get to fix your data model.

Three properties of this domain turn a harmless rounding error into a real defect:

Massive summation. A Scope 3 inventory adds tens of thousands of line items. Error accumulates with count.
Wide dynamic range. You add a 4,000,000 kg figure to a 0.002 kg figure in the same total. This is precisely the case floating-point handles worst.
External reconciliation. The output is checked against an independent calculation. There's no hiding internal drift, because someone outside your system recomputes it.

The float problem, stated precisely

A 64-bit IEEE 754 float (double, JavaScript's only number type) stores 52 bits of mantissa — about 15–17 significant decimal digits. 0.1, 0.2, and 0.3 are not representable exactly in binary, the same way 1/3 isn't representable exactly in decimal. They're stored as the nearest available binary fraction, and the tiny errors survive arithmetic.

(0.1 + 0.2).toFixed(20)
// "0.30000000000000004441"

For a single operation the error is ~10⁻¹⁷. The problem is what happens when you do the operation 50,000 times, and when the operands differ in magnitude by a factor of a billion.

Failure mode 1: the total that won't reconcile

Naive summation of a long list of factors:

function totalEmissions(lineItems) {
  let total = 0;
  for (const item of lineItems) {
    total += item.activity * item.factor;   // each term carries float error
  }
  return total;
}

Each activity * item.factor lands on the nearest representable double, slightly off. Each += rounds again. Over tens of thousands of items the errors are mostly random and partly cancel — but "mostly" is not "exactly," and the residual is deterministic for a given input order. Run the same data through a spreadsheet that sums in a different order and you get a different last digit. Now you have two "correct" totals that disagree, and no way to say which is right.

Fix: control precision at the boundary, not in the loop

Two defensible strategies, depending on stack.

Decimal arithmetic for the money-and-mass path. Store and sum factors as arbitrary-precision decimals so there's no binary-representation error at all:

import Decimal from 'decimal.js';

function totalEmissions(lineItems) {
  return lineItems
    .reduce((acc, item) =>
      acc.plus(new Decimal(item.activity).times(item.factor)),
      new Decimal(0))
    .toNumber();   // convert once, at the very end, after rounding regime applied
}

Decimal is slower. You don't need it everywhere — you need it on the path whose output is a reported figure.

Kahan summation when you must stay in floats. If the hot path can't afford Decimal, compensated summation recovers most of the lost low-order bits by tracking the rounding error and feeding it back in:

function kahanSum(values) {
  let sum = 0;
  let compensation = 0;        // running error term
  for (const v of values) {
    const y = v - compensation;
    const t = sum + y;
    compensation = (t - sum) - y;   // recovers what the addition just dropped
    sum = t;
  }
  return sum;
}

The single addition sum + y loses the low bits of y when sum is large; the next line reconstructs exactly those bits and carries them into the following iteration. For a long sum of mixed-magnitude terms this is the difference between a stable total and one that drifts with input order.

Failure mode 2: the wide-magnitude swallow

This is the one that produces a wrong number, not just an unstable one.

let total = 4_000_000.0;   // a large facility's annual figure, kg
total += 0.002;            // a trace fugitive line, kg
total === 4_000_000.002;   // true here — but stack enough trace lines...

When the accumulator is large and the addend is tiny, the addend's significant bits fall off the bottom of the mantissa and are silently dropped. One trace line is fine. Ten thousand of them, each individually swallowed, is a missing category total. The sum looks authoritative — it's a clean large number — which is exactly why nobody catches it by eye.

Fix: sum within magnitude bands, then combine

Add small things to small things before adding them to big things. Sort ascending and the smallest terms accumulate among themselves into a magnitude the large accumulator can actually absorb:

function bandedSum(values) {
  const ascending = [...values].sort((a, b) => a - b);
  return kahanSum(ascending);   // small-first ordering + compensation
}

Sorting ascending before a compensated sum is a cheap, robust default for "many small, few large." It won't matter on uniform data — but reference-data sums are rarely uniform.

Failure mode 3: the ratio that amplifies

Intensity metrics divide one computed figure by another — emissions per unit revenue, per tonne of product, per kWh. Division doesn't create error, but it amplifies whatever error the operands already carry, and ratios of two nearly-equal slightly-wrong numbers are the worst case.

const intensityA = total2025 / output2025;
const intensityB = total2024 / output2024;
const yoyChange = (intensityA - intensityB) / intensityB;   // tiny - tiny, over tiny

When intensityA and intensityB are close, their difference is dominated by the rounding error in each, and dividing that noisy difference by a small base inflates it into a visible percentage. Your year-on-year intensity change can read as ±0.3% pure artefact.

Fix: defer rounding, widen the working precision

Carry full precision through the entire chain and round once, at presentation. Never round an intermediate that feeds a later division. If the figures are reconciliation-critical, do the division in Decimal too — the cost is trivial relative to one division per report.

Failure mode 4: the unit-boundary shave

Every conversion is a multiply, and every multiply is a place to lose digits. The g → kg → t chain looks innocent:

const grams = 1234567;
const kg = grams / 1000;        // 1234.567
const tonnes = kg / 1000;       // 1.234567
// round-trip back up and compare:
tonnes * 1000 * 1000 === grams; // not guaranteed

Each division lands on the nearest double; chaining them compounds the drift, and a value that round-trips through three units may not come back to where it started. The fix is the same architectural rule that governs the whole post: store in one canonical unit at full precision, convert only at the display boundary. Don't persist the converted value and re-derive from it — persist the canonical value and convert on read.

The rule underneath all four

Every one of these is the same decision made wrong: where does precision get fixed, and how many times. The failures all come from rounding early, rounding repeatedly, or rounding in the middle of a chain that isn't done yet.

The architecture that prevents all four:

One canonical unit, full precision, in storage. No pre-rounded, pre-converted values persisted.
A declared rounding regime, applied once, at the boundary. Half-up, half-even — pick one, document it, apply it where the number leaves the system, never before.
Decimal on any path whose output is a reported figure. Floats are fine for charts and progress bars. They are not fine for the deliverable.
Compensated, magnitude-aware summation wherever you must aggregate many terms in floating point.

This is the same shape as a rule we apply to every figure in the GreenCalculus data layer: a number is meaningless without its declared basis. There, the basis is the GWP version and the emission-factor source. Here, it's the unit and the rounding regime. In both cases the discipline is identical — the number is not just its digits; it's its digits plus the declared rules that produced them. Store the rules with the number, or you can't defend the number.

0.1 + 0.2 was never the bug. It was the warning that your numbers carry rules you haven't written down yet.

The GreenCalculus calculation layer applies these rules across 1,000+ emissions calculators, every one of which has to reconcile against its source data to the last reported digit. Methodology documentation at greencalculus.com.

CSRD/ESRS E1 disclosure requirements, translated into data fields — a developer's map

Jeremiah Say — Mon, 11 May 2026 04:56:14 +0000

ESRS E1 is the climate standard inside the EU's Corporate Sustainability Reporting Directive. It tells companies what to disclose. It does not tell developers what data to collect, what units to store, or how to structure the fields that feed those disclosures.

That translation gap is where most carbon software goes wrong. The sustainability team thinks they're collecting what the standard requires. The developer builds fields that seem right. Nobody maps one to the other explicitly. By the time the first CSRD report needs to be filed, the data model is missing half of what E1 demands and contains a lot that it doesn't need.

This is the map I built when designing the data layer at GreenCalculus.com. It covers every material E1 datapoint and the field structure behind each one.

What ESRS E1 actually requires

ESRS E1 is organised into disclosure requirements (DRs). For GHG emissions, the core ones are:

E1-6: Gross Scope 1, 2 and 3 GHG emissions
E1-7: GHG removals and carbon credits
E1-5: Energy consumption and mix
E1-4: Targets related to climate change mitigation
E1-3: Actions and resources for climate transition
E1-1: Transition plan for climate change mitigation (Phase 1 companies)

Each DR maps to specific datapoints. Each datapoint maps to specific fields. Here is that mapping, section by section.

E1-6: GHG emissions — the core inventory

This is the largest DR. Everything here feeds a GHG inventory that must comply with GHG Protocol Corporate Standard or an equivalent methodology.

Scope 1 — direct emissions

{
  scope1: {
    gross_tco2e: number,         // Total Scope 1, tCO2e, GWP basis declared separately
    gwp_basis: "AR5" | "AR6",    // Must be disclosed. AR5 = IPCC Fifth Assessment Report
    includes_biogenic: false,    // Biogenic CO2 reported out of scope, never in gross total
    biogenic_co2_tco2e: number,  // Reported separately, labelled as out-of-scope
    breakdown: {
      stationary_combustion: number,   // Boilers, generators, furnaces
      mobile_combustion: number,       // Company-owned fleet
      process_emissions: number,       // Chemical/industrial reactions (e.g. BF-BOF steel)
      fugitive_emissions: number,      // Refrigerant leaks, methane from coal/oil/gas
    },
    methodology: string,         // "GHG Protocol Corporate Standard" or equivalent
  }
}

Two fields here that developers routinely miss:

biogenic_co2_tco2e — Biogenic CO₂ from biomass combustion (wood pellets, biogas, etc.) is explicitly excluded from the gross Scope 1 total under GHG Protocol and ESRS E1. It must be reported as a separate line item labelled "out of scope." If your data model rolls it into gross_tco2e, the disclosure is wrong. Every bioenergy fuel entry in our Master Brain carries a separate biogenic_co2 key for exactly this reason.

process_emissions — Steel companies using blast furnace–basic oxygen furnace (BF-BOF) steelmaking classify coking coal use as a process emission, not stationary combustion. ESRS E1-6 requires this disaggregation. A flat scope1_total field without the breakdown loses this.

Scope 2 — purchased electricity, steam, heat, cooling

{
  scope2: {
    location_based_tco2e: number,   // Average grid intensity × consumption
    market_based_tco2e: number,     // Supplier-specific / EAC / REGO factor
    gwp_basis: "AR5" | "AR6",
    grid_factor_source: string,     // "IEA_2026" | "DEFRA_2025" | "EPA_2024"
    grid_factor_country: string,    // ISO 3166-1 alpha-2, e.g. "DE"
    eac_coverage_percent: number,   // % of consumption covered by energy attribute certificates
    residual_mix_factor: number,    // kg CO2e/kWh — used for uncovered market-based portion
  }
}

GHG Protocol Scope 2 Guidance requires both location-based and market-based figures wherever data is available. ESRS E1-6 inherits this. A single scope2_total field is not enough — you need both methods stored separately so the report can disclose both.

eac_coverage_percent matters for the market-based figure. If a company has REGOs covering 40% of its UK electricity, the market-based calculation applies the REGO factor to 40% and the residual mix factor to the remaining 60%. If your model only stores a single factor, this is impossible to reconstruct for audit.

Scope 3 — value chain emissions

ESRS E1-6 requires Scope 3 disclosure across all 15 GHG Protocol categories. Twelve of those 15 are mandatory under CSRD (the three optional ones are upstream/downstream leased assets and franchises, which are required only where material):

{
  scope3: {
    total_tco2e: number,
    gwp_basis: "AR5" | "AR6",
    categories: {
      cat1_purchased_goods_services:          { tco2e: number, method: "spend" | "activity" | "hybrid", required_csrd: true },
      cat2_capital_goods:                     { tco2e: number, method: string, required_csrd: true },
      cat3_fuel_energy_activities:            { tco2e: number, method: string, required_csrd: true },
      cat4_upstream_transport:                { tco2e: number, method: string, required_csrd: true },
      cat5_waste_operations:                  { tco2e: number, method: string, required_csrd: true },
      cat6_business_travel:                   { tco2e: number, method: string, required_csrd: true },
      cat7_employee_commuting:                { tco2e: number, method: string, required_csrd: true },
      cat8_upstream_leased_assets:            { tco2e: number, method: string, required_csrd: false },
      cat9_downstream_transport:              { tco2e: number, method: string, required_csrd: false },
      cat10_processing_sold_products:         { tco2e: number, method: string, required_csrd: false },
      cat11_use_of_sold_products:             { tco2e: number, method: string, required_csrd: true },
      cat12_end_of_life_sold_products:        { tco2e: number, method: string, required_csrd: true },
      cat13_downstream_leased_assets:         { tco2e: number, method: string, required_csrd: false },
      cat14_franchises:                       { tco2e: number, method: string, required_csrd: false },
      cat15_investments:                      { tco2e: number, method: string, required_csrd: false },
    },
    omitted_categories: [
      {
        category: "cat8_upstream_leased_assets",
        reason: "Not material — no upstream leased assets in reporting boundary",
      }
    ],
  }
}

The omitted_categories array is not optional housekeeping — ESRS E1-6 requires companies to explicitly justify any omitted category. If you omit Cat 8 without a documented reason, the auditor will flag it. Build the justification field into the model from day one.

The method field on each category matters for methodology transparency. Spend-based (DEFRA economic factors) and activity-based (physical quantities × emission factors) produce materially different figures for the same category and must be disclosed.

E1-7: GHG removals and carbon credits

This DR is where most platforms are completely empty. ESRS E1-7 requires separate disclosure of:

{
  removals: {
    total_tco2e_removed: number,    // Must not be netted against gross emissions in E1-6
    breakdown: {
      forestry_afforestation: number,
      forestry_reforestation: number,
      soil_sequestration: number,
      blue_carbon: number,
      direct_air_capture: number,
      bioenergy_ccs: number,
    },
    permanence_risk_note: string,   // Required for biological removal pathways
  },
  carbon_credits: {
    total_credits_used: number,     // tCO2e
    standard: string,               // "Gold Standard" | "VCS" | "Article 6.4" | etc.
    vintage_year: number,
    project_ids: string[],
    used_for: "net_zero_claim" | "carbon_neutral_claim" | "offsetting_only",
    credits_excluded_from_scope_targets: boolean,  // SBTi: credits cannot count toward scope targets
  }
}

The critical rule: removals must never be netted against gross emissions in E1-6. The gross figures in E1-6 are gross. Removals are disclosed separately in E1-7. If your data model subtracts removals to produce a "net" figure and feeds that into the E1-6 fields, the disclosure is non-compliant.

Carbon credits are similarly ring-fenced. Under SBTi and increasingly under ESRS E1, offsets cannot be counted against scope-based emission reduction targets. The credits_excluded_from_scope_targets boolean forces this distinction to be explicit in the data model rather than handled ad hoc at report generation time.

E1-5: Energy consumption and mix

{
  energy: {
    total_consumption_mwh: number,
    breakdown: {
      fossil_fuel_mwh: number,
      nuclear_mwh: number,
      renewable_self_generated_mwh: number,
      renewable_purchased_mwh: number,
      renewable_eac_covered_mwh: number,
    },
    renewable_share_percent: number,   // Calculated field: renewable / total × 100
    energy_intensity: {
      value: number,                   // tCO2e per unit of activity
      denominator_unit: string,        // "MWh" | "EUR_revenue" | "tonne_product" | etc.
      denominator_value: number,
    },
  }
}

energy_intensity is required by E1-5 and is the metric most companies get wrong at the data model level. The denominator must be declared — intensity against revenue means something different from intensity against tonnes of product. Both are valid but they are not interchangeable, and the standard requires disclosure of which one you used.

E1-4: Climate targets

{
  targets: [
    {
      id: string,                       // Internal reference
      scope_coverage: ("scope1" | "scope2" | "scope3")[],
      target_type: "absolute" | "intensity",
      baseline_year: number,
      baseline_tco2e: number,
      target_year: number,
      target_reduction_percent: number,
      aligned_framework: "SBTi" | "Paris_1.5C" | "Paris_2C" | "net_zero" | "custom",
      validated_by: string | null,      // "SBTi" if externally validated
      interim_milestones: [
        { year: number, reduction_percent: number }
      ],
      offsets_included_in_target: false,  // Must be false for SBTi-aligned targets
    }
  ]
}

The offsets_included_in_target field is the one that will trip up companies using offsets to meet science-based targets. SBTi is explicit: offsets cannot be used to meet Scope 1, 2, or 3 reduction targets. If this field is missing from your model, there is no machine-readable way to verify compliance at report time.

The GWP basis problem

Every GHG emission figure in ESRS E1 must be accompanied by a declared GWP basis. AR5 and AR6 produce different CO₂e values for the same gas — CH₄ is 28 (AR5) vs 29.8 (AR6) for biogenic methane, and 30 vs 27.9 for fossil methane.

The correct field structure is not a single tco2e number. It is:

{
  gross_tco2e_ar5: number,   // For regulatory reporting (most frameworks still use AR5)
  gross_tco2e_ar6: number,   // For comparability with AR6-based targets
  gwp_basis_primary: "AR5",  // Which basis the disclosed figure uses
}

Storing both values costs two fields. Not storing both means a methodology change from AR5 to AR6 (which is coming as ESRS matures) requires recalculating every historical figure from scratch rather than reading the already-stored alternate value.

The field map as a WordPress custom post meta schema

If you're building this in WordPress, the CSRD inventory post type meta fields map cleanly to the structure above. Here's a minimal registration:

function gc_register_csrd_inventory_meta(): void {

    $fields = [
        // E1-6 Scope 1
        '_csrd_s1_gross_tco2e'              => 'number',
        '_csrd_s1_biogenic_co2_tco2e'       => 'number',
        '_csrd_s1_stationary_tco2e'         => 'number',
        '_csrd_s1_mobile_tco2e'             => 'number',
        '_csrd_s1_process_tco2e'            => 'number',
        '_csrd_s1_fugitive_tco2e'           => 'number',

        // E1-6 Scope 2
        '_csrd_s2_location_tco2e'           => 'number',
        '_csrd_s2_market_tco2e'             => 'number',
        '_csrd_s2_eac_coverage_pct'         => 'number',
        '_csrd_s2_grid_factor_source'       => 'string',
        '_csrd_s2_grid_country'             => 'string',

        // E1-6 Scope 3 (JSON-encoded category array)
        '_csrd_s3_categories_json'          => 'string',
        '_csrd_s3_omitted_json'             => 'string',

        // E1-5 Energy
        '_csrd_energy_total_mwh'            => 'number',
        '_csrd_energy_renewable_pct'        => 'number',
        '_csrd_energy_intensity_value'      => 'number',
        '_csrd_energy_intensity_denominator'=> 'string',

        // E1-7 Removals
        '_csrd_removals_tco2e'              => 'number',
        '_csrd_credits_tco2e'               => 'number',
        '_csrd_credits_standard'            => 'string',

        // GWP basis (applies to all figures above)
        '_csrd_gwp_basis'                   => 'string',
        '_csrd_reporting_year'              => 'integer',
        '_csrd_baseline_year'               => 'integer',
    ];

    foreach ( $fields as $key => $type ) {
        register_post_meta( 'gc_csrd_inventory', $key, [
            'show_in_rest'      => true,
            'single'            => true,
            'type'              => $type,
            'auth_callback'     => fn() => current_user_can( 'edit_posts' ),
            'sanitize_callback' => $type === 'number' ? 'floatval' : 'sanitize_text_field',
        ] );
    }
}
add_action( 'init', 'gc_register_csrd_inventory_meta' );

The JSON-encoded fields (_csrd_s3_categories_json, _csrd_s3_omitted_json) store the full category breakdown as a serialised array rather than as 30 individual meta keys. This keeps the meta table manageable and makes it easy to pass the full Scope 3 breakdown to a REST endpoint or report generator in a single get_post_meta() call.

What this model prevents

Four failure modes that show up in CSRD first filings when the data model wasn't designed for the standard:

1. Biogenic netting — biomass CO₂ rolled into gross Scope 1 total. Non-compliant from the first figure.

2. Single Scope 2 figure — no location/market split stored. Cannot produce a compliant E1-6 disclosure. Requires a full data backfill.

3. Missing Scope 3 omission justifications — categories silently absent from the report. Auditor asks why Cat 8 is missing. No documented reason exists.

4. Net figures in gross fields — removals or credits subtracted before the gross total is stored. The E1-6 gross figure is wrong and there is no way to reconstruct the correct number without raw inputs.

All four are architectural decisions, not data entry errors. The only way to prevent them is to build the field structure before the first data collection cycle, not after the first disclosure.

The GreenCalculus data layer implements these fields across 1,000+ calculators and tools. Full methodology documentation at greencalculus.com.

Building a SHA-256 audit trail for emission factor provenance in WordPress

Jeremiah Say — Mon, 11 May 2026 04:46:33 +0000

Carbon accounting tools have a trust problem that most developers don't think about until it's too late.

A sustainability officer files a CSRD disclosure. An auditor asks: "Where does this emission factor come from?" The tool says 2.57 kg CO₂e/litre for diesel. The auditor wants the source workbook, the specific tab, the row number, and the date someone verified the cell against the published file. Without that, the number is a claim, not evidence.

Most carbon platforms can't answer that question. At GreenCalculus.com, I designed the data layer so every single emission factor carries a _provenance block that answers it — and the automated verification pipeline hashes every source workbook against the issuing body's published file to prove the data hasn't drifted.

Here's how the whole thing works.

The problem with emission factor databases

Emission factors go stale in predictable ways:

Silent copy errors — a value gets transcribed from a source document with a rounding error or wrong unit and propagates for years
Version drift — DEFRA, IEA, EPA publish annual updates; any hardcoded factor is wrong by the following June
GWP basis ambiguity — the same gas has different CO₂e values depending on whether you use AR5 or AR6 GWP-100; most databases don't disclose which one
No chain of custody — you know the number but not who extracted it, from which cell, on which date

All four of these are audit failures, not just data quality issues. Under CSRD and ISO 14064, an auditor can request the full methodology chain for any material emission category. If your platform can't produce it, you have a liability.

The `_provenance` block

Every fuel, grid, and refrigerant factor in the GreenCalculus Master Brain carries a _provenance subkey. Here's a real example — diesel:

'diesel' => [
    'factor'   => 2.57082,
    'unit'     => 'kg CO2e per litre',
    'scope'    => 1,
    'source'   => 'DEFRA_2025',
    'gwp'      => 'AR5_100',
    'name'     => 'Diesel (average biofuel blend)',

    '_provenance' => [
        'source'           => 'UK Government GHG Conversion Factors for Company Reporting, Year 2025 Version 1, DESNZ, June 2025',
        'tab'              => 'Fuels',
        'row_label'        => 'Diesel (average biofuel blend)',
        'row_number'       => 87,
        'column'           => 'D — kg CO2e (per litre)',
        'gwp_basis'        => 'IPCC AR5 GWP-100',
        'sourced_by'       => 'Jeremiah Say',
        'sourced_on'       => '2026-05-06',
        'verified'         => true,
        'verified_against' => 'ghg-conversion-factors-2025-full-set.xlsx',
        'verified_date'    => '2026-05-08',
    ],
],

Every field is mandatory on Tier-1 sources (DEFRA, IEA, EPA). The row_number and column fields mean anyone with the source workbook can find the exact cell in under 30 seconds. sourced_by and sourced_on create a named, timestamped human record. verified_against points to the specific file that was hashed.

SHA-256 hashing the source workbooks

The verified_against field names a specific file. That file needs to be verifiably the same as what the issuing body published. This is where SHA-256 comes in.

When a new DEFRA or IEA release drops, the workflow is:

Download the official workbook
Hash it immediately before touching it
Store the hash in the Master Brain metadata
On every deploy, re-hash the stored file and compare

Here's the PHP that handles step 2–4:

/**
 * Hash a source workbook and return the hex digest.
 * Store this at intake. Re-run on deploy to verify no drift.
 *
 * @param  string $filepath  Absolute path to the workbook file.
 * @return string|false      SHA-256 hex digest, or false on failure.
 */
function gc_hash_source_workbook( string $filepath ) {
    if ( ! file_exists( $filepath ) || ! is_readable( $filepath ) ) {
        error_log( sprintf( '[GC Provenance] File not found or unreadable: %s', $filepath ) );
        return false;
    }

    return hash_file( 'sha256', $filepath );
}

/**
 * Verify a stored workbook hash against the live file on disk.
 * Run this in a deploy hook or WP-CLI command before publishing
 * any Master Brain update.
 *
 * @param  string $filepath       Absolute path to the workbook file.
 * @param  string $expected_hash  SHA-256 hex digest stored at intake.
 * @return bool                   True if file matches stored hash.
 */
function gc_verify_source_workbook( string $filepath, string $expected_hash ): bool {
    $live_hash = gc_hash_source_workbook( $filepath );

    if ( $live_hash === false ) {
        return false;
    }

    $match = hash_equals( $expected_hash, $live_hash );

    if ( ! $match ) {
        error_log( sprintf(
            '[GC Provenance] HASH MISMATCH: %s — expected %s, got %s',
            basename( $filepath ),
            $expected_hash,
            $live_hash
        ) );
    }

    return $match;
}

hash_equals() is used instead of === to prevent timing attacks — a minor point for offline files, but a correct habit.

The stored hashes live in the Master Brain metadata block:

'meta' => [
    'version'    => '2025.6',
    'updated'    => '2026-05-09',
    'gwp_basis'  => 'AR5_100',

    'source_workbook_hashes' => [
        'DEFRA_2025' => [
            'filename' => 'ghg-conversion-factors-2025-full-set.xlsx',
            'sha256'   => 'a3f8c2...', // full 64-char hex digest
            'verified' => '2026-05-08',
        ],
        'EPA_2024' => [
            'filename' => 'egrid2022_summary_tables.pdf',
            'sha256'   => 'b91d47...',
            'verified' => '2026-05-09',
        ],
    ],
],

Running the verification check on deploy

The verification runs as a WP-CLI command that blocks the deploy if any hash fails:

/**
 * WP-CLI command: verify all source workbook hashes.
 * Run before publishing any Master Brain version bump.
 *
 * Usage: wp gc verify-provenance
 */
if ( defined( 'WP_CLI' ) && WP_CLI ) {

    WP_CLI::add_command( 'gc verify-provenance', function () {

        $brain  = gc_get_master_brain_data();
        $hashes = $brain['meta']['source_workbook_hashes'] ?? [];
        $dir    = WP_CONTENT_DIR . '/gc-source-workbooks/';
        $passed = 0;
        $failed = 0;

        foreach ( $hashes as $source_id => $entry ) {
            $filepath = $dir . $entry['filename'];
            $ok       = gc_verify_source_workbook( $filepath, $entry['sha256'] );

            if ( $ok ) {
                WP_CLI::success( "{$source_id}: {$entry['filename']} — hash verified ✓" );
                $passed++;
            } else {
                WP_CLI::error( "{$source_id}: {$entry['filename']} — HASH MISMATCH ✗", false );
                $failed++;
            }
        }

        WP_CLI::line( "---" );
        WP_CLI::line( "Passed: {$passed} | Failed: {$failed}" );

        if ( $failed > 0 ) {
            WP_CLI::error( "Provenance check failed. Do not publish this Master Brain version." );
            exit( 1 );
        }

        WP_CLI::success( "All source workbooks verified. Safe to publish." );
    } );
}

exit(1) means a CI pipeline that runs wp gc verify-provenance will block the deploy automatically if any workbook has drifted.

The `_provenance` enforcement check

Hash verification proves the workbook is intact. But it doesn't prove every factor in the Master Brain was actually extracted from it. For that, there's a second check that scans every entry and flags any that are missing _provenance:

/**
 * WP-CLI command: audit all Master Brain factor entries for _provenance.
 *
 * Usage: wp gc audit-provenance
 */
if ( defined( 'WP_CLI' ) && WP_CLI ) {

    WP_CLI::add_command( 'gc audit-provenance', function () {

        $brain    = gc_get_master_brain_data();
        $sections = [ 'fuels', 'fuels_wtt', 'grid', 'refrigerants', 'agriculture' ];
        $missing  = [];

        foreach ( $sections as $section ) {
            $entries = $brain[ $section ] ?? [];

            foreach ( $entries as $key => $entry ) {
                // Skip non-array entries and nested subgroups
                if ( ! is_array( $entry ) || ! isset( $entry['factor'] ) ) {
                    continue;
                }

                if ( empty( $entry['_provenance'] ) ) {
                    $missing[] = "{$section}.{$key}";
                } elseif ( empty( $entry['_provenance']['verified'] ) || $entry['_provenance']['verified'] !== true ) {
                    $missing[] = "{$section}.{$key} (unverified)";
                }
            }
        }

        if ( empty( $missing ) ) {
            WP_CLI::success( "All factors carry verified _provenance blocks." );
            return;
        }

        WP_CLI::warning( count( $missing ) . " factor(s) missing or unverified provenance:" );
        foreach ( $missing as $key ) {
            WP_CLI::line( "  — {$key}" );
        }

        exit( 1 );
    } );
}

How this surfaces in the schema graph

The verification pipeline isn't just internal tooling. It's represented in the site's Schema.org entity graph as a SoftwareApplication node:

function gc_get_engineering_node(): array {
    return [
        '@type'          => 'SoftwareApplication',
        '@id'            => home_url( '/#engineering' ),
        'name'           => 'GreenCalculus Engineering',
        'description'    => 'Automated verification pipeline. Performs SHA-256 hash verification of source workbooks against the issuing body\'s published files, enforces cell-by-cell provenance attribution on every emission factor, and cross-checks methodology prose against the data layer before publication.',
        'featureList'    => 'SHA-256 hash verification of source workbooks; cell-by-cell _provenance enforcement; dual GWP basis disclosure (AR5/AR6); 30-day Tier-1 update SLA; prose-vs-data cross-validation; public changelog audit graph',
        'softwareVersion' => '2026.05',
    ];
}

Every calculator and methodology page then references this entity as reviewedBy:

$schema['reviewedBy'] = [ '@id' => home_url( '/#engineering' ) ];

This is Schema.org's explicit signal for "who fact-checked this content." It's backed by real machinery — not a fabricated review board. An auditor who follows the @id to /governance/ will find the full description of what the pipeline actually does. The schema points to real code, not a badge.

The discipline this enforces

The whole system only works if it's enforced at authorship time, not patched in later. The rule at GreenCalculus is:

No factor enters the Master Brain without a complete _provenance block. verified: true means a human has opened the source workbook, found the cell, confirmed the value, and signed it with their name and date.

When the DEFRA 2025 release dropped the UK grid factor from 0.207 to 0.177 — a 15% change — the update produced a new _provenance block with a new sourced_on date, a new verified_date, and a public changelog entry stating the old and new values explicitly. The SHA-256 hash of the new workbook replaced the old one in the metadata. The CI pipeline re-ran the hash check on the next deploy and passed.

That's the full chain: source document → hash → cell reference → human verification → named attribution → public changelog. Every link is traceable. Every link is automated where possible and named where it requires human judgment.

For CSRD filers who need to point an auditor at a methodology chain, that's not optional infrastructure. It's the product.

The full GreenCalculus Master Brain data layer, verification pipeline, and public changelog are at greencalculus.com.

How to build a grid emission factor lookup in Vanilla JS using IEA 2026 regional data

Jeremiah Say — Mon, 11 May 2026 04:43:08 +0000

Most Scope 2 carbon calculators I've reviewed do one of two things: hardcode a single global average factor and call it a day, or reach for a third-party API that charges per lookup and introduces a network dependency into a calculation that should be instant and deterministic.

Neither is acceptable if you're building tools that practitioners will use to file regulatory disclosures.

Here's how I structure the grid emission factor lookup at GreenCalculus.com, using a flat data object sourced from IEA 2026, DEFRA 2025, and EPA eGRID 2024 — with zero runtime dependencies.

Why grid factors are harder than they look

The GHG Protocol Scope 2 Guidance requires companies to report two methods wherever data is available:

Location-based: average grid emission intensity for the country or subregion where electricity is consumed (kWh × grid factor = kgCO₂e)
Market-based: factor from a specific electricity contract, renewable energy certificate (EAC/REGO), or supplier disclosure

Location-based is what you can build a deterministic lookup for. Market-based requires data the user must supply. A well-built calculator handles both paths, makes the distinction visible, and never conflates them.

Second problem: a single national average is often wrong. The US national average from EPA eGRID is 0.386 kg CO₂e/kWh. But a data centre in Upstate New York (hydro + nuclear dominated) sits at 0.125 kg CO₂e/kWh — nearly a 3× difference. Using the national average here would overstate Scope 2 by 200%. For CSRD filers, that's a material error.

The data structure

I maintain all factors in a single PHP object (the "Master Brain") that gets injected into window.gcMasterBrain server-side. Every calculator reads from window.gcMasterBrain.grid[countryCode].factor. No hardcoded numbers anywhere in calculator JS.

Here's the shape of each entry:

// window.gcMasterBrain.grid (subset shown)
const gridFactors = {

  // Europe
  GB: { factor: 0.177, unit: "kg CO2e per kWh", source: "DEFRA_2025", year: 2025, name: "United Kingdom", note: "DEFRA 2025. -15% vs 2024." },
  DE: { factor: 0.364, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Germany" },
  FR: { factor: 0.052, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "France",    note: "~70% nuclear" },
  PL: { factor: 0.635, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Poland",    note: "Coal-heavy mix" },
  SE: { factor: 0.013, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Sweden",    note: "Hydro + nuclear" },
  NO: { factor: 0.009, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Norway",    note: "~99% hydropower" },

  // Asia-Pacific
  IN: { factor: 0.708, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "India" },
  CN: { factor: 0.581, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "China",     note: "Declining as solar/wind scales" },
  JP: { factor: 0.453, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Japan" },
  SG: { factor: 0.408, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Singapore" },
  AU: { factor: 0.510, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "Australia" },
  NZ: { factor: 0.098, unit: "kg CO2e per kWh", source: "IEA_2026",   year: 2026, name: "New Zealand", note: "Geothermal + hydro" },

  // US — EPA eGRID 2024 subregions
  // National average is almost never the right choice for a specific site.
  US:           { factor: 0.386,  source: "EPA_2024", name: "United States (national avg)" },
  US_NYUP:      { factor: 0.1249, source: "EPA_2024", name: "NYUP — Upstate New York",  note: "Hydro 31% + nuclear 31%" },
  US_WECC_CAMX: { factor: 0.2265, source: "EPA_2024", name: "CAMX — California",        note: "Gas 46% + solar 20%" },
  US_ERCT:      { factor: 0.3512, source: "EPA_2024", name: "ERCT — Texas (ERCOT)",     note: "Gas 47% + wind 23%" },
  US_RFCW:      { factor: 0.4563, source: "EPA_2024", name: "RFCW — Ohio Valley",       note: "Coal 31% + gas 32%" },
  US_SRMW:      { factor: 0.6260, source: "EPA_2024", name: "SRMW — SERC Midwest",      note: "Coal 59% — highest subregion" },
};

Every entry carries source and year. These render in the calculator UI next to the result — not hidden in a tooltip, not buried in a footnote. If someone is using this number in a regulatory disclosure, they need to see the citation inline.

The lookup function

/**
 * Look up a grid emission factor.
 *
 * @param {string} countryCode  ISO 3166-1 alpha-2 or US eGRID subregion key
 * @param {object} brain        window.gcMasterBrain (injected server-side)
 * @returns {{ factor: number, source: string, year: number, name: string } | null}
 */
function getGridFactor(countryCode, brain) {
  const key = countryCode.toUpperCase();
  const entry = brain?.grid?.[key] ?? null;

  if (!entry) {
    console.error(`[GC] Grid factor not found for key: "${key}"`);
    return null;
  }

  return entry;
}

Tiny, deterministic, no fetch. The ?? guard means a missing or malformed Master Brain injection fails gracefully — the calculator surfaces an error state rather than silently outputting NaN * 0 = 0 into a user's report.

The calculation

/**
 * Scope 2 location-based electricity emissions.
 *
 * @param {number} kWh          Electricity consumed (kWh)
 * @param {string} countryCode  Grid lookup key
 * @param {object} brain        window.gcMasterBrain
 * @returns {{ kgCO2e: number, tCO2e: number, citation: string } | null}
 */
function calcScope2LocationBased(kWh, countryCode, brain) {
  const grid = getGridFactor(countryCode, brain);
  if (!grid) return null;

  const kgCO2e = kWh * grid.factor;

  return {
    kgCO2e:   +kgCO2e.toFixed(4),
    tCO2e:    +(kgCO2e / 1000).toFixed(6),
    citation: `${grid.source} (${grid.year}) — ${grid.name}`,
    factor:   grid.factor,
    note:     grid.note ?? null,
  };
}

The return object always includes citation. Downstream rendering code has no excuse to display a number without its source.

Rendering the citation inline

function renderScope2Result(result, outputEl, citationEl) {
  if (!result) {
    outputEl.textContent = "—";
    citationEl.textContent = "Factor not available for this region.";
    return;
  }

  outputEl.textContent = `${result.tCO2e} tCO₂e`;
  citationEl.textContent = result.citation;

  if (result.note) {
    citationEl.textContent += ` · ${result.note}`;
  }
}

The output element should have font-family: 'JetBrains Mono', monospace; font-variant-numeric: tabular-nums in CSS. When a user changes the kWh input, digits update in-place without layout shift — a subtle but important signal that this is a precision instrument, not a toy.

The stale factor problem

Grid factors change every year. IEA publishes in April. DEFRA publishes every June. EPA eGRID publishes in January.

The UK grid factor dropped 15% in the DEFRA 2025 release — from 0.207 to 0.177 kg CO₂e/kWh. Any calculator that hardcoded the 2024 value is now overstating UK Scope 2 by 17%. For a 10 GWh/year operation, that's roughly 300 tCO₂e of phantom emissions in a filed disclosure.

The pattern I use to prevent this:

All factors live in one file with a version constant (GC_MB_VERSION = '2025.6')
The version renders in every calculator's footer: Data: DEFRA 2025 / IEA 2026 / EPA eGRID 2024
A fallback version constant is gated in CI — it must match the Master Brain version on every deploy
The update calendar is hardcoded as a comment in the source file so it cannot be missed

If a factor update deploys with a version bump but the fallback table is not updated in the same commit, a console.error fires on every page load identifying the stale page by post ID. One-click diagnosis.

What this gives you

A lookup that is:

Deterministic — same inputs, same output, every time, no network round-trip
Auditable — every result carries its source citation inline
Maintainable — one file to update annually, propagates to every calculator automatically
GHG Protocol compliant — location-based correctly separated from market-based; Scope 3 Category 3 (fuel and energy-related activities) handled as a distinct calculation

The full dataset — 50 countries and US eGRID subregions — is live at greencalculus.com.

Sources: IEA Global Energy Review 2026 · DEFRA GHG Conversion Factors 2025 (DESNZ) · EPA eGRID Summary Tables 2022, published January 2024 · GHG Protocol Scope 2 Guidance

Building a zero-dependency carbon calculator platform — architecture decisions and why I rejected every framework

Jeremiah Say — Sun, 10 May 2026 09:02:30 +0000

When I started building GreenCalculus — a carbon calculator platform
for sustainability officers and CSRD compliance teams — the first
decision wasn't which framework to use. It was whether to use one at all.

I chose not to. Here's why, and what I built instead.

The problem with frameworks for calculation tools

Carbon calculators have a specific job: take a number in, multiply it
by an emission factor, output a result in tCO₂e. That's it.

The interaction model is:

User selects fuel type
User enters quantity
User clicks Calculate
Result appears instantly

There is no routing. There is no global state. There is no component
tree. There is no reason to ship 40kb of runtime to do three
multiplications.

React, Vue, and Svelte are excellent tools. They're the wrong tool
for this job.

What "zero dependencies" actually means

No npm. No bundler. No node_modules. No build step.

The entire calculator is:

One HTML file
CSS in a <style> block
JavaScript in a <script> block
Served directly from GitHub Pages

A user on a slow 3G connection in a developing market — where carbon
accounting is growing fastest — loads the calculator in under a second.
There is nothing to parse except the page itself.

This also means zero supply chain risk. No dependency vulnerabilities.
No breaking changes from upstream packages. No npm audit with 47
moderate severity warnings.

CSS @layer architecture

The stylesheet uses the CSS @layer cascade system:

@layer base, layout, components, interactive;

This gives explicit control over specificity without fighting the
cascade. @layer base sets design tokens and resets. @layer layout
handles the 2-column dashboard grid. @layer components styles
individual UI elements. @layer interactive handles state changes.

The result: zero !important declarations in the entire codebase.

Fluid typography with clamp()

Every font size is fluid:

font-size: clamp(1.25rem, 3vw, 1.75rem);

No breakpoint-based font size overrides. No separate mobile stylesheet.
The layout responds smoothly across every viewport without a single
media query for typography.

The design brief calls for GreenCalculus to feel like a "premium
scientific instrument." Fluid type that never jumps or breaks is part
of that feel.

JetBrains Mono + tabular-nums for number stability

This one is underrated. Carbon calculator outputs update in real time
as users type. Without tabular-nums, the result value shifts
horizontally as digits change width — it looks broken even when the
math is correct.

.result-value {
  font-family: 'JetBrains Mono', monospace;
  font-variant-numeric: tabular-nums;
}

Every digit is now the same width. The number is rock-steady during
updates. On a platform where numerical precision is the entire value
proposition, this matters.

2-column dashboard layout — inputs left, results right

B2B sustainability tools are used by people who live in dashboards.
The layout mirrors that mental model:

.gc-calc {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 1.5rem;
  align-items: start;
}

Left panel: inputs (fuel type, quantity, reporting period).

Right panel: results (tCO₂e output, calculation breakdown, source).

The user never loses sight of their inputs while reading the result.
No scrolling required. No modal. No separate results page.

On mobile it collapses to single column via one media query.

Logical properties for internationalisation

All spacing uses CSS Logical Properties:

margin-block-end: 1.25rem;
padding-inline: 1.5rem;

Instead of margin-bottom and padding-left/right. This is future-proofing
for RTL language support (Arabic, Hebrew) without a single line of
additional CSS. GreenCalculus will eventually serve markets where RTL
is the default — the architecture supports it from day one.

The calculation engine

The core formula for every GHG Protocol Scope 1 calculator:
Emissions (tCO₂e) = Activity Data × Emission Factor × GWP

In JavaScript:

const kg = quantity * FACTORS[fuelKey].factor;
const annualKg = kg / reportingPeriodFraction;
const annualTonnes = annualKg / 1000;

That's the entire calculation. Three lines. No library needed.

Emission factors come from UK DESNZ 2024. GWP values are IPCC AR6
GWP-100 — not AR5. The difference matters: fossil methane GWP is 29.8
under AR6, versus 25 under AR5. A 19% understatement if you're using
old values.

The full open dataset is published separately:

→ greencalculus/greencalculus-methodology

Precision and rounding rules

Raw outputs are computed to full floating-point precision. Rounding
is applied only at the display step:

const display = annualTonnes >= 1
  ? annualTonnes.toFixed(2)   // results >= 1t: 2 decimal places
  : annualTonnes.toFixed(4);  // results < 1t: 4 decimal places

Never round intermediate values. Always round display values. This
is the GHG Protocol precision standard applied in code.

What I would use a framework for

To be clear: this isn't a framework vs no-framework manifesto.

I would use React or Vue for:

A multi-step emissions inventory wizard with complex state
A comparison tool pulling live data from multiple APIs
A reporting dashboard with filterable tables across 15 Scope 3 categories

For a single-purpose calculation tool with one input → one output,
Vanilla JS is the correct choice. Match the tool to the job.

Live demo

The Scope 1 stationary combustion calculator is live on GitHub Pages:

→ greencalculus.github.io/greencalculus-calculator-demo

Source is open — MIT licensed:

→ greencalculus/greencalculus-calculator-demo

The platform is still being built. This is the first calculator of
many. If you're working in sustainability tech or have questions on
the GHG Protocol methodology, I'm happy to discuss in the comments.

Why most carbon calculators are using the wrong methane GWP value (and how to fix it)

Jeremiah Say — Sun, 10 May 2026 08:58:19 +0000

If your carbon calculator uses a GWP-100 value of 25 for methane, it's out of date by one full IPCC assessment cycle.

The problem

The IPCC Sixth Assessment Report (AR6), published 2021, updated GWP-100 values significantly:

Gas	AR5	AR6	Change
CH4 (fossil)	25	29.8	+19.2%
CH4 (biogenic)	25	27.9	+11.6%
N2O	265	273	+3.0%
SF6	23,500	25,200	+7.2%

For a company with significant natural gas combustion, refrigerant leaks, or agricultural emissions, the difference between AR5 and AR6 is not cosmetic. It's a ~19% understatement of methane-related emissions.

Why it hasn't been fixed widely

The GHG Protocol Corporate Standard permits either AR5 or AR6. Most tools defaulted to AR5 when they launched and haven't updated. Many sustainability teams don't know which GWP basis their tools use — it's rarely displayed prominently.

What fossil vs biogenic methane means

AR6 distinguishes two GWP values for CH4:

Fossil CH4 (29.8) — use for natural gas combustion, coal mining fugitives, oil & gas fugitive emissions
Biogenic CH4 (27.9) — use for landfill gas, agricultural emissions, managed biological processes

Most tools use a single CH4 value and don't distinguish. This is technically incorrect under AR6.

How to check your tools

Look for a "methodology" or "about" page on any carbon calculator you use. It should state:

Which IPCC assessment report the GWP values come from
Whether fossil and biogenic CH4 are treated separately
The source for emission factors (DESNZ, EPA, IPCC 2006, etc.)

If it doesn't disclose this, treat the output with caution.

What we built

I'm building GreenCalculus — a platform for carbon accounting calculators — and published the full AR6 GWP dataset openly on GitHub:

→ greencalculus/greencalculus-methodology

The data/gwp-values.json file has all 16 gases with AR5 and AR6 values side by side so you can audit your own tools. The METHODOLOGY.md explains exactly how we apply the GHG Protocol hierarchy.

Live demo

Scope 1 stationary combustion calculator using correct AR6 values, zero dependencies:

→ greencalculus.github.io/greencalculus-calculator-demo

Built in Vanilla JS — no frameworks, no bundler, ~300 lines. The calculation is:
Emissions (tCO₂e) = Activity Data × Emission Factor × GWP

Where GWP = 1 for factors already expressed in CO₂e (most fuel factors are pre-multiplied), and the AR6 value for raw gas quantities.

Bottom line

Check your GWP basis. If it says 25 for CH4, update it to 29.8 (fossil) or 27.9 (biogenic). Your Scope 1 inventory depends on it — and so does your CSRD disclosure.

The full open dataset is free to use and cite:
→ github.com/greencalculus/greencalculus-methodology

DEV Community: Jeremiah Say

The "Audit Trail" Pattern: Architecture for Immutable Sustainability Data

The Problem: The "Floating" Emission Factor

The Solution: The Snapshot Pattern

The JSON Data Structure

Implementation: The Three-Tier Storage Strategy

1. The Activity Ledger (Source of Truth)

2. The Factor Registry (The Library)

3. The Calculation Archive (The Receipt)

The Code: A PHP/Laravel Implementation

Audit-Proofing the Frontend

What this architecture prevents

Floating-point will quietly corrupt your emissions math, and 0.1 + 0.2 already warned you

Why this bites harder in measurement code than anywhere else

The float problem, stated precisely

Failure mode 1: the total that won't reconcile

Fix: control precision at the boundary, not in the loop

Failure mode 2: the wide-magnitude swallow

Fix: sum within magnitude bands, then combine

Failure mode 3: the ratio that amplifies

Fix: defer rounding, widen the working precision

Failure mode 4: the unit-boundary shave

The rule underneath all four

CSRD/ESRS E1 disclosure requirements, translated into data fields — a developer's map

What ESRS E1 actually requires

E1-6: GHG emissions — the core inventory

Scope 1 — direct emissions

Scope 2 — purchased electricity, steam, heat, cooling

Scope 3 — value chain emissions

E1-7: GHG removals and carbon credits

E1-5: Energy consumption and mix

E1-4: Climate targets

The GWP basis problem

The field map as a WordPress custom post meta schema

What this model prevents

Building a SHA-256 audit trail for emission factor provenance in WordPress

The problem with emission factor databases

The _provenance block

SHA-256 hashing the source workbooks

Running the verification check on deploy

The _provenance enforcement check

How this surfaces in the schema graph

The discipline this enforces

How to build a grid emission factor lookup in Vanilla JS using IEA 2026 regional data

Why grid factors are harder than they look

The data structure

The lookup function

The calculation

Rendering the citation inline

The stale factor problem

What this gives you

Building a zero-dependency carbon calculator platform — architecture decisions and why I rejected every framework

The problem with frameworks for calculation tools

What "zero dependencies" actually means

CSS @layer architecture

Fluid typography with clamp()

JetBrains Mono + tabular-nums for number stability

2-column dashboard layout — inputs left, results right

Logical properties for internationalisation

The calculation engine

Precision and rounding rules

What I would use a framework for

Live demo

Why most carbon calculators are using the wrong methane GWP value (and how to fix it)

The problem

Why it hasn't been fixed widely

What fossil vs biogenic methane means

How to check your tools

What we built

Live demo

Bottom line

The `_provenance` block

The `_provenance` enforcement check