TruLang Programming Language

All variable declarations in TruLang are immutable by default. Once initialized, the variable cannot be reassigned. Attempting to assign to a variable declared with let causes a compile-time error.

let message = "Hello, World!"; // Type inferred as string
let count: i64 = 100;           // Explicit type annotation

// message = "New Value"; // ❌ COMPILE ERROR: Cannot reassign immutable variable 'message'

To permit reassignment, the mut keyword must be explicitly specified. The variable remains bound to its declaring scope and can only be modified by the scope that created it.

let mut counter: i64 = 0;
counter = counter + 1; // ✓ Allowed: 'counter' was declared with 'let mut'

PRD Rule 2.2: "A variable's declaring scope controls its reassignment. Nested functions cannot modify variables belonging to enclosing scopes. Functions must return updated values when callers need to replace their own variables."

fn parent() {
    let mut total = 10;

    fn nested_child() {
        // total = 20; // ❌ COMPILE ERROR: Nested function cannot mutate variable 'total' declared in enclosing scope
    }
}

Variables cannot hold null unless explicitly declared as a nullable type T?. To access properties on potentially null objects, use safe navigation user?.profile or explicit checks if (user != null).

let user: User? = database.find_user(42);

// Safe navigation returns null if user is null:
let email = user?.email;

if user != null {
    println(user.name); // Unwrapped safely
}

Arrays store contiguous lists of values. In Region A, arrays are bump-allocated inside the request arena. When promoted to persistent storage with persist(arr), the entire array is ref-counted in Region B.

let numbers = [10, 20, 30, 40];
let names = ["Alice", "Bob", "Charlie"];

println(numbers); // Prints: [10, 20, 30, 40]

High-performance hash table for key-value storage. Frequently used in persistent service fields for caching. Supports insert, get, contains, and remove.

let mut cache: Map<string, User> = Map::new();

// Inserting elements:
cache.insert("user_42", persist(user));

// Retrieving elements:
let cached_user = cache.get("user_42");
let exists = cache.contains("user_42"); // returns true

Conditions must strictly evaluate to a bool (or nullable object comparison). Truthiness is strictly checked by the compiler.

let score = 85;

if score >= 90 {
    println("Grade: A");
} else if score >= 80 {
    println("Grade: B");
} else {
    println("Grade: C");
}

The condition is evaluated before each iteration. The loop body can reassign mutable variables declared in the enclosing function scope (such as accumulators and index counters).

let mut sum: i64 = 0;
let mut i: i64 = 1;

while i <= 10 {
    sum = sum + i;
    i = i + 1;
}

println(sum); // Output: 55

Returns a value to the caller. Before the call frame is popped, any active defer statements registered in the function are guaranteed to run in LIFO order.

Parameters are typed. If mut is specified on a parameter, that parameter can be modified locally within the function frame without affecting the caller's value.

fn calculate_discount(price: f64, percent: f64) -> f64 {
    let discount = price * (percent / 100.0);
    return price - discount;
}

Services represent actor units in TruLang. Handlers process incoming messages sequentially from the actor mailbox. Parallel throughput is achieved by instantiating worker pools of actors, eliminating shared mutable concurrency issues.

service UserService {
    memory_budget request = 16 MB;
    memory_budget persistent = 512 MB;

    let mut cache: Map<string, User> = Map::new();

    fn handle(request: Request) -> Response {
        defer log_request_completed(request.id);

        let user = database.find_user(request.user_id);
        if user != null {
            cache.insert(request.user_id, persist(user));
        }
        return Response.json(user);
    }
}

Budgets enforce strict memory ceilings per execution region. The request arena supports elastic burst headroom via max <size>, allowing sudden request spikes to succeed without dropping requests while emitting zero-overhead ArenaBurst telemetry events. When max is omitted, strict limits are maintained.

service ElasticService {
    // 16 MB baseline budget with elastic burst headroom up to 64 MB
    memory_budget request = 16 MB max 64 MB;
    memory_budget persistent = 512 MB;

    let mut cache: Map<string, User> = Map::new();

    fn handle(request: Request) -> Response {
        let user = database.find_user(request.user_id);
        if user != null {
            // Transparent compiler auto-promotion: promoted to Region B cache without persist()
            cache.insert(request.user_id, user);
        }
        return Response.json(user);
    }
}

When an error or exception is thrown, the VM unwinds stack frames until a matching catch block is located.

try {
    let result = execute_query("SELECT * FROM users");
    return Response.json(result);
} catch (err: DatabaseError) {
    return Response.error(500, err.message);
}

Essential for guaranteed resource management (closing files, releasing locks, terminating spans). Runs deterministically when the declaring scope exits.

$ trulang check examples/user_service.tr
✓ Check passed: No syntax, typing, or ownership violations found in examples/user_service.tr

Dual-Mode Execution Strategy: Run in development mode on the stack-based Bytecode VM for sub-second feedback loops, or pass --jit to compile and execute natively on-the-fly.

$ trulang run examples/fibonacci.tr
Calculating Fibonacci sequence up to N = 10:
0, 1, 1, 2, 3, 5, 8, 13, 21, 34

Program exited with value: 55
--- Memory Diagnostics ---
Region A (Execution):  48 bytes used (budget: 16777216 bytes)
Region B (Persistent): 0 bytes retained (0 live objects)

# Native JIT Mode:
$ trulang run --jit examples/fibonacci.tr
[Native JIT Execution completed in 347.038 ms with exit code 0]

