diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index bfa367b..02adbac 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,8 +2,8 @@ git clone https://github.com/hyperpolymath/eclexiaiser.git cd eclexiaiser -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create eclexiaiser-dev @@ -45,7 +45,7 @@ eclexiaiser/ ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md -├── flake.nix # Nix flake — fallback (Perimeter 1) +├── flake.guix # Guix flake — fallback (Perimeter 1) ├── guix.scm # Guix package — primary (Perimeter 1) └── Justfile # Task runner (Perimeter 1) ``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6e2bea9..678e4a4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -33,7 +33,7 @@ ## Banned Languages -- No TypeScript (use ReScript) +- No TypeScript (use AffineScript) - No Node.js / npm / bun (use Deno) - No Go (use Rust) - No Python (use Julia or Rust) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d5cd4e9..045cb8f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -41,8 +41,8 @@ updates: schedule: interval: "weekly" - # Nix flakes - - package-ecosystem: "nix" + # Guix flakes + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/.machine_readable/ai/PLACEHOLDERS.adoc b/.machine_readable/ai/PLACEHOLDERS.adoc index 41134e3..849083e 100644 --- a/.machine_readable/ai/PLACEHOLDERS.adoc +++ b/.machine_readable/ai/PLACEHOLDERS.adoc @@ -48,8 +48,8 @@ sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) | Placeholder | Description | Example | Files | |---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | +| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.guix, devcontainer.json | +| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.guix | | `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/interface/abi/*.idr, src/interface/ffi/*.zig | | `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, src/interface/ffi/*.zig | | `eclexiaiser` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | @@ -133,7 +133,7 @@ After replacing all placeholders, verify none remain: ```bash grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='Justfile' --include='*.guix' --include='*.toml' --include='*.yml' \ --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ --include='*.json' --include='Containerfile' --include='dep5' \ | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' diff --git a/.machine_readable/contractiles/lust/Intentfile.a2ml b/.machine_readable/contractiles/lust/Intentfile.a2ml index f75d38e..53287e5 100644 --- a/.machine_readable/contractiles/lust/Intentfile.a2ml +++ b/.machine_readable/contractiles/lust/Intentfile.a2ml @@ -16,7 +16,7 @@ design philosophy — not current state, but target state. ### reproducible-builds - description: Builds should be bit-for-bit reproducible -- target: Guix + Nix + Containerfile +- target: Guix + Guix + Containerfile - status: aspiration ### zero-dangerous-patterns diff --git a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml index eaee720..698f4d0 100644 --- a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml +++ b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml @@ -67,7 +67,7 @@ compliance-seams-check = true exception-register-required = true exception-bounded-scope-required = true policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad ReScript->TypeScript migration" +example-drift-risk = "single TypeScript exception causing broad AffineScript->TypeScript migration" compliance-tooling = "panic-attack" effects-tooling = "ecological checking with sustainabot guidance" diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..8d55bd6 --- /dev/null +++ b/README.adoc @@ -0,0 +1,121 @@ +== What Is This? + +Eclexiaiser instruments existing code with *energy, carbon, and +resource-cost tracking* — making the environmental cost of computation a +first-class concern. + +https://github.com/hyperpolymath/eclexia[Eclexia] is one of +hyperpolymath’s nextgen languages focused on sustainability. It tracks +resource consumption as a type-level constraint, so developers can write +carbon-aware software that provably stays within energy budgets. +Eclexiaiser brings this to any codebase without requiring the developer +to learn Eclexia directly. + +== How It Works + +[arabic] +. *Manifest* (`+eclexiaiser.toml+`) — define your functions and their +energy budgets, carbon intensity limits, and resource bounds. +. *Source instrumentation* — eclexiaiser analyses your code and inserts +energy measurement hooks at function boundaries. +. *Eclexia annotation codegen* — generates Eclexia constraint files with +joule annotations (`+@requires+` `+energy+` `+<+` `+5kWh+`), carbon +intensity bounds, and renewable-aware scheduling hints. +. *Idris2 ABI proofs* — the generated resource bounds are formally +verified using dependent types. The Idris2 layer proves that your energy +budget is satisfiable and that carbon intensity limits compose correctly +across call chains. +. *Zig FFI bridge* — high-performance energy measurement via RAPL +(Running Average Power Limit), IPMI, or external APIs. Zero-overhead +C-ABI interface for reading hardware energy counters and querying carbon +intensity services. +. *Enforcement and reporting* — violations are caught at compile time +where possible, and at runtime otherwise. Generates sustainability +reports compatible with the EU Corporate Sustainability Reporting +Directive (CSRD). + +== Key Value + +* *Know the carbon cost of every function call* — joule annotations make +energy consumption visible and enforceable at the type level +* *Enforce energy budgets* — set per-function and per-module energy +limits that are checked at compile time via Idris2 dependent type proofs +* *Generate sustainability reports* — produce CSRD-compatible reports +showing energy consumption, carbon emissions, and renewable energy +utilisation +* *Carbon intensity API integration* — connect to WattTime or +Electricity Maps to schedule heavy computation when the grid is cleanest +* *Renewable-aware scheduling* — defer energy-intensive work to periods +of high renewable generation +* *Energy type system* — Eclexia’s `+@requires+`/`+@provides+` +constraints make resource costs explicit and optimisable across the +entire call graph + +== Architecture + +Follows the hyperpolymath -iser pattern: + +.... +eclexiaiser.toml (manifest: functions, budgets, carbon limits) + | + v +Source instrumentation (insert energy measurement hooks) + | + v +Eclexia annotation codegen (@requires energy, @provides carbon_report) + | + v +Idris2 ABI (proves resource bounds compose, budgets are satisfiable) + | + v +Zig FFI (RAPL/IPMI energy measurement, WattTime/Electricity Maps API) + | + v +Sustainability report + enforcement violations +.... + +Part of the https://github.com/hyperpolymath/iseriser[-iser family]. + +=== Key Types (Idris2 ABI) + +* `+EnergyBudget+` — per-function energy limit in joules, proven +satisfiable +* `+CarbonIntensity+` — grams CO2 per kilowatt-hour, sourced from grid +API +* `+JouleAnnotation+` — type-level energy annotation for a function +* `+ResourceBound+` — composite bound (energy + carbon + time + memory) +* `+SustainabilityReport+` — aggregated metrics with CSRD field mapping + +=== Zig FFI Operations + +* `+eclexiaiser_measure_energy+` — read hardware energy counters +(RAPL/IPMI) +* `+eclexiaiser_query_carbon+` — fetch current carbon intensity from +grid API +* `+eclexiaiser_enforce_budget+` — check a measurement against a proven +bound +* `+eclexiaiser_generate_report+` — produce a sustainability report +struct + +== Use Cases + +* *Green computing* — annotate hotspots, set budgets, prove compliance +* *Data centre optimisation* — measure per-function energy, identify +waste +* *Carbon-aware CI/CD* — skip heavy builds when the grid is dirty; +schedule nightly jobs when renewables peak +* *EU CSRD compliance* — generate the energy and emissions data required +by the Corporate Sustainability Reporting Directive +* *Cloud cost prediction* — estimate energy costs before deployment +using the proven energy bounds + +== Status + +*Codebase in progress.* Scaffold complete (CLI, manifest parser, +directory structure, CI/CD). Codegen stubs in place. Idris2 ABI and Zig +FFI templates present — domain-specific types and energy measurement +logic pending. + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md deleted file mode 100644 index 9b4c5e9..0000000 --- a/README.md +++ /dev/null @@ -1,144 +0,0 @@ - - -# What Is This? - -Eclexiaiser instruments existing code with **energy, carbon, and -resource-cost tracking** — making the environmental cost of computation -a first-class concern. - -[Eclexia](https://github.com/hyperpolymath/eclexia) is one of -hyperpolymath’s nextgen languages focused on sustainability. It tracks -resource consumption as a type-level constraint, so developers can write -carbon-aware software that provably stays within energy budgets. -Eclexiaiser brings this to any codebase without requiring the developer -to learn Eclexia directly. - -# How It Works - -1. **Manifest** (`eclexiaiser.toml`) — define your functions and their - energy budgets, carbon intensity limits, and resource bounds. - -2. **Source instrumentation** — eclexiaiser analyses your code and - inserts energy measurement hooks at function boundaries. - -3. **Eclexia annotation codegen** — generates Eclexia constraint files - with joule annotations (`@requires` `energy` `<` `5kWh`), carbon - intensity bounds, and renewable-aware scheduling hints. - -4. **Idris2 ABI proofs** — the generated resource bounds are formally - verified using dependent types. The Idris2 layer proves that your - energy budget is satisfiable and that carbon intensity limits - compose correctly across call chains. - -5. **Zig FFI bridge** — high-performance energy measurement via RAPL - (Running Average Power Limit), IPMI, or external APIs. Zero-overhead - C-ABI interface for reading hardware energy counters and querying - carbon intensity services. - -6. **Enforcement and reporting** — violations are caught at compile - time where possible, and at runtime otherwise. Generates - sustainability reports compatible with the EU Corporate - Sustainability Reporting Directive (CSRD). - -# Key Value - -- **Know the carbon cost of every function call** — joule annotations - make energy consumption visible and enforceable at the type level - -- **Enforce energy budgets** — set per-function and per-module energy - limits that are checked at compile time via Idris2 dependent type - proofs - -- **Generate sustainability reports** — produce CSRD-compatible reports - showing energy consumption, carbon emissions, and renewable energy - utilisation - -- **Carbon intensity API integration** — connect to WattTime or - Electricity Maps to schedule heavy computation when the grid is - cleanest - -- **Renewable-aware scheduling** — defer energy-intensive work to - periods of high renewable generation - -- **Energy type system** — Eclexia’s `@requires`/`@provides` constraints - make resource costs explicit and optimisable across the entire call - graph - -# Architecture - -Follows the hyperpolymath -iser pattern: - - eclexiaiser.toml (manifest: functions, budgets, carbon limits) - | - v - Source instrumentation (insert energy measurement hooks) - | - v - Eclexia annotation codegen (@requires energy, @provides carbon_report) - | - v - Idris2 ABI (proves resource bounds compose, budgets are satisfiable) - | - v - Zig FFI (RAPL/IPMI energy measurement, WattTime/Electricity Maps API) - | - v - Sustainability report + enforcement violations - -Part of the [-iser family](https://github.com/hyperpolymath/iseriser). - -## Key Types (Idris2 ABI) - -- `EnergyBudget` — per-function energy limit in joules, proven - satisfiable - -- `CarbonIntensity` — grams CO2 per kilowatt-hour, sourced from grid API - -- `JouleAnnotation` — type-level energy annotation for a function - -- `ResourceBound` — composite bound (energy + carbon + time + memory) - -- `SustainabilityReport` — aggregated metrics with CSRD field mapping - -## Zig FFI Operations - -- `eclexiaiser_measure_energy` — read hardware energy counters - (RAPL/IPMI) - -- `eclexiaiser_query_carbon` — fetch current carbon intensity from grid - API - -- `eclexiaiser_enforce_budget` — check a measurement against a proven - bound - -- `eclexiaiser_generate_report` — produce a sustainability report struct - -# Use Cases - -- **Green computing** — annotate hotspots, set budgets, prove compliance - -- **Data centre optimisation** — measure per-function energy, identify - waste - -- **Carbon-aware CI/CD** — skip heavy builds when the grid is dirty; - schedule nightly jobs when renewables peak - -- **EU CSRD compliance** — generate the energy and emissions data - required by the Corporate Sustainability Reporting Directive - -- **Cloud cost prediction** — estimate energy costs before deployment - using the proven energy bounds - -# Status - -**Codebase in progress.** Scaffold complete (CLI, manifest parser, -directory structure, CI/CD). Codegen stubs in place. Idris2 ABI and Zig -FFI templates present — domain-specific types and energy measurement -logic pending. - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/ROADMAP.adoc b/ROADMAP.adoc index b645871..5407282 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -16,7 +16,7 @@ == Phase 1: Source Instrumentation * [ ] Parse target source files to identify function boundaries * [ ] Insert energy measurement hooks at function entry/exit -* [ ] Support Rust, ReScript, and Gleam as initial target languages +* [ ] Support Rust, AffineScript, and Gleam as initial target languages * [ ] Preserve source maps for accurate attribution * [ ] CLI `generate` subcommand produces instrumented source diff --git a/SECURITY.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index 5fbf88e..abbac68 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the eclexiaiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..7388be9 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,34 @@ +== TEST-NEEDS.md — eclexiaiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |2 |Location(s): /tests, /verification/tests +|CI workflows |22 |Running tests on GitHub Actions +|Unit tests |Built-in |Rust/cargo test framework +|Integration tests |Configured |Via integration/ directory +|=== + +=== What’s Covered + +* [x] Rust unit test suite (cargo test) +* [x] Documentation tests +* [x] Example programs with tests + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 011b7c7..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ -# TEST-NEEDS.md — eclexiaiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 2 | Location(s): /tests, /verification/tests | -| CI workflows | 22 | Running tests on GitHub Actions | -| Unit tests | Built-in | Rust/cargo test framework | -| Integration tests | Configured | Via integration/ directory | - -## What's Covered - -- [x] Rust unit test suite (cargo test) -- [x] Documentation tests -- [x] Example programs with tests - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 78% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 829a130..c327699 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,16 +1,15 @@ - - -# TOPOLOGY — eclexiaiser +== TOPOLOGY — eclexiaiser -## Purpose +=== Purpose -Energy, carbon, and resource-cost awareness for existing software via Eclexia -economics-as-code. Instruments code with energy measurement hooks, generates -Eclexia constraint annotations, and formally verifies resource bounds. +Energy, carbon, and resource-cost awareness for existing software via +Eclexia economics-as-code. Instruments code with energy measurement +hooks, generates Eclexia constraint annotations, and formally verifies +resource bounds. -## Module Map +=== Module Map -``` +.... eclexiaiser/ ├── src/ │ ├── main.rs # CLI entry point (clap subcommands) @@ -61,11 +60,11 @@ eclexiaiser/ │ ├── configs/ # git-cliff, etc. │ └── anchors/ # ANCHOR.a2ml └── .github/workflows/ # 17 RSR-standard workflows -``` +.... -## Data Flow +=== Data Flow -``` +.... eclexiaiser.toml │ (manifest: function names, energy budgets, carbon limits, grid zone) v @@ -93,26 +92,40 @@ eclexiaiser.toml │ │ Enforcement violations (compile-time or runtime) │ │ Energy dashboard data (PanLL panel) └────────────────────────┘ -``` - -## Key Domain Types - -| Type | Module | Purpose | -|------|--------|---------| -| `EnergyBudget` | Types.idr | Per-function energy limit in joules with satisfiability proof | -| `CarbonIntensity` | Types.idr | gCO2/kWh from grid API, indexed by zone | -| `JouleAnnotation` | Types.idr | Type-level energy annotation for a function | -| `ResourceBound` | Types.idr | Composite bound (energy + carbon + time + memory) | -| `SustainabilityReport` | Types.idr | Aggregated metrics with CSRD field mapping | -| `EnergyMeasurement` | Layout.idr | C-compatible struct for hardware counter readings | -| `CarbonQuery` | Layout.idr | C-compatible struct for carbon API request/response | - -## Integration Points - -- **iseriser** — meta-framework that generated this scaffold -- **proven** — shared Idris2 verification primitives -- **typell** — type theory engine for constraint solving -- **PanLL** — real-time energy dashboard panel -- **BoJ-server** — remote energy analysis cartridge -- **VeriSimDB** — historical energy measurement storage -- **WattTime / Electricity Maps** — external carbon intensity APIs +.... + +=== Key Domain Types + +[width="100%",cols="27%,34%,39%",options="header",] +|=== +|Type |Module |Purpose +|`+EnergyBudget+` |Types.idr |Per-function energy limit in joules with +satisfiability proof + +|`+CarbonIntensity+` |Types.idr |gCO2/kWh from grid API, indexed by zone + +|`+JouleAnnotation+` |Types.idr |Type-level energy annotation for a +function + +|`+ResourceBound+` |Types.idr |Composite bound (energy + carbon + time + +memory) + +|`+SustainabilityReport+` |Types.idr |Aggregated metrics with CSRD field +mapping + +|`+EnergyMeasurement+` |Layout.idr |C-compatible struct for hardware +counter readings + +|`+CarbonQuery+` |Layout.idr |C-compatible struct for carbon API +request/response +|=== + +=== Integration Points + +* *iseriser* — meta-framework that generated this scaffold +* *proven* — shared Idris2 verification primitives +* *typell* — type theory engine for constraint solving +* *PanLL* — real-time energy dashboard panel +* *BoJ-server* — remote energy analysis cartridge +* *VeriSimDB* — historical energy measurement storage +* *WattTime / Electricity Maps* — external carbon intensity APIs diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index 8faf3bb..83e1c15 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -204,8 +204,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript, Gleam -* **Tier 2** (Silver): Nickel, Guile Scheme, Nix, Idris2, OCaml +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript, Gleam +* **Tier 2** (Silver): Nickel, Guile Scheme, Guix, Idris2, OCaml * **Infrastructure**: Guix channels, derivations, Julia batch scripts === Required Files @@ -219,12 +219,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) * npm, Bun, pnpm, yarn (use Deno) diff --git a/docs/STATE-VISUALIZER.adoc b/docs/STATE-VISUALIZER.adoc index 4be8d44..7746b12 100644 --- a/docs/STATE-VISUALIZER.adoc +++ b/docs/STATE-VISUALIZER.adoc @@ -46,7 +46,7 @@ ┌─────────────────────────────────────────┐ │ PLATFORM INTEGRATION │ │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ GitHub │ │ GitLab │ │ Nix / ││ + │ │ GitHub │ │ GitLab │ │ Guix / ││ │ │ Workflows │ │ CI/CD │ │ Guix ││ │ └───────────┘ └───────────┘ └───────┘│ └─────────────────────────────────────────┘ @@ -88,7 +88,7 @@ CONTAINER ECOSYSTEM (Phase 2) REPO INFRASTRUCTURE .machine_readable/ ██████████ 100% STATE/META/ECOSYSTEM active Governance & License ██████████ 100% MPL-2.0 & Ethical use verified - Development Shells (Nix/Guix) ██████████ 100% Reproducible env stable + Development Shells (Guix/Guix) ██████████ 100% Reproducible env stable ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% RSR Template Stable & Certified diff --git a/docs/developer/ABI-FFI-README.adoc b/docs/developer/ABI-FFI-README.adoc index fe01f12..dd5db7a 100644 --- a/docs/developer/ABI-FFI-README.adoc +++ b/docs/developer/ABI-FFI-README.adoc @@ -44,7 +44,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ ``` @@ -76,7 +76,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ ``` diff --git a/docs/governance/MAINTENANCE-CHECKLIST.a2ml b/docs/governance/MAINTENANCE-CHECKLIST.a2ml index eaee720..698f4d0 100644 --- a/docs/governance/MAINTENANCE-CHECKLIST.a2ml +++ b/docs/governance/MAINTENANCE-CHECKLIST.a2ml @@ -67,7 +67,7 @@ compliance-seams-check = true exception-register-required = true exception-bounded-scope-required = true policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad ReScript->TypeScript migration" +example-drift-risk = "single TypeScript exception causing broad AffineScript->TypeScript migration" compliance-tooling = "panic-attack" effects-tooling = "ecological checking with sustainabot guidance" diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc index 58e132b..6a3636b 100644 --- a/docs/practice/AI-CONVENTIONS.adoc +++ b/docs/practice/AI-CONVENTIONS.adoc @@ -53,7 +53,7 @@ MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the reposit | Banned | Use Instead | |---------------------|--------------------| -| TypeScript | ReScript | +| TypeScript | AffineScript | | Node.js / npm / bun | Deno | | Go | Rust | | Python | Julia / Rust | diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..9bdac36 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — eclexiaiser (Developer) + +=== What is eclexiaiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 6bd02cc..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — eclexiaiser (Developer) - -## What is eclexiaiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..c7b1766 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — eclexiaiser (User) + +=== What is eclexiaiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 9449af2..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — eclexiaiser (User) - -## What is eclexiaiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture