// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2024-2026 hyperpolymath (Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>)
= AffineScript Compiler Capabilities Analysis

____
*⚠️ AUTHORITATIVE STATUS:* Superseded by
link:docs/CAPABILITY-MATRIX.adoc[`docs/CAPABILITY-MATRIX.adoc`] for all
feature-readiness claims. This file is retained as analysis history;
where it disagrees with the matrix, the matrix wins.
____

== 🎯 Current Compiler Targets

=== Primary Target: WebAssembly

*Current Status:* ✅ *Fully Implemented*

The AffineScript compiler currently *compiles to WebAssembly 1.0* as its
primary target.

[source,ocaml]
----
(* lib/codegen.ml - WASM Backend *)
module Wasm : sig
  val generate_code : context -> Ast.program -> string
  (* Generates WebAssembly text format *)
end
----

=== Secondary Target: Julia (Experimental)

*Current Status:* ⚠️ *Phase 1 - Basic Types Only*

[source,ocaml]
----
(* lib/julia_codegen.ml - Julia Backend *)
module Julia_codegen : sig
  val generate_code : Ast.program -> string
  (* Generates Julia source code - Phase 1 MVP *)
end
----

'''''

== 📊 Deployment Platform Support

=== iOS

* *Status:* ❌ *Not Directly Supported*
* *Workaround:* ✅ *Via WebAssembly in Safari*
* *Limitations:* No native compilation, WASM only
* *Performance:* Good (Safari has excellent WASM support)

=== Android

* *Status:* ✅ *Supported via WebAssembly*
* *Methods:* Chrome/Firefox WASM, or native via Termux
* *Performance:* Excellent (Chrome V8 WASM engine)
* *Limitations:* No direct APK compilation

=== MINIX

* *Status:* ❌ *Not Supported*
* *Reason:* No WASM runtime in MINIX by default
* *Workaround:* Would need custom WASM runtime port

=== RISC-V

* *Status:* ⚠️ *Partial Support*
* *Current:* WASM can run on RISC-V via Wasmtime/WASI
* *Native:* ❌ No RISC-V assembly backend yet
* *Performance:* Good (Wasmtime is optimized for RISC-V)

=== ARM (32/64-bit)

* *Status:* ✅ *Supported via WASM*
* *Native:* ❌ No ARM assembly backend yet
* *Performance:* Excellent (ARM has fast WASM interpreters)
* *Platforms:* iOS, Android, Linux ARM, Windows ARM

=== AMD (x86-64)

* *Status:* ✅ *Fully Supported*
* *Methods:* WASM in browsers, native via WASI
* *Performance:* Excellent (native-speed WASM)
* *Platforms:* Windows, Linux, macOS

=== NVIDIA (CUDA/GPU)

* *Status:* ❌ *Not Supported*
* *Current:* No GPU code generation
* *Workaround:* WASM {plus} WebGPU in browsers
* *Future:* GPU backend planned (see backends/gpu++_++backend.ml)

'''''

== 🧠 Memory Architecture Support

=== GDDR5/6/7 (GPU Memory)

* *Status:* ❌ *Not Supported*
* *Reason:* No GPU backend implementation
* *Current:* WASM uses linear memory only
* *Future:* GPU backend will add GDDR support

=== HBM (High Bandwidth Memory)

* *Status:* ❌ *Not Supported*
* *Reason:* No GPU/accelerator backends
* *Current:* All memory operations are CPU-bound
* *Future:* NPU/GPU backends will add HBM support

=== Current Memory Model

[source,wasm]
----
(module
  (memory $memory 16)  ; 16 pages = 1MB (64KB per page)
  (export "memory" (memory $memory))
)
----

*Limitations:* - Maximum 1MB by default (configurable) - No GPU memory
access - No shared memory between CPU/GPU - No HBM or GDDR support

'''''

== 🔧 Current Compiler Pipeline

....
AffineScript Source
    ↓ (Parser)
Abstract Syntax Tree (AST)
    ↓ (Type Checker)
Typed AST
    ↓ (Borrow Checker)
Validated AST
    ↓ (Code Generator)
WebAssembly Text Format
    ↓ (WASM Toolchain)
WebAssembly Binary (.wasm)
....

=== Supported Features

* ✅ *Lexer & Parser:* Complete (quantity sugar `:0/:1/:ω` and attribute
form `@erased/@linear/@unrestricted` accepted)
* ✅ *Type Checker:* Wired into `check`/`compile`/`eval` CLI paths
* ✅ *Affine Types / QTT:* Live gate
(`Quantity.check++_++program++_++quantities` runs in standard CLI
pipeline)
* ⚠️ *Borrow Checker:* Live gate with ongoing Phase 3 work
* ❌ *Dependent / Refinement Types:* removed in v1 (#558) — withdrawn rather
than shipped unenforced; `assume(...)` is rejected at parse. See
link:../SOUNDNESS.adoc[docs/SOUNDNESS.adoc]
* ✅ *WASM Codegen:* Primary backend (feature gaps remain for advanced
effect-handler lowering)
* ✅ *Julia Codegen:* Phase 1 (basic types)
* ❌ *Native Codegen:* Not implemented
* ❌ *GPU Codegen:* Not implemented
* ⚠️ *Optimizer:* Basic constant folding in `lib/opt.ml`; no full
optimization pipeline yet

=== Missing Features

* ❌ *SIMD Operations:* No WASM SIMD support
* ❌ *Multithreading:* No WASM threads
* ❌ *Tail Calls:* Not implemented
* ❌ *Reference Types:* Not implemented
* ⚠️ *Exception Handling in WASM Backends:* `try/finally` lowering
exists; `try/catch` still requires EH proposal/CPS path
* ⚠️ *Garbage Collection:* WASM GC backend exists (`--wasm-gc`) but is
not full feature parity

'''''

