# Aura

> Aura is a compiled, statically typed programming language with Python-inspired syntax, deterministic ownership, native execution, and no garbage collector. Its current focus includes reliable applications, agents, and ML infrastructure; its long-term goal is a general-purpose systems language for every type of software, including operating systems and device drivers.

## Project

- [Aura](https://github.com/johnolafenwa/Aura#readme): Aura is a compiled, statically typed programming language designed for reliable software. It combines Python-inspired readability with deterministic ownership, structured concurrency, typed failure, native executables, and no garbage collector.
- [Aura](https://johnolafenwa.github.io/Aura): Aura brings familiar source code to a compiled, statically typed language. Its indentation-based syntax is easy to read, while compiler checks cover types, ownership, mutation, exhaustive matching, failure handling, and task boundaries. Programs build as native executables with deterministic cleanup and no garbage collector.
- [Why Aura](https://johnolafenwa.github.io/Aura/positioning): Aura 0.3.2 is a technical preview of a compiled, statically typed programming language for reliable software. It combines Python-inspired syntax, deterministic ownership, structured concurrency, typed failure, and native executables.
- [Downloads](https://johnolafenwa.github.io/Aura/downloads): Aura 0.3.2 is a technical preview. The compiler, command-line tools, editor extension, reference manual, and source are distributed from the [Aura GitHub repository](https://github.com/johnolafenwa/Aura).

## Install Aura

- [Install Aura](https://johnolafenwa.github.io/Aura/install): Aura 0.3 is distributed as a self-contained command-line tool with its private native runtime. Choose the guide for the operating system where `aura` will run:
- [Install Aura On Linux](https://johnolafenwa.github.io/Aura/install/linux): The Aura 0.3 preview supports x86-64 Ubuntu 24.04 and compatible glibc-based Linux distributions. The release does not currently include Linux ARM64 or musl archives.
- [Install Aura On macOS](https://johnolafenwa.github.io/Aura/install/macos): Aura publishes separate macOS 15 archives for Apple silicon and Intel. The installer uses `uname` to select the correct archive.
- [Install The VS Code Extension](https://johnolafenwa.github.io/Aura/install/vscode): The **Aura Programming Language** extension provides `.au` syntax highlighting, indentation, snippets, diagnostics, completion, hover, go-to-definition, and document symbols.
- [Install Aura On Windows With WSL](https://johnolafenwa.github.io/Aura/install/windows-wsl): Aura does not publish a native Windows executable. On an x86-64 Windows 11 machine, install and run the Linux release inside Windows Subsystem for Linux 2 using Ubuntu 24.04. The CLI, compiler runtime, projects, and VS Code language server all run inside WSL 2.

## Language Manual

- [Aura Language Reference](https://johnolafenwa.github.io/Aura/manual): The source version for this Manual is **Aura 0.3.2 (technical preview)**. The release stamp below records the rendered implementation baseline commit.
- [API Index](https://johnolafenwa.github.io/Aura/manual/api-index): This page indexes every maintained public builtin constant, function, method, module type, and builtin enum documented by the manual. It is intentionally dense. Use the linked manual pages for examples and longer discussion.
- [Assertions](https://johnolafenwa.github.io/Aura/manual/assertions): An assertion states an invariant that must hold for execution to continue. Assertions are for programmer errors and internal consistency, not recoverable input or protocol failures. Use a typed `Result` when a caller should be able to handle the outcome.
- [Bytes, Text Codecs, And SHA-256](https://johnolafenwa.github.io/Aura/manual/bytes): Aura represents an owned sequence of bytes as `list[uint8]`. There is no separate `Bytes` nominal type and no implicit conversion between text and bytes. UTF-8 conversion is available on `str`; hexadecimal, base64, and SHA-256 operations live in the built-in `bytes` module.
- [Classes](https://johnolafenwa.github.io/Aura/manual/classes): Classes define nominal product types: one value contains a fixed set of named fields and exposes class methods. Ordinary classes are move types unless declared `copy class`.
- [CLI And Tooling](https://johnolafenwa.github.io/Aura/manual/cli-and-tooling): The `aura` CLI is the product surface for checking, running, building, inspecting, and editor integration.
- [Closures](https://johnolafenwa.github.io/Aura/manual/closures): Aura closures use `lambda parameters: expression`. They are small expression-bodied callable values. Parameter types come from context; a zero-parameter lambda may infer its result type from its body. Captures are always by value: Copy values are copied and owned non-Copy values are moved when the closure is created.
- [Collections](https://johnolafenwa.github.io/Aura/manual/collections): Aura provides three generic owned collection types:
- [Concurrency](https://johnolafenwa.github.io/Aura/manual/concurrency): Aura provides pinned-worker scheduler-backed lightweight tasks, structured task groups, queues, task handles, cancellation checks, sleeping, and typed single- and multi-source wait helpers. Scheduler waits use a persistent event reactor: descriptors stay registered, deadlines live in a timer heap, and Queue, task-completion, and blocking-pool events notify the responsible worker directly.
- [Conformance](https://johnolafenwa.github.io/Aura/manual/conformance): Aura keeps the language reference and implementation aligned through executable conformance layers. This page identifies which tests substantiate each part of the specification and what a conforming implementation is expected to do.
- [Control-Plane Modules](https://johnolafenwa.github.io/Aura/manual/control-plane): Aura 0.3 includes a small, typed host/control-plane surface intended for service launchers, workers, evaluation harnesses, and agent infrastructure. These modules behave the same through `aura run` and direct native binaries.
- [Current Limits](https://johnolafenwa.github.io/Aura/manual/current-limits): This page documents known current limits of the Aura compiler and runtime.
- [Diagnostics](https://johnolafenwa.github.io/Aura/manual/diagnostics): Aura diagnostics are part of the language and tooling contract. Lexing, parsing, static checking, ownership checking, lowering, building, and runtime traps all use the compiler-owned diagnostic structure described here. A typed library failure such as `Result.Err`, `Option.None`, a timeout, cancellation, or an `io.Error` value is ordinary program data, not a diagnostic.
- [Enums And Pattern Matching](https://johnolafenwa.github.io/Aura/manual/enums-and-match): Enums define nominal sum types. Each value contains exactly one declared variant and, when that variant has payloads, one value for each payload position. Pattern matching evaluates a scrutinee once, selects the first matching arm, and binds payload values for that arm.
- [Execution Model](https://johnolafenwa.github.io/Aura/manual/execution-model): Aura source is statically checked, lowered, and executed with deterministic single-expression sequencing plus scheduler-controlled concurrency and external I/O. This chapter defines observable behavior shared by `aura run` and built programs.
- [Expressions](https://johnolafenwa.github.io/Aura/manual/expressions): An expression evaluates to a value. This chapter defines the reader-facing expression contract: available forms, grouping, precedence, evaluation order, and the main static restrictions. The exact productions and specialization/indexing disambiguation are normative in [Grammar](/manual/grammar#expressions-and-precedence). Type rules are centralized in [Static Semantics](/manual/static-semantics#expression-typing), and runtime behavior is centralized in [Execution Model](/manual/execution-model#evaluation-order).
- [Foreign Function Interface (FFI) v0](https://johnolafenwa.github.io/Aura/manual/ffi): Aura FFI v0 calls a deliberately small subset of the platform C ABI. It is an unsafe package capability for binding trusted, already-loaded native symbols; it is not a general dynamic-library, pointer, or callback system.
- [Filesystem Module](https://johnolafenwa.github.io/Aura/manual/filesystem): The `fs` module provides one-shot helpers for common file operations and an owned `fs.File` resource for handle-based workflows.
- [Functions](https://johnolafenwa.github.io/Aura/manual/functions): Functions are module-level declarations introduced by `def`. Their callable contracts fix the parameter names, parameter passing modes, parameter types, generic parameters and bounds, return behavior, and any inferred clone-safety obligations used at every call site.
- [Generics And Traits](https://johnolafenwa.github.io/Aura/manual/generics-and-traits): Generics parameterize declarations over types. Traits are nominal interfaces used for generic bounds, method dispatch, operator dispatch, supertrait requirements, and `try` error conversion.
- [Grammar](https://johnolafenwa.github.io/Aura/manual/grammar): This chapter defines the complete source grammar of Aura 0.3. The grammar is normative after lexical token formation. Static restrictions—types, visibility, ownership, exhaustiveness, valid receivers, and API-specific rules—are defined by [Static Semantics](/manual/static-semantics).
- [I/O Module](https://johnolafenwa.github.io/Aura/manual/io): The `io` module covers standard input/output and the common error enum shared by filesystem and networking APIs.
- [JSON Module](https://johnolafenwa.github.io/Aura/manual/json): Aura's `json` module represents arbitrary JSON data with one recursive enum. Parsing reports malformed or unsupported input as typed data; dumping produces one deterministic JSON string or traps when the supplied value cannot satisfy the serializer contract.
- [Language Specification](https://johnolafenwa.github.io/Aura/manual/language-specification): This Manual is the normative specification of the implemented Aura 0.3 development language. It defines the source language, static rules, ownership model, execution behavior, maintained runtime APIs, package model, and tool contracts that a conforming implementation must provide.
- [Lexical Structure](https://johnolafenwa.github.io/Aura/manual/lexical-structure): This chapter defines how Aura source text becomes tokens and indentation markers. It is normative for source spelling. The complete token-level productions are collected in [Grammar](/manual/grammar); name binding and reserved builtin names are defined by [Names And Scopes](/manual/names-and-scopes) and [Static Semantics](/manual/static-semantics).
- [Math Module](https://johnolafenwa.github.io/Aura/manual/math): The `math` module provides exact binary64 constants plus scalar `float64` rounding, exponentiation, exponential, logarithmic, and trigonometric functions. Every function input is explicitly `float64`; the module performs no implicit numeric conversion.
- [Names And Scopes](https://johnolafenwa.github.io/Aura/manual/names-and-scopes): Aura resolves names statically. A name denotes a local binding, parameter, pattern payload, type parameter, module, function, class, enum, trait, enum variant through a qualified path, or maintained builtin. Name resolution never falls back to dynamic lookup.
- [Network Module](https://johnolafenwa.github.io/Aura/manual/network): The `net` module exposes scheduler-aware networking resources:
- [Numeric Arrays](https://johnolafenwa.github.io/Aura/manual/numeric-arrays): `Array[T]` is Aura's owned contiguous CPU numeric container. It is intended for local preprocessing, postprocessing, evaluation, and batch-shaped numeric work. It is smaller than a general tensor framework: shape is runtime metadata, storage is row-major and host-only, and results own their buffers.
- [Ownership And Borrowing](https://johnolafenwa.github.io/Aura/manual/ownership-and-borrowing): Aura statically tracks whether an operation copies, moves, shares, or mutates a value. The rules apply to local bindings, parameters, method receivers, fields, supported indexed operations, collection iteration, pattern matching, task starts, and resources.
- [Packages](https://johnolafenwa.github.io/Aura/manual/packages): An Aura package is a directory containing `Aura.toml` and a `src/` source root. The package graph determines module paths, dependency import prefixes, git revisions, and the owner of `Aura.lock`.
- [Performance](https://johnolafenwa.github.io/Aura/manual/performance): Aura tracks performance with reproducible programs, named hardware, pinned source commits, raw observations, and content hashes. The current measurements show where the compiler and runtime are already competitive and where later releases need focused optimization.
- [Process Module](https://johnolafenwa.github.io/Aura/manual/process): The `process` module runs child processes without a shell by default. Commands are explicit `list[str]` argv values. That means `["/bin/echo", "hello world"]` runs exactly one executable with one argument; Aura does not split strings or expand shell syntax.
- [Randomness Module](https://johnolafenwa.github.io/Aura/manual/randomness): Aura separates reproducible pseudo-random streams from security-sensitive operating-system randomness. Import `random`, construct an explicitly seeded `random.Rng` when results must repeat, and use the module's `secure_*` functions only when results must be unpredictable.
- [Statements](https://johnolafenwa.github.io/Aura/manual/statements): Statements introduce and update bindings, control execution, or evaluate an expression for its effects. This chapter defines their legality and observable flow. Exact syntax is normative in [Grammar](/manual/grammar#suites-and-statements), compile-time legality in [Static Semantics](/manual/static-semantics), and runtime sequencing and cleanup in [Execution Model](/manual/execution-model).
- [Static Semantics](https://johnolafenwa.github.io/Aura/manual/static-semantics): Static semantics are the rules applied after parsing and module loading and before MIR lowering or native code generation. A module is well typed only if every declaration, statement, expression, pattern, call, move, and borrow satisfies these rules.
- [Status And Compatibility](https://johnolafenwa.github.io/Aura/manual/status-and-compatibility): Aura 0.3 is an advanced technical preview. It is suitable for compiler and runtime evaluation, examples, and controlled experiments. It is not a production systems-language release or a security boundary for untrusted programs.
- [Tuples](https://johnolafenwa.github.io/Aura/manual/tuples): Tuples are fixed-size, heterogeneous product values. Aura's minimal tuple surface is intended for returning, passing, unpacking, and pattern-matching a known number of values. Tuples are not variable-size collections.
- [Types](https://johnolafenwa.github.io/Aura/manual/types): Aura is statically typed. Every expression has a type, and type annotations are part of the public shape of functions, fields, methods, and many empty literals.

## Learn Aura

- [Learn Aura](https://johnolafenwa.github.io/Aura/learn): This book teaches Aura the way a programmer tends to actually learn a language: by writing short programs that do something real, then extending them until the pieces fit together.
- [Converting Between Types](https://johnolafenwa.github.io/Aura/learn/casting): Aura never converts a number behind your back. An `int32` does not quietly become an `int64`, and an integer does not drift into a float because it was convenient. Every conversion is written down, and there are three ways to write one.
- [Working With Collections](https://johnolafenwa.github.io/Aura/learn/collections): Aura uses `list[T]`, `dict[K, V]`, and `set[T]`. Each collection has one exact static element shape, deterministic ownership, and explicit absence.
- [Structured Concurrency](https://johnolafenwa.github.io/Aura/learn/concurrency): Concurrent programs get hard to reason about when child work has no parent. A task started deep inside a function might run forever, fail silently, or leak a resource. The fix Aura builds into the language is called **structured concurrency**: every task is created within a scope, and leaving that scope waits for, cancels, or otherwise accounts for the children.
- [Shaping Data](https://johnolafenwa.github.io/Aura/learn/data-modeling): Most programs get easier to read once the data has names. A loose bag of strings and integers becomes a `Job` with an `id`, a `queue`, and an `attempts` counter. A value that is "sometimes a number and sometimes an error" becomes a `Result` with two variants. Shared behaviour lives on the type.
- [Calling A Small C API](https://johnolafenwa.github.io/Aura/learn/ffi): Aura's FFI v0 is for small, reviewed bindings to trusted C symbols that are already visible in the running process. It deliberately does not expose raw pointers or arbitrary library loading.
- [Aura For Python Developers](https://johnolafenwa.github.io/Aura/learn/from-python): Most of what you know transfers. Indentation, `def`, `class`, f-strings, comprehensions, keyword arguments, `for x in items` — all of it works the way you expect. This chapter is about the parts that do not, so the compiler stops surprising you by the end of the page.
- [Getting Aura Running](https://johnolafenwa.github.io/Aura/learn/install-and-run): Aura release archives ship a command-line tool called `aura` plus its private native runtime under `lib/aura`. The tool parses, type-checks, runs, and builds Aura source files, and it also serves as the entry point for editor tooling.
- [Talking To The World](https://johnolafenwa.github.io/Aura/learn/io-process-networking): Programs eventually need to speak to something outside themselves — a file, a subprocess, a socket, a supervised service. Aura exposes that surface through four built-in modules: `io` for standard streams, `fs` for files and directories, `process` for subprocesses and supervisors, and `net` for sockets, HTTP, and WebSockets.
- [Organizing Code](https://johnolafenwa.github.io/Aura/learn/modules-and-packages): A single-file program is a fine way to start. At some point, though, helper types want a home, public APIs want to be marked as such, and dependencies want to be named somewhere the compiler can read them. That is what Aura's module and package system is for.
- [Running And Shipping](https://johnolafenwa.github.io/Aura/learn/native-builds): Aura has two execution paths: the MIR runtime behind `aura run`, and the native code generator behind `aura build`. They target the same language surface and are exercised by the same test suite, but they fit slightly different moments in a project.
- [Values, Moves, And Borrows](https://johnolafenwa.github.io/Aura/learn/ownership-and-borrowing): This is the central chapter of the book. Almost everything in Aura — how functions receive data, how collections hold it, how tasks share it, how resources get cleaned up — follows from the rules introduced here.
- [Results, Options, And `try`](https://johnolafenwa.github.io/Aura/learn/results-and-options): A program that runs for any length of time has to deal with two uncomfortable facts: values can be absent, and operations can fail. Aura represents both in the type system so the code is honest about which calls might go wrong and how.
- [The First Program](https://johnolafenwa.github.io/Aura/learn/small-programs): The best way to meet a language is to write a program that actually reports something. In this chapter we will build a small classifier: it takes a list of numbers, sorts each one into a category, counts how often each category appears, and prints a report.
- [Testing](https://johnolafenwa.github.io/Aura/learn/testing): A language that checks ownership and failure at compile time still cannot tell you whether your logic is right. That is what tests are for, and Aura ships a runner so you do not have to pick one.

## Tutorials

- [Overview](https://github.com/johnolafenwa/Aura/blob/main/tutorials/00-overview.md): Aura is a compiled, statically typed programming language with Python-inspired syntax, explicit ownership, native executables, and no garbage collector.
- [Running Programs](https://github.com/johnolafenwa/Aura/blob/main/tutorials/01-running-programs.md): Aura currently runs through the bootstrap CLI, `aura`. You invoke it from the repository root using `cargo run -p aura --`.
- [Bindings And Types](https://github.com/johnolafenwa/Aura/blob/main/tutorials/02-bindings-and-types.md): In Aura, every value has a type known at compile time. Bindings are introduced with assignment -- no `let` keyword is needed.
- [Functions](https://github.com/johnolafenwa/Aura/blob/main/tutorials/03-functions.md): Functions are declared with `def` and require explicit parameter types.
- [Control Flow](https://github.com/johnolafenwa/Aura/blob/main/tutorials/04-control-flow.md): Aura supports the standard control-flow constructs: conditionals, loops, pattern matching, and early exit.
- [Classes And Data](https://github.com/johnolafenwa/Aura/blob/main/tutorials/05-classes-and-data.md): The implemented class model currently covers fields, default values, positional and named construction, member access, `public` fields and methods, instance methods, associated methods, mutating methods, explicit `copy class` declarations, and indirect recursive fields.
- [Ownership And Borrowing](https://github.com/johnolafenwa/Aura/blob/main/tutorials/06-ownership-and-borrowing.md): If you are coming from Python, this is the most important chapter in the tutorial. Aura does not use a garbage collector. Instead, it tracks who owns each value and when that value can be freed. This system is called **ownership**, and the way you temporarily lend values without giving them away is called **borrowing**.
- [Strings And Numbers](https://github.com/johnolafenwa/Aura/blob/main/tutorials/07-strings-and-numbers.md): Aura supports enough numeric and string behavior for real programs. This chapter covers arithmetic, string operations, parsing, formatting, and the numeric type system.
- [Tooling](https://github.com/johnolafenwa/Aura/blob/main/tutorials/08-tooling.md): Aura ships with compiler and editor tooling inside the monorepo.
- [Enums And Match](https://github.com/johnolafenwa/Aura/blob/main/tutorials/09-enums-and-match.md): Enums let you define a type that can be one of several variants. Combined with `match`, they give you exhaustive pattern matching -- the compiler guarantees you handle every case.
- [Results And Options](https://github.com/johnolafenwa/Aura/blob/main/tutorials/10-results-and-options.md): Aura represents typed success, failure, presence, and absence with `Result[T, E]`, `Option[T]`, and the queue-specific `SendError[T]`. These enums form the foundation of recoverable error handling in Aura.
- [Resource Management](https://github.com/johnolafenwa/Aura/blob/main/tutorials/11-resource-management.md): When you open a file, a network connection, or a task group, you need to ensure it gets cleaned up even if something goes wrong. Aura's `with` statement provides deterministic scoped cleanup -- the resource is always closed when the block exits, whether by normal completion or early `return`.
- [Error Propagation](https://github.com/johnolafenwa/Aura/blob/main/tutorials/12-error-propagation.md): When functions return `Result[T, E]`, chaining multiple fallible operations with `match` can get deeply nested. Aura provides `try expr` to flatten this pattern.
- [Concurrency](https://github.com/johnolafenwa/Aura/blob/main/tutorials/13-concurrency.md): Aura's maintained concurrency surface is built around pinned-worker scheduler-backed lightweight tasks, structured task groups, typed queues, and explicit wait helpers. Queue waits, task waits, `sleep(...)`, socket waits, and the maintained HTTP helpers all use the same pinned-worker runtime.
- [Current Language Surface](https://github.com/johnolafenwa/Aura/blob/main/tutorials/14-current-language-surface.md): This chapter is a compact reference for the language subset that the bootstrap compiler supports today.
- [Generics](https://github.com/johnolafenwa/Aura/blob/main/tutorials/15-generics.md): Generics let one `Box[T]` definition work across the types that satisfy its requirements. Separate `BoxInt`, `BoxString`, and `BoxFloat` classes are not needed.
- [Traits](https://github.com/johnolafenwa/Aura/blob/main/tutorials/16-traits.md): Traits define shared behavior that different types can implement. If you know Python's abstract base classes or Go's interfaces, traits serve a similar purpose -- they let you write code that works with any type that provides the required methods.
- [Modules And Visibility](https://github.com/johnolafenwa/Aura/blob/main/tutorials/17-modules-and-visibility.md): Aura supports local file modules with `import`, `from ... import ...`, and `public` visibility boundaries. Modules let you organize code across files and control what is exposed to other parts of your project.
- [Packages And Workspaces](https://github.com/johnolafenwa/Aura/blob/main/tutorials/18-packages-and-workspaces.md): Aura supports a package system built around `Aura.toml` manifest files. Packages let you organize larger projects with multiple source directories, share code through local path and git dependencies, and group related packages into workspaces.
- [I/O And Networking](https://github.com/johnolafenwa/Aura/blob/main/tutorials/19-io-and-networking.md): Aura has a maintained I/O surface through four builtin modules:
- [Deterministic And Secure Randomness](https://github.com/johnolafenwa/Aura/blob/main/tutorials/20-randomness.md): Aura makes you choose which promise you need. A seeded `random.Rng` gives a repeatable sequence for tests, simulations, generated fixtures, and retry jitter. The module-level `random.secure_int` and `random.secure_bytes` functions ask the operating system for unpredictable values.
- [Working With JSON Values](https://github.com/johnolafenwa/Aura/blob/main/tutorials/21-json.md): Aura's JSON surface gives untrusted JSON its own recursive value and typed parse-error enums. It keeps parsing failures recoverable while making serialization deterministic enough for service messages, fixtures, and cache keys.
- [Bytes, Encodings, And Hashes](https://github.com/johnolafenwa/Aura/blob/main/tutorials/22-bytes.md): Aura uses `list[uint8]` whenever an API needs raw bytes. That is the same type returned by file, socket, process, and secure-random byte APIs, so data can move between those boundaries without a wrapper conversion.
- [Assertions And Tests](https://github.com/johnolafenwa/Aura/blob/main/tutorials/23-assertions-and-tests.md): Assertions turn a condition that must hold into an immediate, source-located runtime failure. Use the short form when the default message is enough:
- [Multiline Expressions](https://github.com/johnolafenwa/Aura/blob/main/tutorials/24-multiline-expressions.md): Aura can keep one logical expression readable across several physical lines. The rule is simple: the line continues while `(`, `[`, or `{` remains open.
- [Tuples](https://github.com/johnolafenwa/Aura/blob/main/tutorials/25-tuples.md): Tuples bundle a fixed number of values that may have different types. They are useful when a function has two or three natural results but defining a class would add more ceremony than meaning.
- [26. Foreign Function Interface v0](https://github.com/johnolafenwa/Aura/blob/main/tutorials/26-ffi.md): Aura FFI v0 binds small, trusted C APIs without opening the language to general pointer manipulation. FFI declarations are package-only and require an explicit manifest opt-in.
- [Aura Tutorials](https://github.com/johnolafenwa/Aura/blob/main/tutorials/README.md): This directory is the beginning of the Aura tutorial track: a book-style set of Markdown chapters that explains the language as it exists in the repository today.