# AffineScript Compiler Capabilities Analysis

## 🎯 Current Compiler Targets

### Primary Target: WebAssembly

**Current Status:** ✅ **Fully Implemented**

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

```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**

```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 + 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
```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 (note: lexer does not yet emit ZERO/ONE quantity literal tokens — blocks QTT surface syntax)
- ⚠️ **Type Checker:** Rules implemented (bidirectional inference in `lib/typecheck.ml`), but **experimental (enforcement landing soon)** — not yet wired into `check`/`compile`/`eval` CLI paths
- ⚠️ **Affine Types / QTT:** **experimental (enforcement landing soon)** — quantity semiring in `lib/quantity.ml` exists but is not called from `bin/main.ml`
- ⚠️ **Borrow Checker:** **experimental (enforcement landing soon)** — `lib/borrow.ml` carries `[IMPL-DEP: Phase 3]` markers; runtime checks in interpreter only
- ⚠️ **Dependent / Refinement Types:** parse-only — `TRefined` AST node exists but predicates do not reduce
- ✅ **WASM Codegen:** Complete (basic operations)
- ✅ **Julia Codegen:** Phase 1 (basic types)
- ❌ **Native Codegen:** Not implemented
- ❌ **GPU Codegen:** Not implemented
- ❌ **Optimizer:** Not implemented

### Missing Features
- ❌ **SIMD Operations:** No WASM SIMD support
- ❌ **Multithreading:** No WASM threads
- ❌ **Tail Calls:** Not implemented
- ❌ **Reference Types:** Not implemented
- ❌ **Exception Handling:** Not implemented
- ❌ **Garbage Collection:** No GC (manual memory management)

---

## 📊 Platform Compatibility Matrix

| 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)
```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
```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)
```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