== 📊 Platform Compatibility Matrix

[width="99%",cols="19%,21%,26%,21%,13%",options="header",]
|===
|Platform |WASM Support |Native Support |GPU Support |Status
|*iOS* |✅ Excellent |❌ None |❌ None |Works via Safari
|*Android* |✅ Excellent |❌ None |❌ None |Works via Chrome
|*MINIX* |❌ None |❌ None |❌ None |Not supported
|*RISC-V* |✅ Good |❌ None |❌ None |Via Wasmtime
|*ARM64* |✅ Excellent |❌ None |❌ None |All modern browsers
|*ARM32* |✅ Good |❌ None |❌ None |Most browsers
|*x86-64 (AMD/Intel)* |✅ Excellent |❌ None |❌ None |All browsers
|*NVIDIA GPU* |❌ None |❌ None |❌ None |Not supported
|*Apple Silicon* |✅ Excellent |❌ None |❌ None |Safari WASM
|*Windows* |✅ Excellent |❌ None |❌ None |Edge/Chrome/Firefox
|*Linux* |✅ Excellent |❌ None |❌ None |All browsers
|*macOS* |✅ Excellent |❌ None |❌ None |Safari/Chrome
|===

'''''

== 🚀 Deployment Options

=== Web Deployment (Recommended)

[source,html]
----
<!-- Load WASM module in browser -->
<script>
  const response = await fetch('program.wasm');
  const wasmModule = await WebAssembly.instantiateStreaming(response);
  wasmModule.instance.exports.main();
</script>
----

*Pros:* - ✅ Works on all platforms with modern browsers - ✅ No
installation required - ✅ Automatic updates - ✅ Sandboxed execution

*Cons:* - ❌ No GPU acceleration - ❌ Limited to browser capabilities -
❌ No direct hardware access

=== Node.js/WASI Deployment

[source,javascript]
----
// Run WASM in Node.js
const fs = require('fs');
const wasmBuffer = fs.readFileSync('program.wasm');
WebAssembly.instantiate(wasmBuffer).then(wasmModule => {
  wasmModule.instance.exports.main();
});
----

*Pros:* - ✅ Server-side execution - ✅ File system access via WASI - ✅
Can use Node.js APIs

*Cons:* - ❌ No GPU access - ❌ Single-threaded - ❌ No SIMD

=== Native Deployment (Future)

[source,bash]
----
# Future: Compile to native binary
affinescript compile --target native --arch arm64 program.affine
./program
----

*Status:* ❌ Not yet implemented *Planned:* Native backend in
development *Target:* Alpha-2 release

'''''

== 💾 Memory Usage Analysis

=== Current WASM Memory Model

....
Memory Layout:
- Linear memory: 64KB pages (default 16 pages = 1MB)
- Heap: Managed manually (no GC)
- Stack: Grows downward from high address
- Globals: Fixed addresses

Allocation Strategy:
- Bump pointer allocation
- No fragmentation handling
- Manual free required
- No generational GC
....

=== Memory Limitations

* *Maximum Memory:* 1MB by default (configurable)
* *No GPU Memory:* Cannot access GDDR5/6/7 or HBM
* *No Shared Memory:* CPU and GPU memory separate
* *No Unified Memory:* No automatic CPU/GPU sync
* *Manual Management:* Developer must free memory

=== Future Memory Improvements

* 🔄 *Automatic GC:* Planned for Beta
* 🔄 *SIMD Support:* WASM SIMD extension
* 🔄 *Multithreading:* WASM threads
* 🔄 *GPU Memory:* GPU backend will add GDDR/HBM support
* 🔄 *Unified Memory:* Future CPU/GPU integration

'''''

== 🎯 Performance Characteristics

=== Current Performance

* *Arithmetic:* Native speed (WASM is fast)
* *Memory Access:* Linear memory (no caching)
* *Function Calls:* Direct calls (no virtual dispatch)
* *Control Flow:* Optimized branches
* *No SIMD:* Scalar operations only
* *No Parallelism:* Single-threaded

=== Benchmark Results (Estimated)

....
Operation           | WASM (Current) | Native (Future) | GPU (Future)
--------------------|----------------|-----------------|--------------
Integer Arithmetic  | 100%           | 100%            | N/A
Float Arithmetic    | 95%            | 100%            | 1000x (GPU)
Memory Access       | 80%            | 100%            | 500x (GPU)
Function Calls      | 90%            | 100%            | N/A
Control Flow        | 95%            | 100%            | N/A
SIMD Operations     | N/A            | 4x-8x           | 16x-32x
Parallel Operations| N/A            | 2x-4x (cores)   | 1000x (cores)
....

'''''

