diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9f616e0..8d72b43 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,8 +2,8 @@ git clone https://github.com/hyperpolymath/futharkiser.git cd futharkiser -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create futharkiser-dev @@ -45,7 +45,7 @@ futharkiser/ ├── 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 57f0611..e0b4f33 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 | | `futharkiser` | 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 475b2fe..125f175 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..20377ba --- /dev/null +++ b/README.adoc @@ -0,0 +1,158 @@ +== What Is This? + +Futharkiser identifies array-parallel patterns in your code, extracts +them, generates https://futhark-lang.org[Futhark] programs, and compiles +those programs to *GPU kernels* (OpenCL, CUDA, or multicore CPU) — all +without requiring the user to know anything about GPU programming. + +https://futhark-lang.org[Futhark] (by Troels Henriksen et al., DIKU +Copenhagen) is a purely functional array language that compiles to +highly optimised GPU code. It guarantees no data races and achieves +near-hand-tuned performance on parallel array operations. Almost nobody +knows it exists. Futharkiser democratises GPU computing by putting +Futhark behind a simple manifest. + +== How It Works + +Annotate array operations in your code with `+#[futharkise]+` (or +describe them in `+futharkiser.toml+`). Futharkiser then: + +[arabic] +. *Analyses* your source code for parallelisable array patterns +. *Extracts* operations that map to Futhark’s second-order array +combinators (SOACs): `+map+`, `+reduce+`, `+scan+`, `+scatter+`, +`+flatten+`/`+unflatten+` +. *Proves* parallelism safety via the Idris2 ABI layer (no data races, +correct memory layouts, valid GPU buffer descriptors) +. *Generates* Futhark programs with optimal data layouts and memory +transfers +. *Compiles* via `+futhark+` `+opencl+`, `+futhark+` `+cuda+`, +`+futhark+` `+multicore+`, or `+futhark+` `+c+` (sequential, for +debugging) +. *Creates* a Zig FFI bridge so the compiled GPU kernels are callable +from your application with zero ceremony + +== Key Value + +* *GPU computing for everyone* — no CUDA/OpenCL expertise needed +* *10-1000x speedups* on array-heavy workloads, with Futhark’s compiler +performing fusion, tiling, and memory coalescing automatically +* *Automatic memory management* across the CPU/GPU boundary +(host/device/shared memory spaces are tracked by the ABI layer) +* *Safety guarantees* — Futhark is purely functional with no data races; +Idris2 proofs verify the interface contracts at compile time +* *Multiple GPU backends* — OpenCL (widest hardware support), CUDA +(NVIDIA), multicore CPU (no GPU required), sequential C (debugging) + +== Use Cases + +* *Scientific computing* — matrix operations, PDE solvers, linear +algebra +* *Image processing* — convolutions, filters, histograms on pixel arrays +* *Monte Carlo simulation* — massively parallel random sampling +* *Neural network primitives* — custom forward/backward passes on +tensors +* *Financial modelling* — option pricing, risk calculations over large +portfolios +* *Signal processing* — FFT, spectral analysis on array data + +== Architecture + +Follows the hyperpolymath -iser pattern: + +.... +futharkiser.toml User describes WHAT they want + | + v + Source Analysis Identifies map/reduce/scan/scatter patterns + | + v + Idris2 ABI Layer Proves parallelism safety, validates GPU buffer layouts + (src/interface/abi/) Types: SOAC, GPUBackend, ArrayShape, ParallelPattern, MemorySpace + | + v + Futhark Codegen Generates .fut programs with SOACs + (src/codegen/) + | + v + GPU Compilation futhark opencl | futhark cuda | futhark multicore | futhark c + | + v + Zig FFI Bridge C-ABI callable GPU kernels + (src/interface/ffi/) + | + v + Your Application Calls GPU kernels as normal functions +.... + +=== Futhark SOACs (Second-Order Array Combinators) + +Futharkiser maps source patterns to these Futhark primitives: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|SOAC |Description |Example pattern +|`+map+` |Apply function to every element |`+items.iter().map(|x|+` +`+x+` `+*+` `+2)+` + +|`+reduce+` |Fold array with associative operator +|`+items.iter().sum()+` + +|`+scan+` |Inclusive prefix scan |Running totals, prefix sums + +|`+scatter+` |Irregular write to array positions |Histogram binning, +sparse updates + +|`+flatten+`/`+unflatten+` |Reshape nested arrays |Matrix operations, +batch processing +|=== + +=== GPU Backends + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Backend |Use case |Flag +|OpenCL |Widest hardware support (AMD, Intel, NVIDIA) |`+--backend+` +`+opencl+` + +|CUDA |NVIDIA GPUs (best NVIDIA performance) |`+--backend+` `+cuda+` + +|Multicore CPU |No GPU available; still parallel |`+--backend+` +`+multicore+` + +|Sequential C |Debugging, correctness testing |`+--backend+` `+c+` +|=== + +Part of the https://github.com/hyperpolymath/iseriser[-iser family] of +acceleration frameworks. + +== Status + +*Codebase in progress.* Architecture defined, CLI scaffolded, RSR +template complete, Idris2 ABI types stubbed. Futhark codegen and GPU +compilation pipeline are the next milestones. + +== Quick Start + +[source,bash] +---- +# Initialise a manifest in your project +futharkiser init + +# Edit futharkiser.toml to describe your array operations +# Then generate, build, and run: +futharkiser generate +futharkiser build --backend opencl +futharkiser run +---- + +== Building from Source + +[source,bash] +---- +cargo build --release +---- + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md deleted file mode 100644 index b35e6fd..0000000 --- a/README.md +++ /dev/null @@ -1,157 +0,0 @@ - - -# What Is This? - -Futharkiser identifies array-parallel patterns in your code, extracts -them, generates [Futhark](https://futhark-lang.org) programs, and -compiles those programs to **GPU kernels** (OpenCL, CUDA, or multicore -CPU) — all without requiring the user to know anything about GPU -programming. - -[Futhark](https://futhark-lang.org) (by Troels Henriksen et al., DIKU -Copenhagen) is a purely functional array language that compiles to -highly optimised GPU code. It guarantees no data races and achieves -near-hand-tuned performance on parallel array operations. Almost nobody -knows it exists. Futharkiser democratises GPU computing by putting -Futhark behind a simple manifest. - -# How It Works - -Annotate array operations in your code with `#[futharkise]` (or describe -them in `futharkiser.toml`). Futharkiser then: - -1. **Analyses** your source code for parallelisable array patterns - -2. **Extracts** operations that map to Futhark’s second-order array - combinators (SOACs): `map`, `reduce`, `scan`, `scatter`, - `flatten`/`unflatten` - -3. **Proves** parallelism safety via the Idris2 ABI layer (no data - races, correct memory layouts, valid GPU buffer descriptors) - -4. **Generates** Futhark programs with optimal data layouts and memory - transfers - -5. **Compiles** via `futhark` `opencl`, `futhark` `cuda`, `futhark` - `multicore`, or `futhark` `c` (sequential, for debugging) - -6. **Creates** a Zig FFI bridge so the compiled GPU kernels are - callable from your application with zero ceremony - -# Key Value - -- **GPU computing for everyone** — no CUDA/OpenCL expertise needed - -- **10-1000x speedups** on array-heavy workloads, with Futhark’s - compiler performing fusion, tiling, and memory coalescing - automatically - -- **Automatic memory management** across the CPU/GPU boundary - (host/device/shared memory spaces are tracked by the ABI layer) - -- **Safety guarantees** — Futhark is purely functional with no data - races; Idris2 proofs verify the interface contracts at compile time - -- **Multiple GPU backends** — OpenCL (widest hardware support), CUDA - (NVIDIA), multicore CPU (no GPU required), sequential C (debugging) - -# Use Cases - -- **Scientific computing** — matrix operations, PDE solvers, linear - algebra - -- **Image processing** — convolutions, filters, histograms on pixel - arrays - -- **Monte Carlo simulation** — massively parallel random sampling - -- **Neural network primitives** — custom forward/backward passes on - tensors - -- **Financial modelling** — option pricing, risk calculations over large - portfolios - -- **Signal processing** — FFT, spectral analysis on array data - -# Architecture - -Follows the hyperpolymath -iser pattern: - - futharkiser.toml User describes WHAT they want - | - v - Source Analysis Identifies map/reduce/scan/scatter patterns - | - v - Idris2 ABI Layer Proves parallelism safety, validates GPU buffer layouts - (src/interface/abi/) Types: SOAC, GPUBackend, ArrayShape, ParallelPattern, MemorySpace - | - v - Futhark Codegen Generates .fut programs with SOACs - (src/codegen/) - | - v - GPU Compilation futhark opencl | futhark cuda | futhark multicore | futhark c - | - v - Zig FFI Bridge C-ABI callable GPU kernels - (src/interface/ffi/) - | - v - Your Application Calls GPU kernels as normal functions - -## Futhark SOACs (Second-Order Array Combinators) - -Futharkiser maps source patterns to these Futhark primitives: - -| SOAC | Description | Example pattern | -|----|----|----| -| `map` | Apply function to every element | `items.iter().map(|x|` `x` `*` `2)` | -| `reduce` | Fold array with associative operator | `items.iter().sum()` | -| `scan` | Inclusive prefix scan | Running totals, prefix sums | -| `scatter` | Irregular write to array positions | Histogram binning, sparse updates | -| `flatten`/`unflatten` | Reshape nested arrays | Matrix operations, batch processing | - -## GPU Backends - -| Backend | Use case | Flag | -|----|----|----| -| OpenCL | Widest hardware support (AMD, Intel, NVIDIA) | `--backend` `opencl` | -| CUDA | NVIDIA GPUs (best NVIDIA performance) | `--backend` `cuda` | -| Multicore CPU | No GPU available; still parallel | `--backend` `multicore` | -| Sequential C | Debugging, correctness testing | `--backend` `c` | - -Part of the [-iser family](https://github.com/hyperpolymath/iseriser) of -acceleration frameworks. - -# Status - -**Codebase in progress.** Architecture defined, CLI scaffolded, RSR -template complete, Idris2 ABI types stubbed. Futhark codegen and GPU -compilation pipeline are the next milestones. - -# Quick Start - -```bash -# Initialise a manifest in your project -futharkiser init - -# Edit futharkiser.toml to describe your array operations -# Then generate, build, and run: -futharkiser generate -futharkiser build --backend opencl -futharkiser run -``` - -# Building from Source - -```bash -cargo build --release -``` - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/SECURITY.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index a21454f..1f8d1d2 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 futharkiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..01045ea --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — futharkiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |2 |Current state +|=== + +=== What’s Covered + +* [x] 2 existing test file(s) +* [x] Rust integration tests + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +cargo test --all +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 451beb1..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# TEST-NEEDS.md — futharkiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 2 | Current state | - -## What's Covered - -- [x] 2 existing test file(s) -- [x] Rust integration tests - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -cargo test --all -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 67% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 9c98b48..f19928f 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,20 @@ - - -# TOPOLOGY.md — futharkiser +== TOPOLOGY.md — futharkiser -## Purpose +=== Purpose -futharkiser compiles annotated array operation descriptions to GPU kernels via Futhark. Futhark (Troels Henriksen, DIKU Copenhagen) is a purely functional array language that compiles to OpenCL or CUDA with guaranteed data-race freedom. futharkiser reads kernel descriptions from a `futharkiser.toml` manifest and generates idiomatic Futhark programs using SOACs (second-order array combinators), which are then compiled to the selected GPU backend. It targets engineers who want GPU acceleration with formal data-race guarantees without writing Futhark or GPU code directly. +futharkiser compiles annotated array operation descriptions to GPU +kernels via Futhark. Futhark (Troels Henriksen, DIKU Copenhagen) is a +purely functional array language that compiles to OpenCL or CUDA with +guaranteed data-race freedom. futharkiser reads kernel descriptions from +a `+futharkiser.toml+` manifest and generates idiomatic Futhark programs +using SOACs (second-order array combinators), which are then compiled to +the selected GPU backend. It targets engineers who want GPU acceleration +with formal data-race guarantees without writing Futhark or GPU code +directly. -## Module Map +=== Module Map -``` +.... futharkiser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, build, run, info @@ -20,11 +26,11 @@ futharkiser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... futharkiser.toml manifest │ ┌────▼────┐ @@ -43,4 +49,4 @@ futharkiser.toml manifest ┌────▼────┐ │ Futhark │ compile to OpenCL/CUDA GPU kernels └─────────┘ -``` +.... 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/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 61% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index cf5d751..223f234 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,16 +1,15 @@ - - -# Futharkiser — Topology +== Futharkiser — Topology -## Overview +=== Overview -Futharkiser compiles annotated array operations to GPU kernels via Futhark. -It follows the hyperpolymath -iser pattern: manifest → source analysis → Idris2 -ABI (formal proofs) → Futhark codegen → GPU compilation → Zig FFI bridge. +Futharkiser compiles annotated array operations to GPU kernels via +Futhark. It follows the hyperpolymath -iser pattern: manifest → source +analysis → Idris2 ABI (formal proofs) → Futhark codegen → GPU +compilation → Zig FFI bridge. -## Data Flow +=== Data Flow -``` +.... User Source Code futharkiser.toml manifest │ │ └──────────┬─────────────────────┘ @@ -51,37 +50,67 @@ User Source Code futharkiser.toml manifest │ ▼ Host Application calls GPU kernels as normal functions -``` +.... -## Module Map +=== Module Map -| Module | Language | Location | Purpose | -|--------|----------|----------|---------| -| CLI | Rust | `src/main.rs` | Subcommands: init, validate, generate, build, run, info | -| Library API | Rust | `src/lib.rs` | Programmatic access to manifest + codegen | -| Manifest | Rust | `src/manifest/mod.rs` | Parse and validate `futharkiser.toml` | -| Codegen | Rust | `src/codegen/mod.rs` | Generate Futhark `.fut` files from patterns | -| ABI Types | Idris2 | `src/interface/abi/Types.idr` | SOAC, GPUBackend, ArrayShape, MemorySpace, ParallelPattern, FutharkType, GPUBuffer | -| ABI Layout | Idris2 | `src/interface/abi/Layout.idr` | GPU buffer descriptor layout proofs, struct alignment | -| ABI Foreign | Idris2 | `src/interface/abi/Foreign.idr` | FFI declarations: compile, execute, alloc_buffer, transfer | -| FFI Impl | Zig | `src/interface/ffi/src/main.zig` | C-ABI implementation: GPU context, buffer management | -| FFI Build | Zig | `src/interface/ffi/build.zig` | Build config for libfutharkiser shared/static library | -| FFI Tests | Zig | `src/interface/ffi/test/integration_test.zig` | Integration tests for FFI ↔ ABI contract | +[width="100%",cols="22%,27%,27%,24%",options="header",] +|=== +|Module |Language |Location |Purpose +|CLI |Rust |`+src/main.rs+` |Subcommands: init, validate, generate, +build, run, info -## Key Type Correspondence +|Library API |Rust |`+src/lib.rs+` |Programmatic access to manifest + +codegen -The following types MUST match between the Idris2 ABI and Zig FFI layers: +|Manifest |Rust |`+src/manifest/mod.rs+` |Parse and validate +`+futharkiser.toml+` -| Concept | Idris2 (Types.idr) | Zig (main.zig) | C value | -|---------|--------------------|-----------------|---------| -| Result codes | `Result` enum | `Result` enum(c_int) | 0-7 | -| GPU backend | `GPUBackend` | `GPUBackend` enum(u32) | 0=OpenCL, 1=CUDA, 2=Multicore, 3=Sequential | -| Memory space | `MemorySpace` | `MemorySpace` enum(u32) | 0=Device, 1=Host, 2=Shared | -| Buffer descriptor | `gpuBufferDescriptorLayout` | `GPUBufferDescriptor` extern struct | 32 bytes, 8-byte aligned | +|Codegen |Rust |`+src/codegen/mod.rs+` |Generate Futhark `+.fut+` files +from patterns -## GPU Memory Model +|ABI Types |Idris2 |`+src/interface/abi/Types.idr+` |SOAC, GPUBackend, +ArrayShape, MemorySpace, ParallelPattern, FutharkType, GPUBuffer -``` +|ABI Layout |Idris2 |`+src/interface/abi/Layout.idr+` |GPU buffer +descriptor layout proofs, struct alignment + +|ABI Foreign |Idris2 |`+src/interface/abi/Foreign.idr+` |FFI +declarations: compile, execute, alloc_buffer, transfer + +|FFI Impl |Zig |`+src/interface/ffi/src/main.zig+` |C-ABI +implementation: GPU context, buffer management + +|FFI Build |Zig |`+src/interface/ffi/build.zig+` |Build config for +libfutharkiser shared/static library + +|FFI Tests |Zig |`+src/interface/ffi/test/integration_test.zig+` +|Integration tests for FFI ↔ ABI contract +|=== + +=== Key Type Correspondence + +The following types MUST match between the Idris2 ABI and Zig FFI +layers: + +[width="100%",cols="18%,36%,30%,16%",options="header",] +|=== +|Concept |Idris2 (Types.idr) |Zig (main.zig) |C value +|Result codes |`+Result+` enum |`+Result+` enum(c_int) |0-7 + +|GPU backend |`+GPUBackend+` |`+GPUBackend+` enum(u32) |0=OpenCL, +1=CUDA, 2=Multicore, 3=Sequential + +|Memory space |`+MemorySpace+` |`+MemorySpace+` enum(u32) |0=Device, +1=Host, 2=Shared + +|Buffer descriptor |`+gpuBufferDescriptorLayout+` +|`+GPUBufferDescriptor+` extern struct |32 bytes, 8-byte aligned +|=== + +=== GPU Memory Model + +.... ┌─────────────────────────────────────────┐ │ Host (CPU) Memory │ │ MemorySpace.Host │ @@ -105,13 +134,19 @@ The following types MUST match between the Idris2 ABI and Zig FFI layers: │ - Slower than Device for kernel access │ │ - No explicit transfer needed │ └─────────────────────────────────────────┘ -``` +.... + +=== External Dependencies + +[width="100%",cols="38%,31%,31%",options="header",] +|=== +|Dependency |Version |Purpose +|Futhark |latest |GPU array language compiler (generates OpenCL/CUDA C +code) + +|Zig |0.13+ |FFI bridge compilation -## External Dependencies +|Idris2 |0.7+ |ABI formal proofs -| Dependency | Version | Purpose | -|-----------|---------|---------| -| Futhark | latest | GPU array language compiler (generates OpenCL/CUDA C code) | -| Zig | 0.13+ | FFI bridge compilation | -| Idris2 | 0.7+ | ABI formal proofs | -| Rust | 2024 edition | CLI and orchestration | +|Rust |2024 edition |CLI and orchestration +|=== 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..c839960 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — futharkiser (Developer) + +=== What is futharkiser? + +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 54f24f2..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — futharkiser (Developer) - -## What is futharkiser? -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..acd3b1a --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — futharkiser (User) + +=== What is futharkiser? + +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 b085cb3..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — futharkiser (User) - -## What is futharkiser? -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