docs: bespoke architecture, roadmap, topology, and ABI definitions for eclexiaiser

Replace template placeholders with eclexiaiser-specific content across all
documentation and interface files:

- README.adoc: full description of energy/carbon instrumentation pipeline,
  Eclexia annotation codegen, use cases (CSRD, data centres, carbon-aware CI)
- ROADMAP.adoc: 7-phase roadmap from scaffold through CSRD reporting
- TOPOLOGY.md: module map, data flow diagram, domain type reference
- Idris2 ABI: EnergyBudget, CarbonIntensity, JouleAnnotation, ResourceBound,
  SustainabilityReport types with composition and satisfiability proofs;
  energy measurement struct layouts (32/24/40 byte C-compatible)
- Zig FFI: RAPL/IPMI energy counter framework, WattTime/Electricity Maps
  carbon API stubs, budget enforcement, report generation, static fallback
  data for 6 grid zones
- Integration tests: budget enforcement, carbon intensity queries, reporting
- Machine-readable: bespoke STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
- AI manifest: eclexiaiser identity, domain invariants (microjoule units)

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

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for eclexiaiser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -18,10 +18,19 @@ can-create-files = true
 [agent-constraints]
 # What AI agents must NOT do:
 # - Never use banned language patterns (believe_me, unsafeCoerce, etc.)
-# - Never commit secrets or credentials
+# - Never commit secrets or credentials (especially API keys for WattTime/Electricity Maps)
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never use floating-point at the FFI boundary (microjoules and mg CO2/kWh are integers)
+# - Never hardcode carbon intensity values in Idris2 ABI (use Zig FFI for runtime data)
+
+[domain-rules]
+# Energy units: microjoules (uJ) at ABI boundary
+# Carbon units: milligrams CO2 per kWh at ABI boundary
+# Time units: microseconds (us) at ABI boundary
+# Memory units: bytes at ABI boundary
+# Renewable percentage: basis points (0-10000 = 0.00%-100.00%)
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,18 +6,22 @@
   (version "0.1.0")
   (name "eclexiaiser")
   (type "tool")
-  (purpose "Add energy/carbon/resource-cost awareness via Eclexia")
+  (purpose "Add energy, carbon, and resource-cost awareness to existing software via Eclexia economics-as-code")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
+    (domain "sustainability, green computing, carbon-aware software")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
     (project "iseriser"
       (relationship "meta-framework")
       (description "Generates new -iser project scaffolding"))
+    (project "eclexia"
+      (relationship "target-language")
+      (description "Economics-as-code language with @requires/@provides resource constraints"))
     (project "typedqliser"
       (relationship "sibling-priority-1")
       (description "Formal type safety for any query language"))
@@ -27,12 +31,18 @@
     (project "verisimiser"
       (relationship "sibling-priority-3")
       (description "VeriSimDB octad database augmentation"))