Translates TruLang bytecode into optimized native machine code via host toolchains (clang, gcc, or cl.exe). Emits a standalone executable binary that runs directly on the OS without requiring the trulang CLI or VM, strictly preserving Region A $O(1)$ bump arena allocation and Region B persistent memory.

$ trulang build --release examples/fibonacci.tr -o fib_native
╔════════════════════════════════════════════════════════════════════════╗
║              TruLang Native AOT Compilation Complete                     ║
╠════════════════════════════════════════════════════════════════════════╣
║ Output Binary: ./fib_native                                            ║
║ Binary Size:   33.48 KB (34288 bytes)                                   ║
║ Optimization:  Release (-O3)                                            ║
║ Target Arch:   aarch64 / x86_64                                         ║
║ Build Time:    120.44 ms                                                ║
╚════════════════════════════════════════════════════════════════════════╝

# Run standalone binary directly with zero runtime dependencies:
$ ./fib_native
Calculating Fibonacci sequence up to N = 10:
55

$ trulang monitor
Attaching Memory Supervisor to telemetry segment: "/tmp/trulang_shm_7305.dat"

╔══════════════════════════════════════════════════════════════════════════╗
║                      TruLang Independent Memory Supervisor                 ║
╠══════════════════════════════════════════════════════════════════════════╣
║ Worker Process PID: 7305         Heartbeat: 0.12s ago                    ║
║ Health Status: 🟢 HEALTHY (Within configured budgets)                    ║
╠──────────────────────────────────────────────────────────────────────────╢
║ Region A (Execution):          16 B /   16777216 B (  0.0%) -      2 allocs ║
║ Region B (Persistent):         16 B /  536870912 B (  0.0%) -      1 objs   ║
╚══════════════════════════════════════════════════════════════════════════╝

$ trulang lsp --stdio
Starting TruLang Language Server daemon (JSON-RPC 2.0 over stdio)...

Compiled directly into the core binary. Eliminates toolchain divergence and provides live syntax checking, type diagnostics with compiler actionable hints (e.g. suggesting let mut), hover tooltips, and jump-to-definition for VS Code, Cursor, Neovim, and Zed.

$ trulang fmt examples/user_service.tr --write
✓ Formatted examples/user_service.tr

Telemetry records spanning 56 bytes are exchanged over zero-syscall mmap ring buffers without lock contention. Writers acquire an odd sequence counter before modifying fields, issue memory release barriers, and increment to an even counter upon completion. Readers verify sequence consistency before and after read operations:

// Zero-lock atomic reader with optimistic retry
for _ in 0..16 {
    let seq1 = std::ptr::read_volatile(&record.seq);
    if seq1 % 2 != 0 { std::hint::spin_loop(); continue; }
    fence(Ordering::Acquire);
    let data = std::ptr::read_volatile(record_ptr);
    fence(Ordering::Acquire);
    let seq2 = std::ptr::read_volatile(&record.seq);
    if seq1 == seq2 && seq1 % 2 == 0 { return Ok(data); }
}

Shared memory segments are strictly isolated from world-writable /tmp. TruLang targets $XDG_RUNTIME_DIR/trulang/ (falling back to ~/.trulang/shm/ or /tmp/trulang_runtime_{uid}/) with directory mode 0700 and file creation mode 0600.

All arithmetic opcodes (+, -, *, /, %, neg) use checked hardware arithmetic. Edge cases like i64::MIN / -1 or integer wrap are caught and converted to typed VmError::ArithmeticOverflow or VmError::DivisionByZero rather than panicking the host process.

Adversarial inputs with nested parentheses ((((...)))) are stopped at 64 levels with SyntaxError("recursion depth limit exceeded"). The VM bounds operand stack to 65,536 elements and call frames to 4,096, terminating infinite recursive loops with VmError::StackOverflow.

ServiceActor enforces a bounded mailbox (default 10,000 requests). When queue capacity is reached under traffic spikes, incoming messages are immediately rejected with ActorError::MailboxFull to shed load rather than accumulating runaway latency.

Promotion to Region B persistent storage via persist(x) traverses the reference graph with detect_value_cycles. Self-referential cyclic structures are rejected with VmError::CyclicPersistentData, guaranteeing that Region B ref-counted allocations cleanly free when unreferenced.

1. Hybrid Worker Thread Pool Architecture

In high-throughput actor systems, executing blocking I/O (e.g. PostgreSQL network socket reads or heavy cryptographic hashing) directly inside the actor thread starves incoming requests. TruLang's WorkerPool offloads blocking native calls to a thread pool with zero thread leakage, keeping the actor mailbox responsive:

import "rust:trulang_std_pg" as db;

service UserService {
    memory_budget request = 64 KB;
    // Database connection pool held as an opaque ExternalHandle in actor state
    let pool = db.create_pool("postgres://localhost/users");

    fn handle(user_id: i64) -> Response {
        // Query is offloaded to WorkerPool; actor mailbox never blocks
        let user = pool.query_user(user_id);
        return Response.json(user);
    }
}

2. Deterministic RAII Destructors (`ExternalHandle<T>`)

Opaque native handles (sockets, thread pools, file descriptors, database connections) are wrapped in ExternalHandle<T>. When the enclosing actor terminates or local variable drops, the Rust/C destructor runs deterministically, eliminating resource leaks.

3. Region A Arena Marshaling

Foreign DTOs, JSON payloads, and primitive types returned by native code are marshaled directly into the request's Region A bump arena. If a foreign query returns a payload exceeding the actor's memory budget, TruLang halts the request with VmError::MemoryExceeded, guaranteeing that foreign code cannot bypass memory limits.