# AILANG Documentation for LLMs

This file contains all AILANG documentation in a single file for LLM consumption.

Last updated: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

---


# README

# 🧠 AILANG: The Deterministic Language for AI Coders

![CI](https://github.com/sunholo-data/ailang/workflows/CI/badge.svg)
![Coverage](https://img.shields.io/badge/coverage-32.6%25-orange.svg)
![Go Version](https://img.shields.io/badge/go-%3E%3D1.22-blue.svg)
![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)

AILANG is a purely functional, effect-typed language designed for **autonomous code synthesis and reasoning**. Unlike human-oriented languages built around IDEs, concurrency, and sugar, AILANG's design goal is **machine decidability, semantic transparency, and compositional determinism**.

---

## 🧩 Core Philosophy

**For humans, a language is a tool for expression.**
**For AIs, it's a substrate for reasoning.**

AILANG minimizes ambiguity and maximizes predictability. Every construct — type, effect, or expression — has **deterministic semantics** that can be reflected, verified, and serialized.

---

## 🏗️ Architecture Overview

| Layer | Description | Status |
|-------|-------------|--------|
| **1. Core Semantics** | Pure functional core with algebraic data types (ADTs), first-class effects, and Hindley-Milner type inference. | ✅ Stable |
| **2. Type System** | Polymorphic effects (`! {IO, ε}`), `Result` and `Option` types, and fully deterministic unification (TApp-aware). | ✅ Stable |
| **3. Reflection & Meta-Programming** | Typed quasiquotes and semantic reflection (`reflect(typeOf(f))`) for deterministic code generation. | 🔜 v0.4.x |
| **4. Deterministic Tooling** | Canonical `normalize`, `suggest`, and `apply` commands; JSON schema output; `--emit-trace jsonl` for training data. | 🔜 v0.3.15 |
| **5. Schema & Hashing Layer** | Machine-readable type/effect registry and versioned semantic hashes for reproducible builds. | 🔜 v0.4.x |
| **6. Runtime & Effects** | Deterministic evaluator with explicit effect rows; supports IO, FS, Net, Clock; no hidden state or global scheduler. | ✅ Stable |
| **7. Cognitive Interfaces** | JSONL trace export for AI self-training; deterministic edit plans for autonomous refactoring. | 🔜 v0.4.x |
| **8. Future Extensions** | Capability budgets (`! {IO @limit=2}`), semantic DAG scheduler (`schedule { a >> b \| c }`). | 🔮 v0.5.x+ |

---

## ❌ Removed / Deprecated Human-Oriented Features

| Removed Feature | Reason for Removal |
|----------------|-------------------|
| **CSP Concurrency / Session Types** | Replaced by static effect-typed task graphs; no runtime scheduler needed. |
| **Unstructured Macros** | Replaced by typed quasiquotes (deterministic AST templates). |
| **Type Classes** | Replaced by structural reflection and record-based traits; removes implicit resolution. |
| **LSP Server** | Superseded by deterministic JSON-RPC API (`ailangd`) exposing parser/typechecker directly. |
| **IDE-centric DX Features** | AIs interact via CLI / API; autocompletion and hover text are unnecessary. |

---

## 🔮 AI-Native Roadmap

| Milestone | Goal | Example Deliverable |
|-----------|------|-------------------|
| **v0.3.15 – Deterministic Tooling** | Canonical normalization, symbol import suggestion, JSON trace export | `ailang suggest-imports file.ail` |
| **v0.4.0 – Meta & Reflection Layer** | Typed quasiquotes + reflection API | `quote (x) -> x + 1 : (int)->int` |
| **v0.4.2 – Schema Registry** | Machine-readable type/effect schemas for deterministic builds | `/schemas/std/io.json` |
| **v0.5.x – Unified Registry Runtime** | Remove legacy builtin registry; single spec source | `RegisterBuiltin(spec)` unified |
| **v0.6.x – Capability Budgets & DAG Scheduler** | Deterministic parallelism via static scheduling | `schedule { parse >> decode \| validate }` |
| **v1.0 – Cognitive Autonomy** | Full round-trip reasoning: AI reads, edits, compiles, evaluates, and self-trains from traces | `--emit-trace jsonl` → fine-tuned validator |

---

## 🧪 Current Milestone: v0.3.14 (JSON Decode)

- ✅ Added `std/json.decode : string -> Result[Json, string]` with streaming parser
- ✅ Fixed list/record pattern matching at runtime
- ✅ Unified primitive type casing (`string`, `int`, `float`, `bool`)
- ✅ DX overhaul: operators (`==`, `!=`, `<`, `>=`) now work naturally
- ✅ All **2,847 tests passing**; 100% coverage on new builtin
- 🔜 **Next**: deterministic tooling (`normalize`, `suggest`, `apply`) in v0.3.15

### Major Milestones

- **v0.3.14 (Oct 2025)**: JSON Decode Release - JSON parsing + pattern matching fixes
- **v0.3.12 (Oct 2025)**: Recovery Release - `show()` builtin restored (recovers 51% of benchmarks)
- **v0.3.11 (Oct 2025)**: Critical row unification fix
- **v0.3.10 (Oct 2025)**: M-DX1 Developer Experience - Builtin system migration (-67% dev time)
- **v0.3.9 (Oct 2025)**: AI API Integration - HTTP headers, JSON encoding, OpenAI example
- **v0.3.6 (Oct 2025)**: AI usability - auto-import, record updates, error detection
- **v0.3.5 (Oct 2025)**: Anonymous functions, `letrec`, numeric conversions

For detailed version history, see [CHANGELOG.md](CHANGELOG.md).

---

## 💡 Why AILANG Works Better for AIs

| Human Need | Human Feature | AI Equivalent in AILANG |
|-----------|---------------|------------------------|
| IDE assistance | LSP / autocompletion | Deterministic type/query API |
| Asynchronous code | Threads / goroutines | Static task DAGs with effects |
| Code reuse | Inheritance / traits | Structural reflection & records |
| Debugging | Interactive debugger | Replayable evaluation trace |
| Logging | `print` / `console` | `--emit-trace jsonl` structured logs |
| Macros | text substitution | Typed quasiquotes (semantic macros) |

---

## 🔁 Why AILANG Has No Loops (and Never Will)

AILANG intentionally omits `for`, `while`, and other open-ended loop constructs.
This isn't a missing feature — it's a design decision rooted in **determinism and compositional reasoning**.

### 🧠 For Humans, Loops Express Control. For AIs, Loops Obscure Structure.

Traditional loops compress time into mutable state:

```python
sum = 0
for i in range(0, 10):
    sum = sum + i
```

This is compact for humans but **semantically opaque** for machines:
the iteration count, state shape, and termination guarantee are **implicit**.

AILANG replaces this with **total, analyzable recursion**:

```ailang
foldl(range(0, 10), 0, \acc, i. acc + i)
```

or **pattern matching**:

```ailang
func sum(list: List[Int]) -> Int {
  match list {
    [] => 0,
    [x, ...xs] => x + sum(xs)
  }
}
```

Every iteration is a **pure function over data, not time** —
which makes it statically decidable, effect-safe, and perfectly compositional.

### ⚙️ The Deterministic Iteration Principle

| Goal | Imperative Loops | AILANG Alternative |
|------|-----------------|-------------------|
| Repeat a computation | `for` / `while` | `map`, `fold`, `filter`, `rec` |
| Aggregate results | mutable accumulator | `foldl` / `foldr` |
| Early termination | `break` | `foldWhile` / `find` |
| Parallel evaluation | scheduler threads | static task DAGs |
| Verification | undecidable | total + effect-typed |

### 🧩 Benefits

- **Deterministic semantics**: iteration defined by data, not by time
- **Static totality**: no halting ambiguity
- **Composable reasoning**: works algebraically with higher-order functions
- **Easier optimization**: map/fold can fuse or parallelize safely
- **Simpler runtime**: no mutable counters or loop scopes

### 💡 Future Syntactic Sugar

For readability, AILANG may later support **comprehension syntax**:

```ailang
[ p.name for p in people if p.age >= 30 ]
```

…which **desugars deterministically** to:

```ailang
map(filter(people, \p. p.age >= 30), \p. p.name)
```

**No hidden state. No implicit time. Fully analyzable by both compiler and AI.**

For the formal rationale and algebraic laws, see the [Why No Loops?](https://sunholo-data.github.io/ailang/docs/reference/no-loops) documentation.

---

## Quick Start

### Installation

```bash
# From source
git clone https://github.com/sunholo/ailang.git
cd ailang
make install

# Verify installation
ailang --version
```

For detailed installation instructions, see the [Getting Started Guide](docs/guides/getting-started.md).

### Hello World (Module Execution)

```ailang
-- examples/demos/hello_io.ail
module examples/demos/hello_io

import std/io (println)

export func main() -> () ! {IO} {
  println("Hello from AILANG v0.3.14!")
}
```

```bash
ailang run --caps IO examples/demos/hello_io.ail
# Output: Hello from AILANG v0.3.14!
```

**Important**: Flags must come BEFORE the filename:
```bash
# ✅ CORRECT:
ailang run --caps IO --entry main file.ail

# ❌ WRONG:
ailang run file.ail --caps IO --entry main
```

### Interactive REPL

The REPL features full type inference and deterministic evaluation:

```bash
ailang repl

λ> 1 + 2
3 :: Int

λ> "Hello " ++ "World"
Hello World :: String

λ> let double = \x. x * 2 in double(21)
42 :: Int

λ> :type \x. x + x
\x. x + x :: ∀α. Num α ⇒ α → α

λ> :quit
```

**REPL Commands**: `:help`, `:type <expr>`, `:instances`, `:import <module>`, `:history`, `:clear`

See [REPL Commands](docs/reference/repl-commands.md) for full reference.

---

## What AILANG Can Do (Implementation Status)

### ✅ Core Language

- **Pure functional programming** - Lambda calculus, closures, recursion
- **Hindley-Milner type inference** - Row polymorphism, let-polymorphism
- **Built-in type class instances** - `Num`, `Eq`, `Ord`, `Show` (structural reflection planned for v0.4.0)
- **Algebraic effects** - Capability-based security (IO, FS, Clock, Net)
- **Pattern matching** - ADTs with exhaustiveness checking
- **Module system** - Runtime execution, cross-module imports
- **Block expressions** - `{ e1; e2; e3 }` for sequencing
- **JSON support** - Parsing (`std/json.decode`), encoding (`std/json.encode`)

### ✅ Development Tools

- **M-EVAL** - AI code generation benchmarks (multi-model support)
- **M-EVAL-LOOP v2.0** - Native Go eval tools with 90%+ test coverage
- **Structured error reporting** - JSON schemas for deterministic diagnostics
- **Effect system runtime** - Hermetic testing with `MockEffContext`

### 🔜 Deterministic Tooling (v0.3.15)

- **`ailang normalize`** - Canonical code formatting
- **`ailang suggest-imports`** - Automatic import resolution
- **`ailang apply`** - Deterministic code edits from JSON plans
- **`--emit-trace jsonl`** - Structured execution traces for training

### 🔮 Future (v0.4.0+)

- **Typed quasiquotes** - Deterministic AST templates
- **Structural reflection** - Replace hardcoded type classes
- **Schema registry** - Machine-readable type/effect definitions
- **Capability budgets** - Resource-bounded effects

---

## 📊 Test Coverage

**Examples**: 48/66 passing (72.7%)

All record subsumption, effect system (IO, FS, Clock, Net), type class, ADT, recursion, and block expression examples working.

See [examples/STATUS.md](examples/STATUS.md) for detailed status.

<!-- EXAMPLES_STATUS_START -->
## Status

![Examples](https://img.shields.io/badge/examples-52%20passing%2032%20failing-red.svg)

### Example Verification Status

*Last updated: 2025-10-18 22:26:22 UTC*

**Summary:** 52 passed, 32 failed, 4 skipped (Total: 88)

| Example File | Status | Notes |
|--------------|--------|-------|
| `adt_option.ail` | ✅ Pass |  |
| `adt_simple.ail` | ✅ Pass |  |
| `ai_call.ail` | ❌ Fail | Warning: import path 'stdlib/std/*' is deprecat... |
| `arithmetic.ail` | ❌ Fail | Error: type error in examples/arithmetic (decl ... |
| `block_demo.ail` | ⏭️ Skip | Test/demo file |
| `block_recursion.ail` | ✅ Pass |  |
| `bug_float_comparison.ail` | ✅ Pass |  |
| `bug_modulo_operator.ail` | ✅ Pass |  |
| `claude_haiku_call.ail` | ❌ Fail | Warning: import path 'stdlib/std/*' is deprecat... |
| `demo_ai_api.ail` | ❌ Fail | Error: type error in examples/demo_ai_api (decl... |
| `demo_openai_api.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `demos/adt_pipeline.ail` | ✅ Pass |  |
| `demos/effects_pure.ail` | ❌ Fail | Warning: import path 'stdlib/std/*' is deprecat... |
| `demos/hello_io.ail` | ✅ Pass |  |
| `effects_basic.ail` | ✅ Pass |  |
| `effects_pure.ail` | ✅ Pass |  |
| `experimental/ai_agent_integration.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `experimental/concurrent_pipeline.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `experimental/factorial.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `experimental/quicksort.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `experimental/web_api.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `func_expressions.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `guards_basic.ail` | ✅ Pass |  |
| `hello.ail` | ❌ Fail | Error: type error in examples/hello (decl 0): u... |
| `json_basic_decode.ail` | ✅ Pass |  |
| `lambda_expressions.ail` | ❌ Fail | Error: type error in examples/lambda_expression... |
| `letrec_recursion.ail` | ✅ Pass |  |
| `list_patterns.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `micro_block_if.ail` | ✅ Pass |  |
| `micro_block_seq.ail` | ✅ Pass |  |
| `micro_clock_measure.ail` | ❌ Fail | Error: type error in examples/micro_clock_measu... |
| `micro_io_echo.ail` | ✅ Pass |  |
| `micro_net_fetch.ail` | ❌ Fail | Error: type error in examples/micro_net_fetch (... |
| `micro_option_map.ail` | ✅ Pass |  |
| `micro_record_person.ail` | ✅ Pass |  |
| `numeric_conversion.ail` | ❌ Fail | Error: type error in examples/numeric_conversio... |
| `option_demo.ail` | ⏭️ Skip | Test/demo file |
| `patterns.ail` | ✅ Pass |  |
| `records.ail` | ❌ Fail | Error: type error in examples/records (decl 3):... |
| `recursion_error.ail` | ✅ Pass |  |
| `recursion_factorial.ail` | ✅ Pass |  |
| `recursion_fibonacci.ail` | ✅ Pass |  |
| `recursion_mutual.ail` | ✅ Pass |  |
| `recursion_quicksort.ail` | ✅ Pass |  |
| `showcase/01_type_inference.ail` | ❌ Fail | Error: type error in examples/showcase/01_type_... |
| `showcase/02_lambdas.ail` | ❌ Fail | Error: type error in examples/showcase/02_lambd... |
| `showcase/03_lists.ail` | ❌ Fail | Error: type error in examples/showcase/03_lists... |
| `showcase/03_type_classes.ail` | ❌ Fail | Error: type error in examples/showcase/03_type_... |
| `showcase/04_closures.ail` | ❌ Fail | Error: type error in examples/showcase/04_closu... |
| `simple.ail` | ✅ Pass |  |
| `stdlib_demo.ail` | ⏭️ Skip | Test/demo file |
| `stdlib_demo_simple.ail` | ⏭️ Skip | Test/demo file |
| `test_effect_annotation.ail` | ✅ Pass |  |
| `test_effect_capability.ail` | ✅ Pass |  |
| `test_effect_fs.ail` | ✅ Pass |  |
| `test_effect_io.ail` | ✅ Pass |  |
| `test_effect_io_simple.ail` | ❌ Fail | Error: evaluation error: _io_println: no effect... |
| `test_exhaustive_bool_complete.ail` | ✅ Pass |  |
| `test_exhaustive_bool_incomplete.ail` | ✅ Pass |  |
| `test_exhaustive_wildcard.ail` | ✅ Pass |  |
| `test_fizzbuzz.ail` | ✅ Pass |  |
| `test_float_comparison.ail` | ✅ Pass |  |
| `test_float_eq_works.ail` | ✅ Pass |  |
| `test_float_modulo.ail` | ✅ Pass |  |
| `test_guard_bool.ail` | ✅ Pass |  |
| `test_guard_debug.ail` | ✅ Pass |  |
| `test_guard_false.ail` | ✅ Pass |  |
| `test_import_ctor.ail` | ✅ Pass |  |
| `test_import_func.ail` | ✅ Pass |  |
| `test_integral.ail` | ✅ Pass |  |
| `test_invocation.ail` | ✅ Pass |  |
| `test_io_builtins.ail` | ✅ Pass |  |
| `test_m_r7_comprehensive.ail` | ❌ Fail | Error: module loading error: failed to load exa... |
| `test_module_minimal.ail` | ✅ Pass |  |
| `test_modulo_works.ail` | ✅ Pass |  |
| `test_net_file_protocol.ail` | ❌ Fail | Error: type error in examples/test_net_file_pro... |
| `test_net_localhost.ail` | ❌ Fail | Error: type error in examples/test_net_localhos... |
| `test_net_security.ail` | ❌ Fail | Error: type error in examples/test_net_security... |
| `test_no_import.ail` | ✅ Pass |  |
| `test_record_subsumption.ail` | ✅ Pass |  |
| `test_single_guard.ail` | ✅ Pass |  |
| `test_use_constructor.ail` | ✅ Pass |  |
| `test_with_import.ail` | ✅ Pass |  |
| `type_classes_working_reference.ail` | ❌ Fail | Error: type error in examples/type_classes_work... |
| `typeclasses.ail` | ❌ Fail | Error: type error in examples/typeclasses (decl... |
| `v3_3/imports.ail` | ✅ Pass |  |
| `v3_3/imports_basic.ail` | ✅ Pass |  |
| `v3_3/math/gcd.ail` | ❌ Fail | Error: entrypoint 'main' not found in module |

<!-- EXAMPLES_STATUS_END -->

---

## Documentation

📖 **[Complete Documentation](https://sunholo-data.github.io/ailang/)** - Visit our full documentation site

**Quick Links:**
- **[Getting Started](https://sunholo-data.github.io/ailang/docs/guides/getting-started)** - Installation and tutorial
- **[Language Guide](https://sunholo-data.github.io/ailang/docs/category/language-guide)** - Syntax and features
- **[REPL Guide](https://sunholo-data.github.io/ailang/docs/guides/repl)** - Interactive development
- **[Benchmarks](https://sunholo-data.github.io/ailang/docs/benchmarks/performance)** - AI code generation performance
- **[Examples](https://sunholo-data.github.io/ailang/docs/examples/overview)** - Code examples and patterns

---

## Development

```bash
# Build and install
make install

# Run tests
make test

# Start REPL
make repl

# Run example
make run FILE=examples/hello.ail

# Auto-rebuild on changes
make watch-install

# Check coverage
make test-coverage-badge

# AI Evaluation & Design Generation
make eval-suite          # Run AI benchmarks (AILANG vs Python)
make eval-report         # Generate evaluation report
make eval-analyze        # Analyze failures, generate design docs
```

See the [Development Guide](https://sunholo-data.github.io/ailang/docs/guides/development) for detailed instructions.

---

## 📚 Specification Reference

- **Core**: `/internal/types/`, `/internal/eval/`
- **Effects**: `/internal/effects/`
- **Builtins**: `/internal/builtins/spec.go`
- **Standard Library**: `/stdlib/std/*`
- **Design Docs**: `/design_docs/`

---

## Project Structure

```
ailang/
├── cmd/ailang/         # CLI entry point
├── internal/           # Core implementation
│   ├── repl/           # Interactive REPL
│   ├── lexer/          # Tokenizer
│   ├── parser/         # Parser
│   ├── types/          # Type system
│   ├── eval/           # Evaluator
│   ├── effects/        # Effect system runtime
│   ├── builtins/       # Builtin registry
│   └── eval_harness/   # AI evaluation framework
├── stdlib/             # Standard library
├── examples/           # Example programs
├── docs/               # Documentation
└── design_docs/        # Design documents
```

---

## Contributing

AILANG is an experimental language in active development. Contributions are welcome! Please see the [Development Guide](https://sunholo-data.github.io/ailang/docs/guides/development) for guidelines.

---

## ⚖️ License & Philosophy

AILANG is **open infrastructure for Cognitive DevOps** — systems that write, test, and deploy themselves deterministically.

**Our design north star: build languages AIs enjoy using.**

Apache 2.0 - See [LICENSE](LICENSE) for details.

---

## Acknowledgments

AILANG draws inspiration from:
- **Haskell** (type system, purity)
- **OCaml** (module system, effects)
- **Rust** (capability-based security)
- **Idris/Agda** (reflection and metaprogramming)

---

*For AI agents: This is a deterministic functional language with Hindley-Milner type inference, algebraic effects, and explicit effect tracking. The REPL is fully functional. Module execution works with capability-based security. See [CLAUDE.md](CLAUDE.md) and [Complete Documentation](https://sunholo-data.github.io/ailang/) for exact capabilities.*

---

# Guide: wasm-integration.md

---
id: wasm-integration
title: WebAssembly Integration Guide
sidebar_label: WASM Integration
---

# WebAssembly Integration Guide

AILANG can run entirely in the browser using WebAssembly, enabling interactive demonstrations and online playgrounds without requiring server-side execution.

## Overview

The AILANG WebAssembly build provides:

- **Full Language Support**: Complete AILANG interpreter compiled to WASM
- **Client-Side Execution**: No server needed after initial load
- **Small Bundle Size**: ~5.7MB uncompressed (~1-2MB with gzip)
- **React Integration**: Ready-made component for easy integration
- **Offline Capable**: Works offline after first load

## Quick Start

### 1. Build WASM Binary

```bash
cd ailang
make build-wasm
```

This produces `bin/ailang.wasm`.

### 2. Integration Options

#### Option A: Docusaurus (Recommended)

1. Copy assets:
```bash
cp bin/ailang.wasm docs/static/wasm/
cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" docs/static/wasm/
cp web/ailang-repl.js docs/src/components/
cp web/AilangRepl.jsx docs/src/components/
```

2. Add to `docusaurus.config.js`:
```javascript
module.exports = {
  scripts: [
    {
      src: '/wasm/wasm_exec.js',
      async: false,
    },
  ],
  // ... rest of config
};
```

3. Use in MDX:
```mdx
---
title: Try AILANG
---

import AilangRepl from '@site/src/components/AilangRepl';

<AilangRepl />
```

#### Option B: Vanilla HTML

```html
<!DOCTYPE html>
<html>
<head>
  <title>AILANG REPL</title>
  <script src="wasm_exec.js"></script>
  <script src="ailang-repl.js"></script>
</head>
<body>
  <div id="repl-container"></div>

  <script>
    const repl = new AilangREPL();

    repl.init('/path/to/ailang.wasm').then(() => {
      console.log('AILANG ready!');

      // Evaluate expressions
      const result = repl.eval('1 + 2');
      console.log(result); // "3 :: Int"
    });
  </script>
</body>
</html>
```

#### Option C: React (Custom)

```jsx
import { useEffect, useState } from 'react';
import AilangREPL from './ailang-repl';

export default function MyReplComponent() {
  const [repl, setRepl] = useState(null);
  const [result, setResult] = useState('');

  useEffect(() => {
    const replInstance = new AilangREPL();
    replInstance.init('/wasm/ailang.wasm').then(() => {
      setRepl(replInstance);
    });
  }, []);

  const handleEval = (input) => {
    if (repl) {
      const output = repl.eval(input);
      setResult(output);
    }
  };

  return (
    <div>
      <input onKeyDown={(e) => {
        if (e.key === 'Enter') handleEval(e.target.value);
      }} />
      <pre>{result}</pre>
    </div>
  );
}
```

## JavaScript API

### `AilangREPL` Class

```javascript
const repl = new AilangREPL();
```

#### Methods

##### `init(wasmPath)`

Initialize the WASM module.

```javascript
await repl.init('/wasm/ailang.wasm');
```

**Parameters:**
- `wasmPath` (string): Path to `ailang.wasm` file

**Returns:** Promise that resolves when REPL is ready

##### `eval(input)`

Evaluate an AILANG expression.

```javascript
const result = repl.eval('1 + 2');
// Returns: "3 :: Int"
```

**Parameters:**
- `input` (string): AILANG code to evaluate

**Returns:** Result string (includes value and type)

##### `command(cmd)`

Execute a REPL command.

```javascript
const type = repl.command(':type \x. x');
// Returns: "\x. x :: a -> a"
```

**Parameters:**
- `cmd` (string): REPL command (e.g., `:type`, `:help`)

**Returns:** Command output string

##### `reset()`

Reset the REPL environment.

```javascript
repl.reset();
```

**Returns:** Status message

##### `onReady(callback)`

Register callback for when REPL is ready.

```javascript
repl.onReady(() => {
  console.log('REPL initialized!');
});
```

## REPL Commands

The WebAssembly REPL supports the same commands as the CLI:

| Command | Description |
|---------|-------------|
| `:help` | Show available commands |
| `:type <expr>` | Display expression type |
| `:instances` | Show type class instances |
| `:reset` | Clear environment |

## Limitations

The browser version has these limitations compared to the CLI:

| Feature | CLI | WASM |
|---------|-----|------|
| Expression evaluation | Yes | Yes |
| Type inference | Yes | Yes |
| Pattern matching | Yes | Yes |
| Type classes | Yes | Yes |
| File I/O (`FS` effect) | Yes | No |
| Module imports | Yes | No |
| History persistence | Yes | No |

## Deployment

### Static Hosting

WASM files work on any static host:

```bash
# Build and deploy
make build-wasm
cp bin/ailang.wasm your-site/static/wasm/
# Deploy your-site/ to Netlify/Vercel/GitHub Pages
```

### CDN Optimization

1. **Enable Compression:**
```nginx
# nginx.conf
gzip_types application/wasm;
```

2. **Set Cache Headers:**
```nginx
location ~* \.wasm$ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}
```

3. **Use HTTP/2:**
WASM benefits from HTTP/2 multiplexing for faster loading.

### Performance Tips

- **Lazy Loading**: Only load WASM when user navigates to playground
- **Service Worker**: Cache WASM for offline use
- **CDN**: Serve from edge locations
- **Preload**: Add `<link rel="preload" href="ailang.wasm" as="fetch">`

## CI/CD Integration

### GitHub Actions

WASM is automatically built and released:

```yaml
# .github/workflows/release.yml (excerpt)
- name: Build WASM binary
  run: make build-wasm

- name: Create Release
  uses: softprops/action-gh-release@v2
  with:
    files: bin/ailang-wasm.tar.gz
```

### Docusaurus Deployment

WASM is included in documentation builds:

```yaml
# .github/workflows/docusaurus-deploy.yml (excerpt)
- name: Build WASM binary
  run: make build-wasm

- name: Copy static assets
  run: |
    cp bin/ailang.wasm docs/static/wasm/
    cp web/ailang-repl.js docs/src/components/
```

## Troubleshooting

### "WebAssembly not supported"

**Solution**: Use a modern browser:
- Chrome 57+
- Firefox 52+
- Safari 11+
- Edge 16+

### "Failed to load AILANG WASM"

**Solutions**:
1. Check browser console for network errors
2. Verify `ailang.wasm` path is correct
3. Ensure `wasm_exec.js` loaded first
4. Check CORS headers if serving from different domain

### "REPL not initialized"

**Solution**: Wait for `init()` promise or use `onReady()`:

```javascript
repl.init('/wasm/ailang.wasm').then(() => {
  // Safe to use repl here
  repl.eval('1 + 2');
});
```

### Slow Loading

**Solutions**:
1. Enable gzip compression (reduces to ~1-2MB)
2. Use CDN
3. Add preload hints:
   ```html
   <link rel="preload" href="/wasm/ailang.wasm" as="fetch" crossorigin>
   ```

## Examples

See:
- [Live Playground](/docs/playground) - Try it now
- [Integration Example](https://github.com/sunholo-data/ailang/blob/main/web/example.mdx)
- [Component Source](https://github.com/sunholo-data/ailang/blob/main/web/AilangRepl.jsx)

## Next Steps

- [Try the Playground](/docs/playground)
- [Download Latest Release](https://github.com/sunholo-data/ailang/releases/latest)
- [Report Issues](https://github.com/sunholo-data/ailang/issues)

---

# AI Teaching Prompt (Latest: v0.3.12)

# AILANG AI Teaching Prompt (v0.3.12)

**CRITICAL: You MUST write code in AILANG syntax. This is NOT Python, NOT Rust, NOT JavaScript.**

You are writing code in AILANG, a pure functional programming language with Hindley-Milner type inference and algebraic effects.

## ⚠️ CRITICAL: What AILANG is NOT

**DO NOT generate code like this - these will FAIL:**

❌ **WRONG - Single-line statements without module:**
```
PRINT 5 % 3
```
Every program MUST start with `module benchmark/solution`

❌ **WRONG - Imperative style with loops:**
```python
loop {
  x = read();
  if (x == "") { break; }
  println(x);  # WRONG - no loops in AILANG
}
```
AILANG has NO `loop`, `break`, `while`, `for`. Use recursion!

❌ **WRONG - Python/JavaScript syntax:**
```python
for i in range(10):
    println(i)  # WRONG - no for loops
```
This is not Python. Use functional recursion.

❌ **WRONG - Assignment statements:**
```
x = 10;
x = x + 1;
```
No mutable variables. Use `let` bindings.

**✅ CORRECT - Functional AILANG:**
```ailang
module benchmark/solution

import std/io (println)

export func loop(n: int) -> () ! {IO} {
  if n > 10
  then ()
  else {
    println(show(n));
    loop(n + 1)
  }
}

export func main() -> () ! {IO} {
  loop(1)
}
```

## MANDATORY Structure

**EVERY AILANG program MUST have this structure:**

1. **Module declaration**: `module benchmark/solution` (first line)
2. **Imports**: `import std/io (println)` (if using IO)
3. **Functions**: `export func main() -> () ! {IO} { ... }`

**IMPORTANT SYNTAX RULES:**
- Use `func` NOT `fn`, `function`, or `def`
- Use `type Name[a] = Constructor(a) | Constructor2` NOT `type Name { }` or `enum`
- NO namespace syntax (`::`), just use constructor names directly
- Semicolons REQUIRED between statements in blocks
- Pattern matching uses `=>` NOT `:` or `->`
- NO `for`, `while`, `var`, `const`, `let mut`, or any imperative constructs

## Current Version: v0.3.12 (October 2025)

**✅ WHAT WORKS:**
- ✅ **`show()` function** - NEW v0.3.12: Polymorphic `show(value)` converts ANY value to string! Use for printing numbers, bools, ADTs
- ✅ **Module declarations** - `module path/to/module`
- ✅ **Function declarations** - `export func name(params) -> Type { body }`
- ✅ **Anonymous functions** - `func(x: int) -> int { x * 2 }` (inline lambdas)
- ✅ **Recursive lambdas** - `letrec fib = \n. if n < 2 then n else fib(n-1) + fib(n-2) in ...`
- ✅ **Numeric conversions** - `intToFloat(42)`, `floatToInt(3.14)`
- ✅ **Auto-import std/prelude** - Zero imports needed for comparisons (`<`, `>`, `==`, `!=`)
- ✅ **Record updates** - `{base | field: value}` functional updates
- ✅ **Multi-line ADTs** - Optional leading pipe `type Tree = | Leaf | Node`
- ✅ **Import statements** - `import std/io (println)`, `import std/clock (now, sleep)`, `import std/net (httpGet)`
- ✅ **Pattern matching** - Constructors, tuples, lists, wildcards, **guards** (`if` conditions)
- ✅ **Effect system** - `! {IO, FS, Clock, Net}` for side effects with capability security
- ✅ **ADTs** - Algebraic data types: `type Option[a] = Some(a) | None`
- ✅ **Recursion** - Self-recursive and mutually-recursive functions with stack overflow protection
- ✅ **Block expressions** - `{ stmt1; stmt2; result }` for sequencing
- ✅ **Records** - Record literals, field access, updates, subsumption
- ✅ **Type system fixes** - Modulo operator (`%`) and float comparison (`==`) both work correctly
- ✅ **JSON encoding** - `std/json` module with `Json` ADT and `encode()` function
- ✅ **HTTP headers** - `httpRequest()` with custom headers and Result-based error handling

**⚠️ LIMITATIONS:**
- ⚠️ NO `for`/`while` loops - use recursion
- ⚠️ NO `var` - everything is immutable
- ⚠️ NO error propagation operator `?` (yet)
- ⚠️ NO custom HTTP headers (OpenAI/Claude APIs blocked until v0.4.0)
- ⚠️ NO list spread patterns `[x, ...rest]` (yet) - use Cons constructor
- ⚠️ `show` is a builtin - do NOT import it

## 📋 IMPORT CHECKLIST - Read Before Writing Code!

**NEW in v0.3.6: std/prelude is AUTO-IMPORTED!**

**You NO LONGER need to import Ord or Eq** for comparison operators:

```ailang
module benchmark/solution

import std/io (println)

export func main() -> () ! {IO} {
  if 5 > 3 then println("Works!") else ()  // ✅ NO import needed!
}
```

**Common imports:**
- `println`, `print` → `import std/io (println)`
- `readFile`, `writeFile` → `import std/fs (readFile, writeFile)`
- `now`, `sleep` → `import std/clock (now, sleep)`
- `httpGet`, `httpPost` → `import std/net (httpGet, httpPost)`
- `httpRequest` (NEW) → `import std/net (httpRequest)` for custom headers
- JSON encoding (NEW) → `import std/json (encode, jo, ja, kv, js, jnum)`
- `show` → builtin, **DO NOT IMPORT**
- `<`, `>`, `<=`, `>=`, `==`, `!=` → **AUTO-IMPORTED, NO IMPORT NEEDED!**

**IMPORTANT**: If you see error "No instance for Ord" or "No instance for Eq", you may have set `AILANG_NO_PRELUDE=1`. This is rare - std/prelude is auto-imported by default.

## Module Structure

Every AILANG program must be a module with exported functions:

```ailang
module benchmark/solution

import std/io (println)

export func main() -> () ! {IO} {
  println("Hello, World!")
}
```

**IMPORTANT**: Always use `module benchmark/solution` as the module name for benchmark programs.

## 🆕 NEW in v0.3.12: `show()` Function

**CRITICAL: Use `show()` to convert ANY value to a string!**

The `show()` function is a polymorphic builtin that converts ANY value (int, float, bool, records, ADTs, lists) to a string representation:

```ailang
module benchmark/solution

import std/io (println)

export func main() -> () ! {IO} {
  // ✅ CORRECT - Use show() to convert numbers to strings
  println("Number: " ++ show(42));           // "Number: 42"
  println("Float: " ++ show(3.14));          // "Float: 3.14"
  println("Bool: " ++ show(true));           // "Bool: true"
  println("Result: " ++ show(5 % 3));        // "Result: 2"

  // ✅ Works with ADTs
  let opt = Some(42);
  println("Option: " ++ show(opt));          // "Option: Some(42)"

  // ❌ WRONG - Don't try to concat numbers directly
  println("Number: " ++ 42);                 // ERROR: type mismatch
}
```

**When to use `show()`:**
- Converting numbers (int/float) to strings: `show(42)`, `show(3.14)`
- Converting booleans to strings: `show(true)`
- Converting ADT constructors: `show(Some(42))` → `"Some(42)"`
- Converting lists: `show([1, 2, 3])` → `"[1, 2, 3]"`
- Any time you need to print a non-string value

**Remember:**
- `show()` is a BUILTIN - **DO NOT IMPORT IT**
- Type signature: `show : ∀α. α -> string`
- Always available, no import needed

## Functions

```ailang
-- Simple pure function
export func add(x: int, y: int) -> int {
  x + y
}

-- Function with effects (IO, FS)
export func greet(name: string) -> () ! {IO} {
  println("Hello, " ++ name)
}

-- Generic function
export func identity[a](x: a) -> a {
  x
}

-- Multi-statement body (SEMICOLONS REQUIRED!)
export func compute() -> int {
  let x = 10;
  let y = 20;
  x + y
}
```

## Anonymous Functions

Inline lambda expressions with familiar syntax:

```ailang
-- Anonymous function literal
let double = func(x: int) -> int { x * 2 }

-- With type inference
let add = func(x, y) { x + y }

-- With effects
let greet = func(name: string) -> () ! {IO} {
  println("Hello, " ++ name)
}

-- Higher-order functions
let apply = func(f: func(int) -> int, x: int) -> int { f(x) }
apply(func(n: int) -> int { n * 2 }, 5)  -- 10
```

**IMPORTANT**: Use `=>` for lambdas (`\x. body`), use `-> {` for func expressions.

## Recursive Lambdas

The `letrec` keyword enables recursive function definitions in expressions:

```ailang
-- Fibonacci using letrec
letrec fib = \n. if n < 2 then n else fib(n - 1) + fib(n - 2) in
fib(10)  -- 55

-- Factorial
letrec factorial = \n. if n == 0 then 1 else n * factorial(n - 1) in
factorial(5)  -- 120
```

**Use case**: Recursive functions in REPL or inside expressions without full function declarations.

## Numeric Conversions

Explicit type conversion builtins for int ↔ float:

```ailang
-- Int to Float
intToFloat(42)  -- 42.0

-- Float to Int (truncates towards zero)
floatToInt(3.14)   -- 3
floatToInt(-3.14)  -- -3

-- Mixed arithmetic (requires conversion)
let result = intToFloat(1) + 2.5  -- 3.5
```

**IMPORTANT**: AILANG does NOT do automatic numeric coercion. You MUST use these builtins.

## Block Expressions

Blocks allow sequencing statements with semicolons:

```ailang
export func demo() -> () ! {IO} {
  {
    println("First");
    println("Second");
    println("Third")
  }
}

-- Blocks are expressions - the last value is returned
export func compute() -> int {
  {
    let x = 10;
    let y = 20;
    x + y
  }
}
```

**CRITICAL**: Semicolons REQUIRED between statements! Missing semicolons will cause parse errors.

## Records (with NEW Update Syntax!)

Records are structural types with named fields:

```ailang
-- Record literal
let person = {name: "Alice", age: 30, city: "NYC"}

-- Field access
person.name    -- "Alice"
person.age     -- 30

-- Use in functions
export func describe(p: {name: string, age: int}) -> string {
  p.name ++ " is " ++ show(p.age)
}
```

**NEW in v0.3.6: Record Update Syntax!**

Functional record updates create a new record with specified fields changed:

```ailang
let person = {name: "Alice", age: 30, city: "NYC"};

-- Update one field
let older = {person | age: 31};
-- Result: {name: "Alice", age: 31, city: "NYC"}

-- Update multiple fields
let moved = {older | city: "SF", age: 32};
-- Result: {name: "Alice", age: 32, city: "SF"}

-- Complex base expressions work
let updated = {getRecord() | field: value};
let nested = {config.server | port: 8080};
```

**IMPORTANT**: Updates are immutable - they create NEW records, leaving originals unchanged!

## Algebraic Data Types (ADTs)

**✅ CORRECT AILANG SYNTAX:**

```ailang
type Option[a] = Some(a) | None
type Result[a, e] = Ok(a) | Err(e)
type List[a] = Cons(a, List[a]) | Nil

export func getOrElse[a](opt: Option[a], default: a) -> a {
  match opt {
    Some(x) => x,
    None => default
  }
}
```

**NEW in v0.3.8: Multi-line ADTs with Optional Leading Pipe!**

```ailang
-- Single-line (traditional)
type Tree = Leaf(int) | Node(Tree, int, Tree)

-- Multi-line (NEW - optional leading pipe)
type Tree =
  | Leaf(int)
  | Node(Tree, int, Tree)

-- Also valid (no leading pipe on first variant)
type Tree =
  Leaf(int)
  | Node(Tree, int, Tree)
```

Both styles work identically! Use multi-line for complex ADTs with many variants.

**❌ WRONG - This is Rust/other languages, NOT AILANG:**
```rust
type Option {        // ❌ Wrong - no { } braces
  Some(value)        // ❌ Wrong - not AILANG syntax
  None
}

Option::Some(42)     // ❌ Wrong - AILANG has no :: operator
fn divide(a, b) { }  // ❌ Wrong - use 'func' not 'fn'
```

**✅ CORRECT - Use constructors directly:**
```ailang
Some(42)             // ✅ Correct - no namespace needed
None                 // ✅ Correct
```

## Available Imports

**std/io** - IO operations (requires `! {IO}` effect)
```ailang
import std/io (println, print, readLine)

export func main() -> () ! {IO} {
  println("text")
}
```

**std/fs** - File operations (requires `! {FS}` effect)
```ailang
import std/fs (readFile, writeFile, exists)

export func readData() -> string ! {FS} {
  readFile("data.txt")
}
```

**std/clock** - Time operations (requires `! {Clock}` effect)
```ailang
import std/clock (now, sleep)

export func measureTime() -> () ! {IO, Clock} {
  let start = now();
  sleep(1000);  -- Sleep for 1 second (milliseconds)
  let end = now();
  println("Elapsed: " ++ show(end - start) ++ "ms")
}
```

**std/json** - JSON encoding (NEW v0.3.9)
```ailang
import std/json (encode, jo, ja, kv, js, jnum, jb, jn)

export func buildJSON() -> string ! {} {
  let obj = jo([
    kv("name", js("Alice")),
    kv("age", jnum(30.0)),
    kv("active", jb(true)),
    kv("hobbies", ja([js("reading"), js("coding")]))
  ]);
  encode(obj)  -- Returns: {"name":"Alice","age":30,"active":true,"hobbies":["reading","coding"]}
}
```

**std/net** - HTTP operations (requires `! {Net}` effect)
```ailang
import std/net (httpGet, httpPost)

export func fetchData() -> () ! {IO, Net} {
  let response = httpGet("https://api.example.com/data");
  println(response)
}
```

**std/net (Advanced)** - HTTP with headers (NEW v0.3.9)
```ailang
import std/net (httpRequest, NetError, Transport, InvalidHeader)
import std/json (encode, jo, kv, js)

export func callAPI(apiKey: string) -> () ! {IO, Net} {
  let headers = [
    {name: "Authorization", value: concat_String("Bearer ", apiKey)},
    {name: "Content-Type", value: "application/json"}
  ];
  let body = encode(jo([kv("message", js("Hello"))]));

  match httpRequest("POST", "https://api.example.com/endpoint", headers, body) {
    Ok(resp) =>
      if resp.ok then println(resp.body)
      else println(concat_String("HTTP error: ", show(resp.status)))
    Err(err) => match err {
      Transport(msg) => println(concat_String("Network error: ", msg))
      InvalidHeader(hdr) => println(concat_String("Invalid header: ", hdr))
      -- DisallowedHost, BodyTooLarge also available
    }
  }
}
```

**IMPORTANT:**
- `show` is a BUILTIN function - do NOT import it from std/io!
- Clock and Net have security restrictions (no localhost, private IPs, file:// URLs blocked)
- Run with capabilities: `ailang run --caps IO,FS,Clock,Net --entry main file.ail`

**std/option** - Option type
```ailang
import std/option (Option, Some, None)
```

## Recursion (instead of loops)

Recursion works perfectly in v0.3.8:

```ailang
export func factorial(n: int) -> int {
  if n <= 1
  then 1
  else n * factorial(n - 1)
}

-- Recursion with IO effects and blocks
export func countdown(n: int) -> () ! {IO} {
  if n <= 0 then {
    println("Done!")
  } else {
    println(show(n));
    countdown(n - 1)
  }
}
```

## Recursion Limitation in REPL

**IMPORTANT:** Recursive lambdas are NOT supported in let-bindings:

```ailang
-- ❌ DOES NOT WORK - let bindings cannot be recursive
let fib = \n. if n < 2 then n else fib(n - 1) + fib(n - 2) in fib(10)
-- Error: undefined variable: fib
```

**✅ WORKAROUND:** Use `func` declarations in module files instead:

```ailang
-- In a .ail file:
module examples/fib
export func fib(n: int) -> int {
  if n < 2 then n else fib(n - 1) + fib(n - 2)
}
```

**Why:** Module-level `func` declarations are automatically recursive. The `letrec` keyword does not exist in AILANG's surface syntax.

## Common Mistakes to Avoid

❌ **Don't use for/while loops:**
```ailang
for i in [1, 2, 3] { println(i) }  -- ❌ NOT supported
```

✅ **Use recursion:**
```ailang
export func printAll(xs: [int]) -> () ! {IO} {
  match xs {
    [] => (),
    _ => {
      println(show(head(xs)));
      printAll(tail(xs))
    }
  }
}
```

❌ **Don't forget semicolons in blocks:**
```ailang
{
  println("First")
  println("Second")  -- ❌ Parse error! Missing semicolon
}
```

✅ **Add semicolons between statements:**
```ailang
{
  println("First");
  println("Second")  -- ✅ Last statement doesn't need semicolon
}
```

❌ **Don't import show:**
```ailang
import std/io (println, show)  -- ❌ show not in std/io
```

✅ **show is a builtin:**
```ailang
import std/io (println)
-- show is available automatically
println(show(42))
```

❌ **Don't forget module and export:**
```ailang
func main() {  -- ❌ Missing 'module' declaration and 'export'
  println("hello")
}
```

✅ **Always use module and export:**
```ailang
module benchmark/solution
import std/io (println)

export func main() -> () ! {IO} {
  println("hello")
}
```

## Complete Working Examples

### Example 1: Safe Division with Option
```ailang
module benchmark/solution

import std/io (println)

type Option[a] = Some(a) | None

export func safeDivide(a: float, b: float) -> Option[float] {
  if b == 0.0
  then None
  else Some(a / b)
}

export func printResult(result: Option[float]) -> () ! {IO} {
  match result {
    Some(v) => println("Result: " ++ show(v)),
    None => println("Error: Division by zero")
  }
}

export func main() -> () ! {IO} {
  let r1 = safeDivide(10.0, 2.0);
  printResult(r1);
  let r2 = safeDivide(10.0, 0.0);
  printResult(r2)
}
```

### Example 2: Countdown with Recursion and Blocks
```ailang
module benchmark/solution

import std/io (println)

export func countdown(n: int) -> () ! {IO} {
  if n <= 0 then {
    println("Done!")
  } else {
    println(show(n));
    countdown(n - 1)
  }
}

export func main() -> () ! {IO} {
  countdown(5)
}
```

### Example 3: Records with Update Syntax
```ailang
module benchmark/solution

import std/io (println)

export func main() -> () ! {IO} {
  let alice = {name: "Alice", age: 30, city: "NYC"};

  -- Update age (NEW in v0.3.6!)
  let older = {alice | age: 31};

  -- Update city
  let moved = {older | city: "SF"};

  println(moved.name ++ ", " ++ show(moved.age) ++ ", " ++ moved.city)
}
```

## Summary

**Structure:**
1. Start with `module benchmark/solution` (REQUIRED for benchmarks!)
2. Import what you need from stdlib (`import std/io (println)`)
3. Define exported functions with `export func name(params) -> ReturnType { }`
4. Declare effects with `! {IO, FS}` when using IO/FS operations
5. Use recursion instead of loops - AILANG has NO for/while loops!
6. Use semicolons between statements in blocks

**Remember:**
- ✅ Use `func` NOT `fn`, `function`, or `def`
- ✅ ADTs use `type Name[a] = Cons1(a) | Cons2` syntax (multi-line optional)
- ✅ NO `::` operator - use constructors directly
- ✅ NO for/while loops - use recursion
- ✅ Everything is immutable (no `var` or mutation)
- ✅ Pattern matching uses `=>` arrows, guards work (`if` conditions)
- ✅ Semicolons REQUIRED between statements in blocks
- ✅ `show` is builtin - do NOT import it
- ✅ Records: literals, field access, AND update syntax `{r | field: val}`
- ✅ Effects must be declared: `! {IO}`, `! {FS}`, `! {Clock}`, `! {Net}`, or combinations
- ✅ Modulo operator `%` works: `5 % 3` returns `2`
- ✅ Float comparison works: `0.0 == 0.0` returns `true`
- ✅ std/prelude AUTO-IMPORTED: No need to import Ord/Eq for comparisons!
- ✅ Four effects available: IO (console), FS (files), Clock (time), Net (HTTP)

**If you're not sure, look at the examples above!** They show the exact AILANG syntax.

**v0.3.8 Release Notes (October 2025):**
- **Multi-line ADTs**: Optional leading pipe `type Tree = | Leaf | Node` for better readability
- **Operator lowering fix**: Division operators now resolve correctly (fixes runtime errors)
- **Benchmark improvements**: 49.1% success rate (up from 38.6% in v0.3.7) - +10.5% improvement!
- **Test coverage**: 28.9% (improving steadily)
- All previous features: auto-import std/prelude, record updates, Clock/Net effects, numeric conversions

---

# Examples Status

## Example Status

### Working Examples ✅
- `adt_option.ail`
- `adt_simple.ail`
- `ai_call.ail` ← ✨ NEW (v0.3.9) - OpenAI API integration
- `arithmetic.ail`
- `block_recursion.ail` ← ✨ NEW (v0.3.0-alpha2)
- `claude_haiku_call.ail` ← ✨ NEW (v0.3.9) - Anthropic API integration
- `demos/adt_pipeline.ail` ← ✅ FIXED (M-R5 Day 1)
- `demos/hello_io.ail`
- `effects_basic.ail`
- `effects_pure.ail`
- `guards_basic.ail`
- `hello.ail`
- `micro_block_if.ail` ← ✨ NEW (v0.3.0-alpha2)
- `micro_block_seq.ail` ← ✨ NEW (v0.3.0-alpha2)
- `micro_io_echo.ail` ← ✅ FIXED (M-R5 Day 1)
- `micro_option_map.ail` ← ✅ FIXED (M-R5 Day 1)
- `micro_record_person.ail` ← ✨ NEW (v0.3.0-alpha3 M-R5 Day 3)
- `recursion_error.ail`
- `recursion_factorial.ail`
- `recursion_fibonacci.ail`
- `recursion_mutual.ail`
- `recursion_quicksort.ail`
- `showcase/01_type_inference.ail`
- `showcase/02_lambdas.ail`
- `showcase/03_type_classes.ail`
- `showcase/04_closures.ail`
- `simple.ail`
- `test_effect_annotation.ail`
- `test_effect_capability.ail`
- `test_effect_fs.ail`
- `test_effect_io.ail`
- `test_exhaustive_bool_complete.ail`
- `test_exhaustive_bool_incomplete.ail`
- `test_exhaustive_wildcard.ail`
- `test_guard_bool.ail`
- `test_guard_debug.ail`
- `test_guard_false.ail`
- `test_import_ctor.ail` ← ✅ FIXED (M-R5 Day 1)
- `test_import_func.ail` ← ✅ FIXED (M-R5 Day 1)
- `test_invocation.ail`
- `test_io_builtins.ail`
- `test_module_minimal.ail`
- `test_no_import.ail`
- `test_record_subsumption.ail` ← ✨ NEW (v0.3.0-alpha3 M-R5 Day 3)
- `test_single_guard.ail`
- `test_use_constructor.ail` ← ✅ FIXED (M-R5 Day 1)
- `test_with_import.ail`
- `type_classes_working_reference.ail`
- `v3_3/imports.ail` ← ✅ FIXED (M-R5 Day 1)
- `v3_3/imports_basic.ail` ← ✅ FIXED (M-R5 Day 1)

### Failing Examples ❌
- `demos/effects_pure.ail`
- `experimental/ai_agent_integration.ail`
- `experimental/concurrent_pipeline.ail`
- `experimental/factorial.ail`
- `experimental/quicksort.ail`
- `experimental/web_api.ail`
- `lambda_expressions.ail`
- `list_patterns.ail`
- `patterns.ail`
- `records.ail`
- `showcase/03_lists.ail`
- `test_effect_io_simple.ail`
- `typeclasses.ail`
- `v3_3/math/gcd.ail`

### Skipped Examples ⏭️
- `block_demo.ail`
- `option_demo.ail`
- `stdlib_demo.ail`
- `stdlib_demo_simple.ail`

**Summary:** 50 passed, 14 failed, 4 skipped (Total: 68)

**Recent improvements:**
- ✅ **v0.3.9 (Oct 2025)**: 2 new AI API integration examples!
  - `ai_call.ail`: OpenAI GPT-4o-mini integration with JSON encoding
  - `claude_haiku_call.ail`: Anthropic Claude Haiku integration (verified with real API)
- ✅ **M-R5 (v0.3.0-alpha3)**: 11 examples fixed/added via records & row polymorphism!
  - Day 1: 9 examples fixed (demos/adt_pipeline, micro_io_echo, micro_option_map, test_import_ctor, test_import_func, test_use_constructor, v3_3/imports, v3_3/imports_basic)
  - Day 3: 2 new examples (micro_record_person, test_record_subsumption)
- ✅ **M-R8 (v0.3.0-alpha2)**: `micro_block_*.ail`, `block_recursion.ail` (3 files) - Block expressions with recursion
- ✅ **M-R4 (v0.3.0-alpha1)**: `recursion_*.ail` (5 files) - Recursion support with RefCell indirection

---