-    (project "squeakwell"
-      (relationship "sibling")
-      (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — resource bound proofs will use proven primitives"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine — used for constraint solving on resource bounds"))
+    (project "panll"
+      (relationship "consumer")
+      (description "Panel system — eclexiaiser provides real-time energy dashboard panel"))
+    (project "boj-server"
+      (relationship "consumer")
+      (description "BoJ cartridge for remote energy analysis"))
+    (project "verisimdb"
+      (relationship "consumer")
+      (description "Historical energy measurement storage"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,58 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
     (adr "001-iser-pattern"
       (status "accepted")
-      (context "Need to make powerful languages accessible without steep learning curves")
-      (decision "Use manifest-driven code generation: user describes WHAT, tool generates HOW")
-      (consequences "Users write zero target language code; all complexity in the -iser"))
+      (context "Need to make Eclexia sustainability features accessible without learning a new language")
+      (decision "Use manifest-driven code generation: user describes energy budgets in TOML, tool generates Eclexia constraints and measurement hooks")
+      (consequences "Users write zero Eclexia code; all complexity in eclexiaiser"))
 
     (adr "002-abi-ffi-standard"
       (status "accepted")
-      (context "Need verified interop between Rust CLI, target language, and user code")
-      (decision "Idris2 ABI for formal proofs, Zig FFI for C-ABI bridge")
-      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
+      (context "Need verified interop between Rust CLI, energy measurement hardware, and carbon APIs")
+      (decision "Idris2 ABI for formal proofs of resource bounds, Zig FFI for hardware counter access and C-ABI bridge")
+      (consequences "Compile-time correctness guarantees for energy budgets; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (adr "003-microjoule-units"
+      (status "accepted")
+      (context "Floating-point energy values cause rounding errors that compound across call chains")
+      (decision "Use microjoules (uJ) as the canonical unit at the ABI boundary; milligrams CO2/kWh for carbon")
+      (consequences "Integer arithmetic throughout the measurement and enforcement path; no floating-point at FFI boundary"))
+
+    (adr "004-carbon-api-providers"
+      (status "accepted")
+      (context "Need real-time carbon intensity data for renewable-aware scheduling")
+      (decision "Support WattTime, Electricity Maps, and static data as carbon API providers; configurable per zone in manifest")
+      (consequences "Caching layer needed to avoid API rate limits; static fallback for offline/CI use"))
+
+    (adr "005-csrd-reporting"
+      (status "accepted")
+      (context "EU Corporate Sustainability Reporting Directive requires energy and emissions data from software operations")
+      (decision "Generate sustainability reports with CSRD-compatible field mapping from accumulated measurements")
+      (consequences "Report struct must include: total energy, total carbon, renewable percentage, measurement count"))
+
+    (adr "006-rsr-template"
       (status "accepted")
       (context "Need consistent project structure across 29+ -iser repos")
       (decision "All repos cloned from rsr-template-repo with full CI/CD and governance")
       (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one")))
 
   (development-practices
-    (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
+    (language "Rust" (purpose "CLI orchestration, manifest parsing, codegen"))
+    (language "Idris2" (purpose "ABI formal proofs of energy budget satisfiability and composition"))
+    (language "Zig" (purpose "FFI C-ABI bridge for RAPL/IPMI energy counters and carbon API"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
     (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
-    (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
-    (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+      (explanation "User describes energy budgets and carbon limits in eclexiaiser.toml; tool generates all measurement and enforcement code"))
+    (principle "Formally verified resource bounds"
+      (explanation "Idris2 dependent types prove energy budgets compose correctly across call chains and are satisfiable"))
+    (principle "Hardware-level measurement"
+      (explanation "Zig FFI reads RAPL/IPMI hardware counters for accurate energy data; software estimation as fallback"))
+    (principle "Carbon-aware by default"
+      (explanation "Every energy measurement is paired with grid carbon intensity data, enabling renewable-aware scheduling"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,26 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for eclexiaiser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
+# Custom symbolic rules for eclexiaiser
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "no-float-at-boundary", pattern = "Double.*foreign|foreign.*Double", severity = "warning" }
+# - { name = "energy-unit-consistency", pattern = "joules(?!.*micro)", severity = "info" }
 
 [neural-config]
 # Neural pattern detection settings
 # confidence-threshold = 0.85
 # model = "hypatia-v2"
+# domain-hints = ["energy-measurement", "carbon-tracking", "sustainability-reporting"]

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,30 +1,33 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for eclexiaiser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "ci-triggered"
+target = "binary"  # Rust CLI binary + Zig shared library
+# Secondary targets: container (for CI/CD integration), library (for embedding)
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
 # 3. Run `just validate` to check compliance
 # 4. Run `just security` to audit for vulnerabilities
+# 5. Check energy measurement accuracy: compare RAPL vs IPMI vs estimates
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Justfile
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
-# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
-# 4. Tag and push
-# 5. Restore local permissions if needed: `just perms-restore`
-# 6. Run `just container-push` if applicable
+# 3. Verify Zig FFI struct sizes match Idris2 ABI Layout.idr
+# 4. Run `zig build test` in src/interface/ffi/
+# 5. Run `cargo test` for Rust CLI
+# 6. Tag and push
+# 7. Run `just container-push` if applicable
 
 [maintenance-operations]
 # Baseline audit:
@@ -33,3 +36,5 @@ last-updated = "{{CURRENT_DATE}}"
 #   just maint-hard-pass
 # Permission audit:
 #   just perms-audit
+# ABI compliance check:
+#   Compare struct sizes in Zig tests vs Idris2 Layout.idr comments

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,34 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "eclexiaiser")
-    (description "Add energy/carbon/resource-cost awareness via Eclexia")
-    (status "scaffold")
+    (description "Add energy, carbon, and resource-cost awareness to existing software via Eclexia economics-as-code")
+    (status "scaffold — architecture defined, bespoke ABI types in place")
     (priority "—")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "scaffold-complete")
+    (completion-percentage 15)
+    (milestone "Bespoke Idris2 ABI types (EnergyBudget, CarbonIntensity, JouleAnnotation, ResourceBound, SustainabilityReport), Zig FFI with energy measurement stubs, budget enforcement, and carbon API framework"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "Implement source instrumentation for Rust/ReScript/Gleam targets")
+    (step 2 "Generate Eclexia annotation files from manifest budgets")
+    (step 3 "Implement RAPL energy counter reading in Zig FFI")
+    (step 4 "Integrate WattTime and Electricity Maps carbon APIs")
+    (step 5 "Complete Idris2 proofs of resource bound composition and satisfiability")
+    (step 6 "Generate CSRD-compatible sustainability reports")
+    (step 7 "Integration tests with real energy measurements"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in scaffold phase — no blockers yet. RAPL access requires kernel permissions (powercap sysfs)."))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement source instrumentation for function boundary detection")
+    (action "Implement RAPL energy counter reading in Zig FFI")
+    (action "Write first working example: annotate a Rust function with energy budget, measure, enforce")))