== 🔮 Future Platform Support Roadmap

=== Short-Term (Alpha-1 to Alpha-2)

* 🔄 *Native Backend:* x86-64 assembly generation
* 🔄 *ARM64 Support:* Native ARM assembly
* 🔄 *RISC-V Support:* Native RISC-V assembly
* 🔄 *WASM SIMD:* Enable SIMD extensions
* 🔄 *WASM Threads:* Add multithreading support

=== Medium-Term (Beta Release)

* 🚀 *GPU Backend:* WebGPU/Vulkan compute
* 🚀 *Audio Backend:* WebAudio/DSP support
* 🚀 *iOS/Android:* Native app integration
* 🚀 *Memory Management:* Automatic GC
* 🚀 *Optimizer:* Code optimization passes

=== Long-Term (1.0 Release)

* 🌟 *NVIDIA CUDA:* GPU acceleration
* 🌟 *Apple Metal:* GPU acceleration
* 🌟 *Vulkan Compute:* Cross-platform GPU
* 🌟 *GDDR5/6/7:* GPU memory support
* 🌟 *HBM Support:* High bandwidth memory
* 🌟 *Unified Memory:* CPU/GPU shared memory
* 🌟 *MINIX Support:* Custom runtime port

'''''

== 📋 Deployment Checklist

=== Currently Supported ✅

* [x] WebAssembly compilation
* [x] Browser deployment (iOS/Android/Desktop)
* [x] Node.js/WASI deployment
* [x] Basic arithmetic operations
* [x] Memory management (manual)
* [x] Function calls and control flow
* [x] Linear memory model

=== Not Yet Supported ❌

* [ ] Native binary compilation
* [ ] GPU acceleration (CUDA/WebGPU/Vulkan)
* [ ] SIMD vector operations
* [ ] Multithreading
* [ ] Automatic garbage collection
* [ ] GDDR5/6/7 memory access
* [ ] HBM memory access
* [ ] Unified CPU/GPU memory
* [ ] MINIX deployment
* [ ] Direct hardware access

=== Planned for Future Releases 🔄

* [ ] Native backend (Alpha-2)
* [ ] GPU backend (Beta)
* [ ] Audio backend (Beta)
* [ ] ARM64 native (Alpha-2)
* [ ] RISC-V native (Alpha-2)
* [ ] WASM SIMD (Alpha-2)
* [ ] WASM threads (Alpha-2)
* [ ] Memory optimizer (Beta)
* [ ] GPU memory support (1.0)

'''''

== 🎓 Recommendations

=== For Game Developers (Current)

....
✅ Use WASM for browser-based games
✅ Target iOS/Android via Web browsers
✅ Use Web Audio API for sound
✅ Use WebGL/WebGPU for graphics
❌ Avoid GPU compute (not available)
❌ Avoid native compilation (not available)
....

=== For Systems Programmers (Current)

....
✅ Use WASM for portable code
✅ Use WASI for system integration
✅ Manual memory management required
❌ No low-level hardware access
❌ No GPU acceleration
❌ No SIMD optimization
....

=== For Future-Proof Development

....
🔄 Plan for native backend (Alpha-2)
🔄 Design for GPU acceleration (Beta)
🔄 Consider SIMD for performance (Alpha-2)
🔄 Prepare for multithreading (Alpha-2)
🔄 Design memory-efficient data structures
....

'''''

== 🔒 Conclusion

*Current State:* AffineScript compiles to *WebAssembly 1.0* as its
primary target, with experimental Julia code generation. The compiler is
*deployable on iOS/Android via browsers*, *RISC-V via Wasmtime*, and
*ARM/AMD via WASM*, but has *no native compilation*, *no GPU support*,
and *no GDDR/HBM memory access*.

*Strengths:* - ✅ Excellent browser support - ✅ Portable across
platforms - ✅ Memory-safe by design - ✅ Type-safe compilation

*Limitations:* - ❌ No GPU acceleration - ❌ No native binary output -
❌ Limited to 1MB memory by default - ❌ No SIMD or parallelism - ❌ No
GDDR5/6/7 or HBM support

*Future:* The backend architecture has been designed to support all
these features, with processor backends and kernel stubs in place.
Implementation will proceed through Alpha-2, Beta, and 1.0 releases.

*Recommendation:* For current development, use WASM deployment targeting
browsers. For future-proof design, plan for native and GPU backends
coming in later releases.

SPDX-License-Identifier: CC-BY-SA-4.0 SPDX-FileCopyrightText: 2026 Jonathan
D.A. Jewell
