feat: implement Phase 1 — energy/carbon budget enforcement pipeline

Rewrite manifest, ABI, and codegen modules from generic scaffolding to
eclexiaiser's core purpose: energy, carbon, and resource-cost awareness.

- Manifest: parse eclexiaiser.toml with per-function energy-budget-mj,
  carbon-budget-mg, carbon provider config (watttime/electricity-maps/static),
  and report format (text/json/csrd). Full semantic validation.
- ABI: EnergyBudget, CarbonBudget, CarbonProvider, CarbonConfig,
  ComplianceStatus, FunctionMeasurement, SustainabilityReport types with
  carbon estimation formula and compliance threshold logic.
- Codegen parser: validate function annotations and identifiers.
- Codegen instrumenter: generate Rust measurement wrappers with per-function
  budget constants and Eclexia constraint files (.ecl S-expression format).
- Codegen reporter: text, JSON, and EU CSRD-compliant sustainability reports
  with simulated measurements and actionable recommendations.
- 10 integration tests + 23 unit tests (all passing).
- Example green-service manifest in examples/.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

Cargo.lock

@@ -14,6 +14,7 @@ categories = ["command-line-utilities", "development-tools"]
 clap = { version = "4", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 toml = "0.8"
+serde_json = "1"
 anyhow = "1"
 thiserror = "2"
 handlebars = "6"

Cargo.toml

@@ -0,0 +1,34 @@
+# Example eclexiaiser manifest for a "green-service" web application.
+# SPDX-License-Identifier: PMPL-1.0-or-later
+#
+# This manifest declares energy and carbon budgets for two functions:
+# - process_batch: a batch data processing function (50 mJ, 10 mg CO2 max)
+# - render_page: a web page renderer (5 mJ max, no carbon budget)
+#
+# Run:
+#   eclexiaiser validate -m examples/green-service/eclexiaiser.toml
+#   eclexiaiser generate -m examples/green-service/eclexiaiser.toml -o generated/green-service
+#   eclexiaiser info -m examples/green-service/eclexiaiser.toml
+
+[project]
+name = "green-service"
+
+[[functions]]
+name = "process_batch"
+source = "src/batch.rs"
+energy-budget-mj = 50.0         # millijoules max per call
+carbon-budget-mg = 10.0         # mg CO2 max per call
+
+[[functions]]
+name = "render_page"
+source = "src/web.rs"
+energy-budget-mj = 5.0
+
+[carbon]
+provider = "watttime"           # watttime | electricity-maps | static
+region = "GB"                   # grid region
+static-intensity = 200.0        # mg CO2/kWh (fallback if provider = static)
+
+[report]
+format = "text"                 # text | json | csrd
+include-recommendations = true

examples/green-service/eclexiaiser.toml

@@ -1,3 +1,333 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
 // Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-// ABI module for eclexiaiser — Idris2 proof types for Eclexia interface correctness.
+//
+// ABI module for eclexiaiser — core types for energy budgets, carbon intensity,
+// sustainability reporting, and Eclexia constraint generation.
+//
+// These types form the contract between manifest parsing, code instrumentation,
+// and report generation. In the full ABI-FFI architecture, corresponding Idris2
+// definitions in `src/abi/*.idr` would provide formal proofs of interface
+// correctness, and Zig FFI in `ffi/zig/` would expose C-ABI bindings.
+
+use serde::{Deserialize, Serialize};
+
+/// Energy budget for a single function, expressed in millijoules (mJ).
+///
+/// An `EnergyBudget` constrains how much energy a single invocation of a
+/// function is allowed to consume. Exceeding the budget triggers a warning
+/// or error in the sustainability report.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct EnergyBudget {
+    /// Maximum energy consumption per call, in millijoules.
+    pub max_millijoules: f64,
+}
+
+impl EnergyBudget {
+    /// Create a new energy budget with the given millijoule limit.
+    ///
+    /// # Panics
+    /// Panics if `max_millijoules` is negative.
+    pub fn new(max_millijoules: f64) -> Self {
+        assert!(
+            max_millijoules >= 0.0,
+            "Energy budget cannot be negative: {max_millijoules}"
+        );
+        Self { max_millijoules }
+    }
+
+    /// Check whether a measured energy value exceeds this budget.
+    pub fn is_exceeded_by(&self, measured_millijoules: f64) -> bool {
+        measured_millijoules > self.max_millijoules
+    }
+
+    /// Calculate the percentage of budget used by a measurement.
+    pub fn usage_percent(&self, measured_millijoules: f64) -> f64 {
+        if self.max_millijoules == 0.0 {
+            if measured_millijoules > 0.0 {
+                return f64::INFINITY;
+            }
+            return 0.0;
+        }
+        (measured_millijoules / self.max_millijoules) * 100.0
+    }
+}
+
+/// Carbon budget for a single function, expressed in milligrams of CO2 equivalent.
+///
+/// This constrains the carbon emissions attributable to a function call, computed
+/// from energy consumption multiplied by grid carbon intensity.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CarbonBudget {
+    /// Maximum CO2 emissions per call, in milligrams.
+    pub max_mg_co2: f64,
+}
+
+impl CarbonBudget {
+    /// Create a new carbon budget with the given mg CO2 limit.
+    pub fn new(max_mg_co2: f64) -> Self {
+        assert!(
+            max_mg_co2 >= 0.0,
+            "Carbon budget cannot be negative: {max_mg_co2}"
+        );
+        Self { max_mg_co2 }
+    }
+
+    /// Check whether a measured carbon value exceeds this budget.
+    pub fn is_exceeded_by(&self, measured_mg_co2: f64) -> bool {
+        measured_mg_co2 > self.max_mg_co2
+    }
+}
+
+/// Carbon intensity provider — the source of grid carbon intensity data.
+///
+/// Eclexia supports multiple providers for real-time or static carbon intensity
+/// values, enabling accurate carbon accounting per grid region.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum CarbonProvider {
+    /// WattTime API — real-time marginal emissions data.
+    Watttime,
+    /// Electricity Maps API — real-time lifecycle emissions.
+    ElectricityMaps,
+    /// Static intensity value, useful for offline or testing scenarios.
+    Static,
+}
+
+impl CarbonProvider {
+    /// Return a human-readable display name for the provider.
+    pub fn display_name(&self) -> &'static str {
+        match self {
+            CarbonProvider::Watttime => "WattTime",
+            CarbonProvider::ElectricityMaps => "Electricity Maps",
+            CarbonProvider::Static => "Static",
+        }
+    }
+}
+
+/// Carbon configuration section — provider, region, and static fallback.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CarbonConfig {
+    /// Which carbon intensity provider to use.
+    pub provider: CarbonProvider,
+    /// Grid region code (e.g., "GB", "DE", "US-CAL-CISO").
+    pub region: String,
+    /// Static intensity in mg CO2 per kWh (used when provider is Static).
+    #[serde(rename = "static-intensity", default)]
+    pub static_intensity: f64,
+}
+
+impl CarbonConfig {
+    /// Compute carbon emissions in mg CO2 from energy in millijoules.
+    ///
+    /// Uses the static intensity value. For real-time providers, the actual
+    /// intensity would be fetched from the API at measurement time; this method
+    /// serves as the fallback calculation.
+    ///
+    /// Formula: mg_co2 = (millijoules / 3_600_000) * (mg_co2_per_kwh)
+    /// Because 1 kWh = 3,600,000,000 mJ, but intensity is in mg/kWh:
+    /// mg_co2 = millijoules * intensity / 3_600_000_000
+    pub fn estimate_carbon_mg(&self, millijoules: f64) -> f64 {
+        millijoules * self.static_intensity / 3_600_000_000.0
+    }
+}
+
+/// Report format for sustainability output.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ReportFormat {
+    /// Plain text report, human-readable.
+    Text,
+    /// JSON report, machine-readable.
+    Json,
+    /// EU CSRD (Corporate Sustainability Reporting Directive) compliant format.
+    Csrd,
+}
+
+/// Report configuration section.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ReportConfig {
+    /// Output format for the sustainability report.
+    pub format: ReportFormat,
+    /// Whether to include actionable recommendations for reducing impact.
+    #[serde(rename = "include-recommendations", default)]
+    pub include_recommendations: bool,
+}
+
+/// A single function's energy/carbon budget configuration, as declared in the manifest.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FunctionBudget {
+    /// Function name (fully qualified or short).
+    pub name: String,
+    /// Source file containing the function.
+    pub source: String,
+    /// Energy budget in millijoules per call (None = unbounded).
+    #[serde(rename = "energy-budget-mj")]
+    pub energy_budget_mj: Option<f64>,
+    /// Carbon budget in mg CO2 per call (None = unbounded).
+    #[serde(rename = "carbon-budget-mg")]
+    pub carbon_budget_mg: Option<f64>,
+}
+
+impl FunctionBudget {
+    /// Build an `EnergyBudget` from this function's config, if specified.
+    pub fn energy_budget(&self) -> Option<EnergyBudget> {
+        self.energy_budget_mj.map(EnergyBudget::new)
+    }
+
+    /// Build a `CarbonBudget` from this function's config, if specified.
+    pub fn carbon_budget(&self) -> Option<CarbonBudget> {
+        self.carbon_budget_mg.map(CarbonBudget::new)
+    }
+}
+
+/// Compliance status for a single function measurement against its budget.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum ComplianceStatus {
+    /// Within budget (usage <= 100%).
+    Compliant,
+    /// Approaching budget (usage > 80% but <= 100%).
+    Warning,
+    /// Over budget (usage > 100%).
+    Exceeded,
+    /// No budget was set, so compliance is not applicable.
+    Unbounded,
+}
+
+impl ComplianceStatus {
+    /// Determine compliance status from a budget usage percentage.
+    pub fn from_usage_percent(percent: f64) -> Self {
+        if percent > 100.0 {
+            ComplianceStatus::Exceeded
+        } else if percent > 80.0 {
+            ComplianceStatus::Warning
+        } else {
+            ComplianceStatus::Compliant
+        }
+    }
+
+    /// Return a short label for display purposes.
+    pub fn label(&self) -> &'static str {
+        match self {
+            ComplianceStatus::Compliant => "COMPLIANT",
+            ComplianceStatus::Warning => "WARNING",
+            ComplianceStatus::Exceeded => "EXCEEDED",
+            ComplianceStatus::Unbounded => "UNBOUNDED",
+        }
+    }
+}
+
+/// A measurement result for a single function, including energy, carbon, and compliance.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FunctionMeasurement {
+    /// Name of the measured function.
+    pub function_name: String,
+    /// Measured energy in millijoules.
+    pub measured_energy_mj: f64,
+    /// Estimated carbon in mg CO2.
+    pub estimated_carbon_mg: f64,
+    /// Energy budget compliance.
+    pub energy_compliance: ComplianceStatus,
+    /// Carbon budget compliance.
+    pub carbon_compliance: ComplianceStatus,
+}
+
+/// A complete sustainability report for a project.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct SustainabilityReport {
+    /// Project name.
+    pub project_name: String,
+    /// Grid region used for carbon calculations.
+    pub region: String,
+    /// Carbon intensity provider name.
+    pub provider: String,
+    /// Per-function measurement results.
+    pub measurements: Vec<FunctionMeasurement>,
+    /// Total energy across all measured functions, in millijoules.
+    pub total_energy_mj: f64,
+    /// Total estimated carbon across all measured functions, in mg CO2.
+    pub total_carbon_mg: f64,
+    /// Overall compliance: true if all functions are compliant or warning.
+    pub all_compliant: bool,
+    /// Actionable recommendations (empty if not requested).
+    pub recommendations: Vec<String>,
+}
+
+impl SustainabilityReport {
+    /// Return the count of functions that exceeded their energy budget.
+    pub fn energy_violations(&self) -> usize {
+        self.measurements
+            .iter()
+            .filter(|m| m.energy_compliance == ComplianceStatus::Exceeded)
+            .count()
+    }
+
+    /// Return the count of functions that exceeded their carbon budget.
+    pub fn carbon_violations(&self) -> usize {
+        self.measurements
+            .iter()
+            .filter(|m| m.carbon_compliance == ComplianceStatus::Exceeded)
+            .count()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_energy_budget_compliance() {
+        let budget = EnergyBudget::new(50.0);
+        assert!(!budget.is_exceeded_by(49.9));
+        assert!(!budget.is_exceeded_by(50.0));
+        assert!(budget.is_exceeded_by(50.1));
+        assert!((budget.usage_percent(25.0) - 50.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn test_carbon_budget_compliance() {
+        let budget = CarbonBudget::new(10.0);
+        assert!(!budget.is_exceeded_by(10.0));
+        assert!(budget.is_exceeded_by(10.001));
+    }
+
+    #[test]
+    fn test_carbon_estimation() {
+        let config = CarbonConfig {
+            provider: CarbonProvider::Static,
+            region: "GB".to_string(),
+            static_intensity: 200.0,
+        };
+        // 3,600,000,000 mJ = 1 kWh => at 200 mg/kWh => 200 mg
+        // 3,600,000 mJ => 0.001 kWh => 0.2 mg
+        let carbon = config.estimate_carbon_mg(3_600_000.0);
+        assert!((carbon - 0.2).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_compliance_status_from_percent() {
+        assert_eq!(
+            ComplianceStatus::from_usage_percent(50.0),
+            ComplianceStatus::Compliant
+        );
+        assert_eq!(
+            ComplianceStatus::from_usage_percent(85.0),
+            ComplianceStatus::Warning
+        );
+        assert_eq!(
+            ComplianceStatus::from_usage_percent(101.0),
+            ComplianceStatus::Exceeded
+        );
+    }
+
+    #[test]
+    fn test_function_budget_builders() {
+        let fb = FunctionBudget {
+            name: "process".to_string(),
+            source: "src/lib.rs".to_string(),
+            energy_budget_mj: Some(50.0),
+            carbon_budget_mg: None,
+        };
+        assert!(fb.energy_budget().is_some());
+        assert!(fb.carbon_budget().is_none());
+    }
+}