diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 77066a8..0000000 --- a/README.adoc +++ /dev/null @@ -1,198 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell - -= Eclexia -:toc: left -:toclevels: 3 -:sectanchors: -:sectnums: - -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/eclexia"] -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] - -Eclexia is an Economics-as-Code programming language. -It treats energy, time, memory, and carbon as first-class constraints so software can optimize for performance and sustainability together. - -== Quick Links - -* link:GETTING_STARTED.md[Getting Started] -* link:QUICK_STATUS.md[Current Implementation Status] -* link:docs/README.md[Documentation Index] -* link:docs/wiki/Home.md[Wiki Home] -* link:SPECIFICATION.md[Language Specification] -* link:WHITEPAPER.md[Whitepaper] -* link:PROOFS.md[Formal Proofs] -* link:IMPLEMENTATION_ROADMAP.md[Implementation Roadmap] -* link:CONTRIBUTING.md[Contributing] -* link:SECURITY.md[Security Policy] - -== What Is Eclexia? - -Eclexia introduces economics directly into language semantics: - -* Resource-aware constraints in code (`@requires`, `@provides`) -* Adaptive solution selection under changing runtime conditions -* Shadow-price-based tradeoff decisions -* Carbon-aware execution and scheduling -* Multi-objective optimization declared at source level - -Example shape of an adaptive function: - -[source,eclexia] ----- -adaptive def matrix_multiply(A: Matrix, B: Matrix) -> Matrix - @requires: energy < 100J, latency < 500ms - @optimize: minimize energy, minimize carbon -{ - @solution "gpu_accelerated": - @when: gpu_available && matrix_size > 1000 - @provides: energy: 50J, latency: 100ms, carbon: 5gCO2e - { - gpu::multiply(A, B) - } - - @solution "parallel_cpu": - @when: cpu_cores >= 4 - @provides: energy: 80J, latency: 300ms, carbon: 8gCO2e - { - parallel::multiply(A, B) - } -} ----- - -== Quick Start - -[source,bash] ----- -# Build from source (Rust 1.75+) -cargo build --release - -# Run tests -cargo test --workspace - -# Run a sample program -cargo run -- run examples/hello.ecl ----- - -Compiler binary: - -[source,text] ----- -target/release/eclexia ----- - -For a fuller walkthrough, use link:GETTING_STARTED.md[GETTING_STARTED.md]. - -== Documentation Index - -[cols="1,3,1",options="header"] -|=== -| Document | Purpose | Audience - -| link:GETTING_STARTED.md[Getting Started] -| Installation, first run, and CLI usage -| New users - -| link:QUICK_STATUS.md[Quick Status] -| Snapshot of what works and what does not -| Users and contributors - -| link:SPECIFICATION.md[Specification] -| Language syntax and semantics -| Language implementers - -| link:WHITEPAPER.md[Whitepaper] -| High-level design and motivation -| General and research audience - -| link:PROOFS.md[Proofs] -| Formal statements and theorem development -| Researchers - -| link:FORMAL_VERIFICATION.md[Formal Verification] -| Coq/Agda proof status and verification notes -| Researchers and maintainers - -| link:IMPLEMENTATION_ROADMAP.md[Implementation Roadmap] -| Medium/long-term engineering roadmap -| Contributors and maintainers - -| link:TOOLCHAIN_STATUS.md[Toolchain Status] -| Status of compiler/runtime/tooling components -| Contributors - -| link:ALGORITHMS.md[Algorithms] -| Algorithmic details and implementation notes -| Contributors and researchers - -| link:BIBLIOGRAPHY.md[Bibliography] -| Research references used by the project -| Researchers -|=== - -== Current Status - -As of link:QUICK_STATUS.md[QUICK_STATUS.md] (updated 2026-02-12): - -* Alpha stage -* Core compiler pipeline functional -* Runtime components available with active development -* Conformance and workspace tests are in regular use - -This repository has many deep-dive documents. The README now stays focused on orientation, while detailed operational and research content lives in dedicated docs and wiki pages. - -== Repository Layout - -[source,text] ----- -eclexia/ -├── README.adoc -├── compiler/ # compiler crates and CLI front-end -├── runtime/ # runtime crates (scheduler, profiling, carbon, shadow) -├── libraries/ # ecosystem libraries -├── stdlib/ # standard library sources -├── examples/ # sample .ecl programs -├── tests/ # conformance and integration tests -├── formal/ # Coq/Agda artifacts -└── docs/ # reference docs, tutorials, and generated docs ----- - -== README vs Wiki - -The README should remain a concise project entry point. -Long-lived narrative and frequently evolving content is better placed in the wiki. - -Recommended wiki destinations: - -* Architecture walkthroughs and subsystem maps -* Backlog triage and milestone notes -* Design discussions and ADR-style rationale -* Research notes and reading guides -* Contributor onboarding playbooks - -Proposed wiki structure and migration map: -link:docs/wiki/README.md[docs/wiki/README.md] - -== Contributing - -* link:CONTRIBUTING.md[Contributing Guide] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:SECURITY.md[Security Policy] - -== License - -Eclexia is licensed under MPL-2.0. -See link:LICENSE[LICENSE] and link:LICENSE.txt[LICENSE.txt]. - -== Contact - -* General: mailto:info@eclexia.org[info@eclexia.org] -* Research: mailto:research@eclexia.org[research@eclexia.org] -* Security: mailto:security@eclexia.org[security@eclexia.org] - -Repository: https://gitlab.com/eclexia-lang/eclexia - -== Mission - -Make resource-efficient, carbon-aware software the default, not the exception. diff --git a/README.md b/README.md new file mode 100644 index 0000000..033457c --- /dev/null +++ b/README.md @@ -0,0 +1,191 @@ + + +[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/eclexia) +[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) + +Eclexia is an Economics-as-Code programming language. It treats energy, +time, memory, and carbon as first-class constraints so software can +optimize for performance and sustainability together. + +# Quick Links + +- [Getting Started](GETTING_STARTED.md) + +- [Current Implementation Status](QUICK_STATUS.md) + +- [Documentation Index](docs/README.md) + +- [Wiki Home](docs/wiki/Home.md) + +- [Language Specification](SPECIFICATION.md) + +- [Whitepaper](WHITEPAPER.md) + +- [Formal Proofs](PROOFS.md) + +- [Implementation Roadmap](IMPLEMENTATION_ROADMAP.md) + +- [Contributing](CONTRIBUTING.md) + +- [Security Policy](SECURITY.md) + +# What Is Eclexia? + +Eclexia introduces economics directly into language semantics: + +- Resource-aware constraints in code (`@requires`, `@provides`) + +- Adaptive solution selection under changing runtime conditions + +- Shadow-price-based tradeoff decisions + +- Carbon-aware execution and scheduling + +- Multi-objective optimization declared at source level + +Example shape of an adaptive function: + +```eclexia +adaptive def matrix_multiply(A: Matrix, B: Matrix) -> Matrix + @requires: energy < 100J, latency < 500ms + @optimize: minimize energy, minimize carbon +{ + @solution "gpu_accelerated": + @when: gpu_available && matrix_size > 1000 + @provides: energy: 50J, latency: 100ms, carbon: 5gCO2e + { + gpu::multiply(A, B) + } + + @solution "parallel_cpu": + @when: cpu_cores >= 4 + @provides: energy: 80J, latency: 300ms, carbon: 8gCO2e + { + parallel::multiply(A, B) + } +} +``` + +# Quick Start + +```bash +# Build from source (Rust 1.75+) +cargo build --release + +# Run tests +cargo test --workspace + +# Run a sample program +cargo run -- run examples/hello.ecl +``` + +Compiler binary: + +```text +target/release/eclexia +``` + +For a fuller walkthrough, use +GETTING_STARTED. + +# Documentation Index + +| Document | Purpose | Audience | +|----|----|----| +| [Getting Started](GETTING_STARTED.md) | Installation, first run, and CLI usage | New users | +| [Quick Status](QUICK_STATUS.md) | Snapshot of what works and what does not | Users and contributors | +| [Specification](SPECIFICATION.md) | Language syntax and semantics | Language implementers | +| [Whitepaper](WHITEPAPER.md) | High-level design and motivation | General and research audience | +| [Proofs](PROOFS.md) | Formal statements and theorem development | Researchers | +| [Formal Verification](FORMAL_VERIFICATION.md) | Coq/Agda proof status and verification notes | Researchers and maintainers | +| [Implementation Roadmap](IMPLEMENTATION_ROADMAP.md) | Medium/long-term engineering roadmap | Contributors and maintainers | +| [Toolchain Status](TOOLCHAIN_STATUS.md) | Status of compiler/runtime/tooling components | Contributors | +| [Algorithms](ALGORITHMS.md) | Algorithmic details and implementation notes | Contributors and researchers | +| [Bibliography](BIBLIOGRAPHY.md) | Research references used by the project | Researchers | + +# Current Status + +As of QUICK_STATUS (updated +2026-02-12): + +- Alpha stage + +- Core compiler pipeline functional + +- Runtime components available with active development + +- Conformance and workspace tests are in regular use + +This repository has many deep-dive documents. The README now stays +focused on orientation, while detailed operational and research content +lives in dedicated docs and wiki pages. + +# Repository Layout + +```text +eclexia/ +├── README.adoc +├── compiler/ # compiler crates and CLI front-end +├── runtime/ # runtime crates (scheduler, profiling, carbon, shadow) +├── libraries/ # ecosystem libraries +├── stdlib/ # standard library sources +├── examples/ # sample .ecl programs +├── tests/ # conformance and integration tests +├── formal/ # Coq/Agda artifacts +└── docs/ # reference docs, tutorials, and generated docs +``` + +# README vs Wiki + +The README should remain a concise project entry point. Long-lived +narrative and frequently evolving content is better placed in the wiki. + +Recommended wiki destinations: + +- Architecture walkthroughs and subsystem maps + +- Backlog triage and milestone notes + +- Design discussions and ADR-style rationale + +- Research notes and reading guides + +- Contributor onboarding playbooks + +Proposed wiki structure and migration map: +[docs/wiki/README.md](docs/wiki/README.md) + +# Contributing + +- [Contributing Guide](CONTRIBUTING.md) + +- [Code of Conduct](CODE_OF_CONDUCT.md) + +- [Security Policy](SECURITY.md) + +# License + +Eclexia is licensed under MPL-2.0. See [LICENSE](LICENSE) and +LICENSE. + +# Contact + +- General: [[info@eclexia.org](info@eclexia.org)](info@eclexia.org) + +- Research: + [[research@eclexia.org](research@eclexia.org)](research@eclexia.org) + +- Security: + [[security@eclexia.org](security@eclexia.org)](security@eclexia.org) + +Repository: + +# Mission + +Make resource-efficient, carbon-aware software the default, not the +exception.