P1: implement real Zig FFI matching the Idris2 ABI (#30)

## Problem

The Idris2 ABI is the source of truth for this `-iser` project. Its
`%foreign "C:eclexiaiser_*"` declarations live in **two** places:

- `src/interface/abi/Eclexiaiser/ABI/Foreign.idr` — 18 symbols
- the `namespace Foreign` block inside
`src/interface/abi/Eclexiaiser/ABI/Types.idr` — **3 more symbols**:
`eclexiaiser_measure_energy`, `eclexiaiser_query_carbon`,
`eclexiaiser_enforce_budget`

The Zig FFI (`src/interface/ffi/src/main.zig`) exported the 18 from
`Foreign.idr` but was **missing all 3** declared in `Types.idr`. Those
symbols have no matching `export fn`, so they would fail to link when
the ABI is compiled against `libeclexiaiser`. The Zig FFI therefore did
not fully match its ABI.

## Fix

Added the three missing C-ABI exports, with C signatures matching their
`%foreign` types exactly (Idris `Bits64`/`Bits32` ↔ Zig `u64`/`u32`;
opaque handle ↔ `?*anyopaque`; result `Bits32` ↔ the `Result` enum):

| Idris `%foreign` (Types.idr `namespace Foreign`) | Zig export |
| --- | --- |
| `eclexiaiser_measure_energy : Bits64 -> PrimIO Bits64` |
`eclexiaiser_measure_energy(handle) u64` |
| `eclexiaiser_query_carbon : Bits32 -> PrimIO Bits32` |
`eclexiaiser_query_carbon(zone_id: u32) u32` (handle-free) |
| `eclexiaiser_enforce_budget : Bits64 -> Bits64 -> PrimIO Bits32` |
`eclexiaiser_enforce_budget(budget_uj, measured_uj: u64) Result`
(handle-free) |

The handle-free forms mirror the safe wrappers `measureEnergy` /
`queryCarbon` / `enforceBudget` in the `Types.idr` `namespace Foreign`
block. `eclexiaiser_enforce_budget` returns the `Result` enum, whose
values already equal `Types.idr` `resultToInt` (`Ok=0 ..
CounterUnavailable=7`).

Three `test` blocks were added covering the new symbols:
`measure_energy` main path + null-handle rejection, handle-free
`query_carbon`, and `enforce_budget` result codes (ok /
budget_exceeded).

Only `src/interface/ffi/` is touched.

## Verification

- `zig test src/main.zig -lc` → **11/11 pass**, no errors/warnings
- `idris2 --build eclexiaiser-abi.ipkg` → **exit 0**, clean (build dir
removed afterward)
- All **21** `C:eclexiaiser_*` ABI symbols now have a matching `export
fn`
- `Result` enum values equal `resultToInt`

## CI note

Any rust-ci / Hypatia / governance reds are pre-existing estate-infra
checks unrelated to this Zig-only change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_019xMKB3T4Vo5FYC7Czx3JSH

---
_Generated by [Claude
Code](https://claude.ai/code/session_019xMKB3T4Vo5FYC7Czx3JSH)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

src/interface/ffi/src/main.zig

@@ -247,6 +247,28 @@ export fn eclexiaiser_read_power_mw(raw_handle: ?*anyopaque) u64 {
     return estimatePowerMw();
 }
 
+/// Measure energy consumption for a handle, in microjoules.
+/// Matches the ABI declaration in Types.idr (namespace Foreign):
+///   %foreign "C:eclexiaiser_measure_energy"  : Bits64 -> PrimIO Bits64
+/// Returns the current counter reading (uJ), or 0 if no counter is available
+/// or the handle is null.
+export fn eclexiaiser_measure_energy(raw_handle: ?*anyopaque) u64 {
+    const handle = getHandle(raw_handle) orelse return 0;
+
+    if (!handle.initialized) {
+        setError("Handle not initialized");
+        return 0;
+    }
+
+    const reading = readEnergyCounter(handle.counter_type) orelse {
+        setError("Energy counter not available");
+        return 0;
+    };
+
+    clearError();
+    return reading;
+}
+
 //==============================================================================
 // Carbon Intensity API
 //==============================================================================
@@ -280,6 +302,14 @@ export fn eclexiaiser_query_renewable_pct(raw_handle: ?*anyopaque, zone_id: u32)
     return getStaticRenewablePct(zone_id);
 }
 
+/// Query carbon intensity for a grid zone without a library handle.
+/// Matches the ABI declaration in Types.idr (namespace Foreign):
+///   %foreign "C:eclexiaiser_query_carbon"  : Bits32 -> PrimIO Bits32
+/// Returns milligrams CO2 per kWh from the static dataset.
+export fn eclexiaiser_query_carbon(zone_id: u32) u32 {
+    return getStaticCarbonIntensity(zone_id);
+}
+
 /// Set the carbon API provider.
 export fn eclexiaiser_set_carbon_api(raw_handle: ?*anyopaque, api_source: u32) Result {
     const handle = getHandle(raw_handle) orelse return .null_pointer;
@@ -317,6 +347,19 @@ export fn eclexiaiser_enforce_energy_budget(raw_handle: ?*anyopaque, budget_uj:
     return .ok;
 }
 
+/// Enforce an energy budget without a library handle.
+/// Matches the ABI declaration in Types.idr (namespace Foreign):
+///   %foreign "C:eclexiaiser_enforce_budget"  : Bits64 -> Bits64 -> PrimIO Bits32
+/// Returns .ok (0) if within budget, .budget_exceeded (5) otherwise.
+export fn eclexiaiser_enforce_budget(budget_uj: u64, measured_uj: u64) Result {
+    if (measured_uj > budget_uj) {
+        setError("Energy budget exceeded");
+        return .budget_exceeded;
+    }
+    clearError();
+    return .ok;
+}
+
 /// Enforce a carbon limit against a measurement.
 export fn eclexiaiser_enforce_carbon_limit(raw_handle: ?*anyopaque, limit_mg_co2: u64, measured_mg_co2: u64) Result {
     const handle = getHandle(raw_handle) orelse return .null_pointer;
@@ -639,3 +682,23 @@ test "struct layout sizes" {
     try std.testing.expectEqual(@as(usize, 40), @sizeOf(BudgetEnforcement));
     try std.testing.expectEqual(@as(usize, 40), @sizeOf(SustainabilityReport));
 }
+
+test "Types.idr Foreign: measure_energy and null handle" {
+    // Null handle must yield 0 (not a crash).
+    try std.testing.expectEqual(@as(u64, 0), eclexiaiser_measure_energy(null));
+
+    const raw_handle = eclexiaiser_init() orelse return error.InitFailed;
+    defer eclexiaiser_free(raw_handle);
+    // Estimate counter is always available, so a reading is produced.
+    try std.testing.expect(eclexiaiser_measure_energy(raw_handle) > 0);
+}
+
+test "Types.idr Foreign: query_carbon (handle-free)" {
+    try std.testing.expectEqual(@as(u32, 200_000), eclexiaiser_query_carbon(0x4742)); // GB
+    try std.testing.expectEqual(@as(u32, 20_000), eclexiaiser_query_carbon(0x4E4F)); // NO
+}
+
+test "Types.idr Foreign: enforce_budget (handle-free) result codes" {
+    try std.testing.expectEqual(Result.ok, eclexiaiser_enforce_budget(1000, 500));
+    try std.testing.expectEqual(Result.budget_exceeded, eclexiaiser_enforce_budget(500, 1000));
+}