diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7b83a01..24e0aa6 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,8 +2,8 @@ git clone https://github.com/hyperpolymath/bqniser.git cd bqniser -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create bqniser-dev @@ -45,7 +45,7 @@ bqniser/ ├── 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 dd60ed5..9066ed9 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 | | `bqniser` | 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..713b9e8 --- /dev/null +++ b/README.adoc @@ -0,0 +1,159 @@ +https://github.com/sponsors/hyperpolymath[image:https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github[Sponsor]] + +== What Is This? + +*BQNiser* scans your existing code for array computation +patterns — loops, maps, folds, reductions, comprehensions — and rewrites +them as optimised https://mlochbaum.github.io/BQN/[BQN] array +primitives. + +BQN (by Marshall Lochbaum) is an array language descended from APL/J/K. +It brings first-class functions, trains (`+∘+` `+○+` `+⊸+` `+⟜+`), +under/structural-under combinators (`+⌾+`), rank polymorphism, and +leading-axis theory to array processing. BQNiser lets you harness +10-100x speedups on array-heavy workloads *without learning BQN +yourself*. + +Where your Python loop takes 200ms to filter-then-reduce a million-row +column, a single BQN expression using `+/+` (replicate), `+⌽+` +(reverse), or `+⍋+` (grade-up) completes in under 2ms via +https://github.com/dzaima/CBQN[CBQN]’s vectorised runtime. + +== How It Works + +BQNiser follows the https://github.com/hyperpolymath/iseriser[-iser +pattern]: you describe *what* you want; the tool generates *everything*. + +[arabic] +. *Manifest* (`+bqniser.toml+`) — describe your workload, entry points, +data shapes +. *Source Analysis* — AST-based detection of array patterns in Rust, +Python, or Julia source +. *Pattern Matching* — map detected patterns to BQN primitives: +* Nested loops over arrays → `+¨+` (each), `+⌜+` (table) +* Accumulate/reduce → `+´+` (fold), `+\'+` (scan) +* Filter → `+/+` (replicate) with boolean mask +* Sort/rank → `+⍋+` (grade-up), `+⍒+` (grade-down) +* Reshape/transpose → `+⥊+` (reshape), `+⍉+` (transpose) +* Concatenation → `+∾+` (join) +* Index selection → `+⊏+` (select) +* Reversal → `+⌽+` (reverse), `+⌾+` (under) for structural transforms +. *Idris2 ABI* (`+src/interface/abi/+`) — formal proofs that each +rewrite preserves input-output equivalence (dependent types guarantee +correctness) +. *BQN Codegen* — emit optimised BQN source using trains and tacit style +. *CBQN FFI Bridge* (`+src/interface/ffi/+`) — Zig-based C-ABI bridge to +the https://github.com/dzaima/CBQN[CBQN] runtime, so generated BQN runs +in-process with zero serialisation overhead + +== Key Value + +* *10-100x on array operations* — vectorised BQN primitives beat scalar +loops +* *Automatic pattern detection* — finds optimisable code via AST +analysis +* *Equivalence proofs* — Idris2 dependent types prove rewrites preserve +semantics +* *Gradual adoption* — replace hot loops one at a time, keep the rest +untouched +* *Zero BQN knowledge required* — the tool generates all BQN and FFI +code +* *Rank polymorphism* — BQN’s leading-axis theory means primitives +generalise across any number of dimensions automatically + +== BQN Primitives Reference + +BQNiser targets these core primitives and combinators: + +[cols=",,",options="header",] +|=== +|Glyph |Name |Detected Pattern +|`+∾+` |Join |`+concat+`, `+append+`, `+extend+` +|`+⌽+` |Reverse |`+reversed()+`, `+[::-1]+` +|`+⍋+` |Grade Up |`+sorted()+`, `+argsort+` +|`+⍒+` |Grade Down |`+sorted(reverse=True)+` +|`+/+` |Replicate |`+filter+`, boolean indexing +|`+⊏+` |Select |`+arr[indices]+`, `+take+`, `+gather+` +|`+⥊+` |Reshape |`+reshape+`, `+flatten+`, `+ravel+` +|`+⍉+` |Transpose |`+transpose+`, `+T+`, axis permutation +|`+¨+` |Each |`+map+`, list comprehension +|`+⌜+` |Table |nested `+map+`, outer product +|`+´+` |Fold |`+reduce+`, `+foldl+`, `+inject+` +|`+\'+` |Scan |`+accumulate+`, `+scanl+`, prefix sums +|`+⌾+` |Under |structural transforms, lens-like updates +|`+∘○⊸⟜+` |Trains |function composition, tacit pipelines +|=== + +== Architecture + +.... + bqniser.toml src/interface/abi/ src/interface/ffi/ + ┌──────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Manifest │──parse──→│ Idris2 ABI │──gen──→│ Zig FFI │ + │ (TOML) │ │ (Types, Layout, │ │ (CBQN embedding │ + └──────────┘ │ Foreign) │ │ C-ABI bridge) │ + │ └────────┬────────┘ └────────┬────────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Rust CLI │──scan──→ │ Pattern Matcher │──emit─→│ BQN Codegen │ + │ (clap) │ │ (AST → BQN map)│ │ (.bqn files) │ + └──────────┘ └─────────────────┘ └─────────────────┘ +.... + +* *Rust CLI* — parses manifest, invokes AST analysis, orchestrates +generation +* *Pattern Matcher* — maps source-level patterns to BQN primitive +candidates +* *Idris2 ABI* — proves BQN value layout (array header + shape vector + +data cells), proves rewrite equivalence for each transformation +* *BQN Codegen* — emits idiomatic BQN using trains, under, and tacit +definitions +* *Zig FFI* — bridges CBQN’s C API (`+BQN_NewEval+`, `+BQN_Call+`, value +accessors), handles BQN value lifecycle and memory management + +Part of the https://github.com/hyperpolymath/iseriser[-iser family] of +acceleration frameworks. + +== Use Cases + +* *Data processing pipelines* — ETL stages with heavy filtering, +sorting, reshaping +* *Scientific computing* — matrix operations, statistical reductions, +signal processing +* *Financial analytics* — rolling windows, aggregations, time-series +transforms +* *Compiler/transpiler backends* — batch AST transformations as array +operations +* *ETL optimisation* — replace row-by-row processing with bulk array +primitives + +== Quick Start + +[source,bash] +---- +# Initialise a manifest +bqniser init + +# Edit bqniser.toml to describe your workload +# (see examples/ for patterns) + +# Generate BQN + FFI artifacts +bqniser generate + +# Build everything +bqniser build + +# Run +bqniser run +---- + +== Status + +*Codebase in progress.* Architecture defined, CLI scaffolded, Idris2 ABI +types and Zig FFI bridge stubbed. Pattern detection engine and BQN +codegen are the active development frontier. + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md deleted file mode 100644 index 2d92b71..0000000 --- a/README.md +++ /dev/null @@ -1,187 +0,0 @@ - - -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) - -# What Is This? - -**BQNiser** scans your existing code for array computation -patterns — loops, maps, folds, reductions, comprehensions — and rewrites -them as optimised [BQN](https://mlochbaum.github.io/BQN/) array -primitives. - -BQN (by Marshall Lochbaum) is an array language descended from APL/J/K. -It brings first-class functions, trains (`∘` `○` `⊸` `⟜`), -under/structural-under combinators (`⌾`), rank polymorphism, and -leading-axis theory to array processing. BQNiser lets you harness -10-100x speedups on array-heavy workloads **without learning BQN -yourself**. - -Where your Python loop takes 200ms to filter-then-reduce a million-row -column, a single BQN expression using `/` (replicate), `⌽` (reverse), or -`⍋` (grade-up) completes in under 2ms via -[CBQN](https://github.com/dzaima/CBQN)’s vectorised runtime. - -# How It Works - -BQNiser follows the [-iser -pattern](https://github.com/hyperpolymath/iseriser): you describe -**what** you want; the tool generates **everything**. - -1. **Manifest** (`bqniser.toml`) — describe your workload, entry - points, data shapes - -2. **Source Analysis** — AST-based detection of array patterns in Rust, - Python, or Julia source - -3. **Pattern Matching** — map detected patterns to BQN primitives: - - - Nested loops over arrays → `¨` (each), `⌜` (table) - - - Accumulate/reduce → `´` (fold), `` ` `` (scan) - - - Filter → `/` (replicate) with boolean mask - - - Sort/rank → `⍋` (grade-up), `⍒` (grade-down) - - - Reshape/transpose → `⥊` (reshape), `⍉` (transpose) - - - Concatenation → `∾` (join) - - - Index selection → `⊏` (select) - - - Reversal → `⌽` (reverse), `⌾` (under) for structural transforms - -4. **Idris2 ABI** (`src/interface/abi/`) — formal proofs that each - rewrite preserves input-output equivalence (dependent types - guarantee correctness) - -5. **BQN Codegen** — emit optimised BQN source using trains and tacit - style - -6. **CBQN FFI Bridge** (`src/interface/ffi/`) — Zig-based C-ABI bridge - to the [CBQN](https://github.com/dzaima/CBQN) runtime, so generated - BQN runs in-process with zero serialisation overhead - -# Key Value - -- **10-100x on array operations** — vectorised BQN primitives beat - scalar loops - -- **Automatic pattern detection** — finds optimisable code via AST - analysis - -- **Equivalence proofs** — Idris2 dependent types prove rewrites - preserve semantics - -- **Gradual adoption** — replace hot loops one at a time, keep the rest - untouched - -- **Zero BQN knowledge required** — the tool generates all BQN and FFI - code - -- **Rank polymorphism** — BQN’s leading-axis theory means primitives - generalise across any number of dimensions automatically - -# BQN Primitives Reference - -BQNiser targets these core primitives and combinators: - -| Glyph | Name | Detected Pattern | -|---------|------------|------------------------------------------| -| `∾` | Join | `concat`, `append`, `extend` | -| `⌽` | Reverse | `reversed()`, `[::-1]` | -| `⍋` | Grade Up | `sorted()`, `argsort` | -| `⍒` | Grade Down | `sorted(reverse=True)` | -| `/` | Replicate | `filter`, boolean indexing | -| `⊏` | Select | `arr[indices]`, `take`, `gather` | -| `⥊` | Reshape | `reshape`, `flatten`, `ravel` | -| `⍉` | Transpose | `transpose`, `T`, axis permutation | -| `¨` | Each | `map`, list comprehension | -| `⌜` | Table | nested `map`, outer product | -| `´` | Fold | `reduce`, `foldl`, `inject` | -| `` ` `` | Scan | `accumulate`, `scanl`, prefix sums | -| `⌾` | Under | structural transforms, lens-like updates | -| `∘○⊸⟜` | Trains | function composition, tacit pipelines | - -# Architecture - - bqniser.toml src/interface/abi/ src/interface/ffi/ - ┌──────────┐ ┌─────────────────┐ ┌─────────────────┐ - │ Manifest │──parse──→│ Idris2 ABI │──gen──→│ Zig FFI │ - │ (TOML) │ │ (Types, Layout, │ │ (CBQN embedding │ - └──────────┘ │ Foreign) │ │ C-ABI bridge) │ - │ └────────┬────────┘ └────────┬────────┘ - │ │ │ - ▼ ▼ ▼ - ┌──────────┐ ┌─────────────────┐ ┌─────────────────┐ - │ Rust CLI │──scan──→ │ Pattern Matcher │──emit─→│ BQN Codegen │ - │ (clap) │ │ (AST → BQN map)│ │ (.bqn files) │ - └──────────┘ └─────────────────┘ └─────────────────┘ - -- **Rust CLI** — parses manifest, invokes AST analysis, orchestrates - generation - -- **Pattern Matcher** — maps source-level patterns to BQN primitive - candidates - -- **Idris2 ABI** — proves BQN value layout (array header + shape - vector + data cells), proves rewrite equivalence for each - transformation - -- **BQN Codegen** — emits idiomatic BQN using trains, under, and tacit - definitions - -- **Zig FFI** — bridges CBQN’s C API (`BQN_NewEval`, `BQN_Call`, value - accessors), handles BQN value lifecycle and memory management - -Part of the [-iser family](https://github.com/hyperpolymath/iseriser) of -acceleration frameworks. - -# Use Cases - -- **Data processing pipelines** — ETL stages with heavy filtering, - sorting, reshaping - -- **Scientific computing** — matrix operations, statistical reductions, - signal processing - -- **Financial analytics** — rolling windows, aggregations, time-series - transforms - -- **Compiler/transpiler backends** — batch AST transformations as array - operations - -- **ETL optimisation** — replace row-by-row processing with bulk array - primitives - -# Quick Start - -```bash -# Initialise a manifest -bqniser init - -# Edit bqniser.toml to describe your workload -# (see examples/ for patterns) - -# Generate BQN + FFI artifacts -bqniser generate - -# Build everything -bqniser build - -# Run -bqniser run -``` - -# Status - -**Codebase in progress.** Architecture defined, CLI scaffolded, Idris2 -ABI types and Zig FFI bridge stubbed. Pattern detection engine and BQN -codegen are the active development frontier. - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/SECURITY.md b/SECURITY.adoc similarity index 57% rename from SECURITY.md rename to SECURITY.adoc index 5cf873a..545c8cf 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 bqniser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..8d5df76 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,34 @@ +== TEST-NEEDS.md — bqniser + +=== 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 b99482a..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ -# TEST-NEEDS.md — bqniser - -## 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 57% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index b051110..881992d 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,15 @@ - - +== TOPOLOGY.md — bqniser -# TOPOLOGY.md — bqniser +=== Purpose -## Purpose +Rust CLI tool that scans code for array computation patterns (loops, +maps, folds, comprehensions) and rewrites them as optimized BQN array +primitives. Delivers 10-100x speedups on array-heavy workloads without +requiring users to learn BQN explicitly. -Rust CLI tool that scans code for array computation patterns (loops, maps, folds, comprehensions) and rewrites them as optimized BQN array primitives. Delivers 10-100x speedups on array-heavy workloads without requiring users to learn BQN explicitly. +=== Module Map -## Module Map - -``` +.... bqniser/ ├── src/ │ ├── main.rs # CLI entry point @@ -21,18 +21,18 @@ bqniser/ ├── Cargo.toml # Rust package metadata └── examples/ └── ... (demo transformations) -``` +.... -## Data Flow +=== Data Flow -``` +.... [Existing Code] ──► [Scanner] ──► [Pattern Match] ──► [Rewriter] ──► [BQN Output] ↓ [Performance Analysis] -``` +.... -## Key Invariants +=== Key Invariants -- Targets array-heavy Python/Rust/JS code -- Generates standalone BQN that can be integrated back -- Preserves semantics: rewritten code computes same values +* Targets array-heavy Python/Rust/JS code +* Generates standalone BQN that can be integrated back +* Preserves semantics: rewritten code computes same values 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 73% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 06fdabc..5b5ad7b 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,17 +1,18 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +== SPDX-License-Identifier: CC-BY-SA-4.0 -# bqniser -- Topology +== Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) j.d.a.jewell@open.ac.uk -## Overview +== bqniser – Topology -BQNiser detects array computation patterns in existing source code and rewrites -them as optimised BQN array primitives, achieving 10-100x speedups on -array-heavy workloads via the CBQN runtime. +=== Overview -## Module Map +BQNiser detects array computation patterns in existing source code and +rewrites them as optimised BQN array primitives, achieving 10-100x +speedups on array-heavy workloads via the CBQN runtime. -``` +=== Module Map + +.... bqniser/ ├── src/ │ ├── main.rs # CLI entry point (clap subcommands) @@ -49,11 +50,11 @@ bqniser/ │ ├── practice/ # User guides, pattern catalogue │ └── attribution/ # Citations, acknowledgements └── .machine_readable/ # 6a2 metadata, policies, contractiles -``` +.... -## Data Flow +=== Data Flow -``` +.... User Source Code bqniser.toml │ │ ▼ ▼ @@ -95,34 +96,42 @@ User Source Code bqniser.toml │ (vectorised │ │ execution) │ └──────────────────┘ -``` +.... -## Key Interfaces +=== Key Interfaces -| Interface | From | To | Mechanism | -|-----------|------|----|-----------| -| Manifest | User | Rust CLI | TOML parsing (serde) | -| Source AST | User code | Pattern Matcher | tree-sitter / syn | -| Pattern → BQN | Pattern Matcher | BQN Codegen | Internal IR | -| BQN → CBQN | BQN Codegen | Zig FFI | `.bqn` file or inline eval | -| CBQN C API | Zig FFI | CBQN runtime | C function calls | -| ABI proofs | Idris2 | Generated headers | Compile-time verification | -| Rust ↔ Zig | Rust CLI | Zig FFI | C-ABI (shared library) | +[cols=",,,",options="header",] +|=== +|Interface |From |To |Mechanism +|Manifest |User |Rust CLI |TOML parsing (serde) +|Source AST |User code |Pattern Matcher |tree-sitter / syn +|Pattern → BQN |Pattern Matcher |BQN Codegen |Internal IR +|BQN → CBQN |BQN Codegen |Zig FFI |`+.bqn+` file or inline eval +|CBQN C API |Zig FFI |CBQN runtime |C function calls +|ABI proofs |Idris2 |Generated headers |Compile-time verification +|Rust ↔ Zig |Rust CLI |Zig FFI |C-ABI (shared library) +|=== -## External Dependencies +=== External Dependencies -| Dependency | Role | Link | -|------------|------|------| -| CBQN | BQN runtime engine | https://github.com/dzaima/CBQN | -| BQN specification | Language semantics | https://mlochbaum.github.io/BQN/ | -| tree-sitter | Multi-language AST parsing | https://tree-sitter.github.io/ | -| syn | Rust AST parsing | https://docs.rs/syn | -| clap | CLI argument parsing | https://docs.rs/clap | +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Dependency |Role |Link +|CBQN |BQN runtime engine |https://github.com/dzaima/CBQN +|BQN specification |Language semantics |https://mlochbaum.github.io/BQN/ +|tree-sitter |Multi-language AST parsing |https://tree-sitter.github.io/ +|syn |Rust AST parsing |https://docs.rs/syn +|clap |CLI argument parsing |https://docs.rs/clap +|=== -## Invariants +=== Invariants -1. Every BQN rewrite MUST have an Idris2 equivalence proof before codegen emits it -2. All CBQN FFI calls go through the Zig bridge (never raw C from Rust) -3. BQN value memory is managed by CBQN; Zig bridge handles lifecycle -4. Pattern detection is conservative: only rewrite when confidence is high -5. Original source code is never modified; BQN alternatives are generated alongside +[arabic] +. Every BQN rewrite MUST have an Idris2 equivalence proof before codegen +emits it +. All CBQN FFI calls go through the Zig bridge (never raw C from Rust) +. BQN value memory is managed by CBQN; Zig bridge handles lifecycle +. Pattern detection is conservative: only rewrite when confidence is +high +. Original source code is never modified; BQN alternatives are generated +alongside 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..1ff6304 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — bqniser (Developer) + +=== What is bqniser? + +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 3863b71..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — bqniser (Developer) - -## What is bqniser? -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..9370aca --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — bqniser (User) + +=== What is bqniser? + +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 12c646e..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — bqniser (User) - -## What is bqniser? -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