nulang: Instructions file for Codex

Repository Guidelines

Practical orientation for AI assistants working in the Nulang codebase. All paths are relative to the repo root (~/nulang).

Project Overview

Nulang is a typed programming language for concurrent, durable, and distributed software, written in Rust (edition 2021, Cargo workspace with a primary nulang crate and a nulang-ai support crate). Actors are the addressable-isolation model rather than the ontology for all computation. Nulang combines Erlang-style fault-tolerant actors with a Rust/Pony-inspired type system (Hindley-Milner inference + reference capabilities + row-polymorphic algebraic effects), a register-based bytecode VM, a Cranelift JIT, a WASM backend (MIR→WASM via wasm-encoder) with a Wasmtime host runtime, BEAM/OTP primitives, CRDTs, location-transparent distribution, multi-backend persistence (memory/JSON/libSQL, with optional RocksDB/PostgreSQL), PyO3 Python interop, a C-compatible FFI layer, a v0.9 AI runtime (pure types in crates/nulang-ai/, Runtime glue in src/runtime/), and a format-stability layer (src/format/ — frozen .nbc bytecode artifacts, NUL0 wire protocol versioning, migration registry). Status: Alpha; 1558 tests pass in the core crate (cargo test), 1596 with --features wasm-backend; the nulang-ai crate ships 58 additional tests (cargo test -p nulang-ai). License: Apache-2.0.

Architecture & Data Flow

The compiler pipeline shares one frontend across the bytecode, native/AOT, and WASM execution backends:

Bytecode backend (default):

source &str
  -> Lexer::lex()                         -> Vec<Token>            src/lexer.rs
  -> Parser::parse_module()               -> AstModule             src/parser.rs
  -> TypeChecker::check_module()          -> Type                  src/typechecker.rs (HM Algorithm W)
  -> EffectChecker::check_module()        -> ()                    src/effect_checker.rs
  -> CapabilityAnalyzer::infer_cap()      -> Capability            src/effect_checker.rs
  -> HIR lowering (hir_lower::lower_module) -> HIR Module          src/hir_lower.rs
  -> MIR lowering (mir_lower::lower_module) -> MIR Module          src/mir_lower.rs
  -> MIR codegen (mir_codegen::compile_mir)  -> CodeModule         src/mir_codegen.rs
  -> VM::load_module() + VM::run()        -> Value                 src/vm.rs (register VM + JIT tiering)