# Mapanare v5.13.0 > Mapanare is an AI-native compiled programming language where agents, signals, streams, and tensors are first-class language primitives — not libraries. ~328x faster than Python. Parity with Rust (1.003x geomean) and on par with C. ## Overview Mapanare compiles to native binaries via LLVM (production) and WebAssembly (browser/server). It features a self-hosted compiler written in Mapanare itself (38,000+ lines of .mn across 10 modules). 66/66 native goldens through mnc-stage1. 5,800+ tests passing. No Python required at runtime. Website: https://mapanare.dev GitHub: https://github.com/Mapanare-Research/Mapanare Discord: https://discord.gg/5hpGBm3WXf License: MIT ## Key Features - **Agents**: Concurrent actors with typed input/output channels, lifecycle management, supervision, and backpressure. Native LLVM backend uses OS threads with lock-free SPSC ring buffers. Keywords: `agent`, `spawn`, `sync`, `<-`. - **Signals**: Reactive state with automatic dependency tracking, computed values, subscribers, and batched updates. Keywords: `signal`, `computed`, `batch`. - **Streams**: Async pipelines with the `|>` pipe operator. Adjacent map/filter operations fuse automatically into a single pass. 14 operators: map, filter, take, skip, collect, fold, and more. - **Tensors**: N-dimensional arrays with compile-time shape validation. The `@` operator performs matrix multiplication with shape checking at compile time. - **GPU Compute**: CUDA and Vulkan via dlopen (no compile-time SDK dependency). `@gpu`, `@cuda`, `@vulkan` annotations for automatic dispatch. Built-in tensor kernels (add, sub, mul, div, matmul). - **WebAssembly**: Compile to WAT/WASM for browser and server-side execution. WASI preview 1 support (file I/O, environment, clock, random). JS bridge for DOM access and event handling. - **AI Stdlib**: LLM drivers (OpenAI, Anthropic, local), embedding providers with batching and caching, RAG pipelines with document chunking and vector store. - **Database Drivers**: SQLite, PostgreSQL, Redis, embedded KV, connection pooling, schema migrations. Native C runtime for SQLite3 and PostgreSQL via dlopen. - **Data Engine (Dato)**: Tables, aggregations, joins, null handling, reshape, CSV/JSON I/O. - **Encoding**: Full TOML and YAML parsers/serializers. - **Web & Security**: Web crawler (robots.txt, URL frontier, content extraction), vulnerability scanner (template-driven, fingerprinting), HTTP fuzzer (mutation engine), HTTP server toolkit (auth, body parsing, cookies, sessions, rate limiting, SSE, templates). - **Traits**: Generic abstractions over types with trait bounds on generics. Builtin traits: `Display`, `Eq`, `Ord`, `Hash`. Keywords: `trait`, `impl Trait for Type`. - **Modules**: File-based module resolution with `pub` visibility enforcement and circular import detection. Keywords: `import`, `pub`, `export`. - **No OOP**: No classes, no inheritance. Structs, enums, and pattern matching instead. - **Native compilation**: Compile to native binaries via LLVM (22-63x faster than Python), WebAssembly, or Python (deprecated). - **Type system**: Static typing with inference, generics, trait bounds, Option, Result, and `?` error propagation. 25-kind TypeKind enum. - **Arena memory**: Arena-based allocation for the LLVM backend with tag-bit heap string detection. No GC. ASan/TSan clean. - **Self-hosted compiler**: 38,000+ lines of Mapanare across 10 modules (ast, lexer, parser, semantic, mir, lower_state, lower, emit_llvm_ir, emit_llvm, main). 66/66 native goldens (first time in project history at v5.7.0). 3-stage fixed-point: NEAR (4-line VERSION-metadata diff). Real LLVM coroutines for async/await. Tensor literals + multi-dim indexing + broadcast + slicing + reductions. Closure-typed parameters. Or-patterns with built-in constructors. - **Native stdlib**: 25+ modules written in .mn — AI, databases, encoding, filesystem, GPU, WASM, HTTP, and more — all compile natively via LLVM. - **Built-in test runner**: `mapanare test` discovers `@test` functions, `assert` statement, `--filter` flag. - **Observability**: OpenTelemetry tracing (`--trace`), Prometheus metrics (`--metrics`), structured error codes (`MN-X0000`). - **DWARF debug info**: `mapanare build -g` produces debuggable binaries with source mapping. ## Installation ```bash pip install mapanare # or curl -fsSL https://mapanare.dev/install | bash ``` ## Quick Example ```mn agent Classifier { input text: String output label: String fn handle(text: String) -> String { return "positive" } } fn main() { let cls = spawn Classifier() cls.text <- "Mapanare is fast" let result = sync cls.label print(result) } ``` ## CLI Commands - `mapanare run ` — Compile and run - `mapanare build ` — Compile to native binary via LLVM - `mapanare check ` — Type-check only - `mapanare compile ` — Transpile to Python (deprecated) - `mapanare emit-llvm ` — Emit LLVM IR - `mapanare emit-mir ` — Emit MIR - `mapanare emit-wasm ` — Emit WebAssembly (WAT/WASM) - `mapanare test [path]` — Run @test functions - `mapanare lint ` — Lint source code - `mapanare fmt ` — Format source code - `mapanare doc ` — Generate documentation - `mapanare deploy ` — Generate deployment scaffold - `mapanare init` — Create new project scaffold - `mapanare targets` — List supported compilation targets ## Primitive Types Int, Float, Bool, String, Char, Void, Option, Result, List, Map, Tensor, Signal, Stream, Channel ## Stdlib Modules (written in .mn) ### AI - `ai/llm.mn` (1,708 lines) — LLM driver with provider abstraction (OpenAI, Anthropic, local), streaming, tool calls - `ai/embedding.mn` (925 lines) — Embedding provider with batching, caching, similarity search - `ai/rag.mn` (485 lines) — RAG pipeline with document chunking, vector store, retrieval ### Database - `db/sql.mn` (328 lines) — SQL query builder and execution - `db/sqlite.mn` (280 lines) — SQLite driver via native C runtime - `db/postgres.mn` (478 lines) — PostgreSQL driver via native C runtime - `db/redis.mn` (307 lines) — Redis client - `db/kv.mn` (217 lines) — Key-value store abstraction - `db/pool.mn` (247 lines) — Connection pooling - `db/migrate.mn` (328 lines) — Schema migration runner ### Encoding - `encoding/json.mn` (982 lines) — Recursive descent JSON parser, encoder, pretty-printer, SAX streaming - `encoding/csv.mn` (330 lines) — RFC 4180 parser/writer, configurable delimiters - `encoding/toml.mn` (1,902 lines) — Full TOML parser and serializer - `encoding/yaml.mn` (2,121 lines) — Full YAML parser and serializer ### Filesystem - `fs.mn` (658 lines) — Read, write, walk, glob, metadata, temp files ### GPU - `gpu/device.mn` (242 lines) — GPU device detection and selection (CUDA/Vulkan) - `gpu/kernel.mn` (235 lines) — Kernel management and dispatch - `gpu/tensor.mn` (699 lines) — GPU-accelerated tensor operations ### Networking - `net/http.mn` (1,103 lines) — HTTP/1.1 client, URL parser, redirects, chunked transfer - `net/http/server.mn` (600 lines) — HTTP server, route matching, middleware, static files - `net/http/auth.mn` (189 lines) — Authentication middleware - `net/http/body.mn` (529 lines) — Body parsing (JSON, form, multipart) - `net/http/cookie.mn` (234 lines) — Cookie parsing and serialization - `net/http/session.mn` (223 lines) — Session management - `net/http/ratelimit.mn` (172 lines) — Rate limiting middleware - `net/http/sse.mn` (149 lines) — Server-Sent Events - `net/http/template.mn` (700 lines) — Template rendering engine - `net/websocket.mn` (1,120 lines) — RFC 6455 WebSocket (client + server), handshake, framing ### Security & Crypto - `crypto.mn` (283 lines) — SHA-1, SHA-256, HMAC, Base64, random, JWT helpers - `text/regex.mn` (271 lines) — PCRE2 FFI, match, search, replace, split ### WebAssembly - `wasm/bridge.mn` (487 lines) — JavaScript interop: imports, exports, DOM access, events - `wasm/runtime.mn` (307 lines) — WASI preview 1: file I/O, environment, clock, random ## Ecosystem Packages - **Dato** — DataFrame/data analysis engine (tables, aggregations, joins, null handling, reshape, CSV/JSON I/O) - **Crawl** — Web crawler with robots.txt, URL frontier, content extraction, persistence - **Scan** — Template-driven vulnerability scanner with fingerprinting and report generation - **Fuzz** — HTTP fuzzer with mutation engine and wordlist generation ## Documentation Pages - Getting Started: https://mapanare.dev/docs/getting-started - Variables & Mutability: https://mapanare.dev/docs/variables - Functions & Lambdas: https://mapanare.dev/docs/functions - Control Flow: https://mapanare.dev/docs/control-flow - Structs & Enums: https://mapanare.dev/docs/structs-enums - Type System: https://mapanare.dev/docs/type-system - Error Handling: https://mapanare.dev/docs/error-handling - Operators: https://mapanare.dev/docs/operators - Modules & Imports: https://mapanare.dev/docs/modules - Traits: https://mapanare.dev/docs/traits - Decorators: https://mapanare.dev/docs/decorators - Agents: https://mapanare.dev/docs/agents - Signals: https://mapanare.dev/docs/signals - Streams: https://mapanare.dev/docs/streams - Tensors: https://mapanare.dev/docs/tensors - Pipes: https://mapanare.dev/docs/pipes - CLI Reference: https://mapanare.dev/docs/cli - Standard Library: https://mapanare.dev/docs/standard-library - Benchmarks: https://mapanare.dev/benchmarks ## Performance Cross-language geomean: Mapanare/Rust 1.003x (essentially parity), Mapanare/C gcc 0.96x, ~328x faster than Python. | Benchmark | MN (Native) | Python | Go | Rust | vs Python | |-----------|-------------|--------|----|------|-----------| | Fibonacci (n=40) | 0.174s | 7.230s | 0.210s | 0.148s | 42x | | Enum Match (10M) | 1.47ms | — | — | 1.50ms | 0.98x Rust | | String Concat (10K) | 0.077ms | — | — | 0.038ms | 2.04x Rust | | Quicksort (10K) | 1.10ms | — | — | 0.37ms | 2.99x Rust | | Async Scheduler | 1.14ms | — | 1.34ms | — | 0.85x Go | | Collatz Explorer (5M) | 0.081s | 5.546s | — | — | 69x | | Prime Sieve (2M) | 0.035s | 1.038s | — | — | 35x | ## What's New in v5.13.0 Post-v5.8.0 the arc shifted from language features to platform + packaging hygiene. The compiler internals are unchanged from v5.8.0; what changed is everything users land on. - **9.62/10 panel score** at the v5.11.0 review (Pk.* packaging-hygiene health gate, Option A — point-release health gate clears) — −0.04 micro-regression from v5.8.0 driven by README/version-badge drift, closed in v5.13.0 - **Strict 3-stage fixed-point** restored at v5.9.0 (226,603 lines / 0 diff) and held through 5 consecutive releases — first strict-preserving streak since v4.139.0 - **Bundled LLVM toolchain on Windows** (Win.1b, v5.10.0): default `mapanare-${V}-win-x64.zip` ships clang.exe + lld-link.exe + LLVM-C.dll + compiler-rt under `mapanare/llvm/` — clean-machine `mnc run` and `mnc build` work without a system clang. Opt-out via `MAPANARE_NO_BUNDLED_LLVM=1` selects `mapanare-${V}-win-x64-minimal.zip` (~10 MB) - **Native CLI hygiene** (DX.*, v5.9.0–v5.9.1): `mnc --help` works, `mnc version` prints the real version (no `__MN_VERSION__` placeholder leak), missing-clang prints platform-specific install instructions, `mnc cache stats` / `cache clean` work on Windows, **`mnc ` defaults to compile + run** (BREAKING — new `mnc emit-llvm` keeps the IR-emission path) - **Full Windows ABI coverage** (Wb.1 / Wb.2 / We.1, v5.8.3–v5.8.6): SysV/AAPCS64 + Win64 sret/sarg + i686-w64-mingw32 cdecl sret/byval — fixes silent miscompile of `{ptr,i64}` returns on i686 via LLVM's eax:edx packing - **Apple AArch64 sret return** (Da.1, v5.8.8) — closes the macOS arm64 ABI gap - **Versioned release-artifact filenames** (Pk.1, v5.11.0): `mapanare-5.13.0-win-x64.zip`, `mnc-5.13.0-linux-x64`, etc., driven by `VERSION`. Installers probe versioned name first with legacy fallback for pre-v5.11 releases - **66/66 native goldens** through mnc-stage1 — preserved since v5.7.0 - **Real LLVM coroutines** for async/await/block_on with `presplitcoroutine` + `@llvm.coro.id/begin/save/suspend/end` and scheduler-driven suspension (Sh.4, v5.5) - **Tensors in self-hosted compiler**: literals, multi-dim indexing (`a[i, j]`), NumPy-style broadcasting, wildcard slicing (`a[0..2, _]`), reductions (`sum`/`mean`/`max`/`min`/`argmax`/`argmin`) (Sh.6, v5.6) - **Closure-typed parameters**: `fn apply(f: fn(Int) -> Int, x: Int)` and multi-param lambdas `(a, b) => a + b` (Sh.7, v5.7) - **Or-pattern matching with guards** over built-in `None`/`Some`/`Ok`/`Err` constructors - **Drop-glue ownership tracking** for strings, lists, boxed enums, and tensors — valgrind 0 errors, ASan/LSan/TSan clean - **Package manager**: `mapanare install pkg@1.0.0` from the mapanare.dev registry, lockfile, semver - 5,800+ tests passing, 0 flaky across 5x sequential audits - Mapanare/Rust geomean: 1.003x (essentially parity, was 1.17x at v5.0.0) - Mapanare/Python: 328x faster (was 168x at v5.0.0) ## Full Documentation For complete documentation with all code examples, see: https://mapanare.dev/llms-full.txt ## Contact Created by Juan Denis — https://juandenis.com