Runtime Diagnostics & Error Reference

BramandScript features a compiler and virtual machine diagnostic engine inspired by the Rust compiler. When an issue occurs at tokenization, compilation, or bytecode execution, the system emits an unambiguous, contextual diagnostic featuring line numbering, 5-line context windows, column-accurate caret spans, zero-noise borderless formatting, and actionable suggestions.

Visual Anatomy of a BramandScript Diagnostic

Every diagnostic rendered by diagnostics/diagnostics.go adheres to an international terminal standard designed for readability and terminal piping:

✦ error[CompileError]: undefined variable 'totalScore'
  --> src/analytics/engine.bmd:14:13
     |
   9 |     let multiplier = 1.25;
  10 |     let baseWeight = 40;
  11 |     let rawScore = calculate_raw(records);
  12 |     
  13 |     // Calculate adjusted score with dynamic penalty
  14 |     let res = totalScore * multiplier;
     |               ^~~~~~~~~~ [Hint: Declare variable using 'let totalScore = ...' or check spelling]
  15 |     return res;
  16 | };
     |

1. Syntax Errors (SyntaxError)

Syntax errors are detected during lexical analysis (lexer) and top-down operator precedence parsing (parser). They indicate malformed tokens, unclosed string literals, missing delimiters, or invalid grammar constructs.

let count = 10
let maxLimit = 100;

let count = 10;
let maxLimit = 100;

let items = [1, 2, 3;
let sum = (a + b;

let items = [1, 2, 3];
let sum = (a + b);

let msg = "Hello, world;
let badPath = "C:\new_folder\test";

let msg = "Hello, world";
let badPath = "C:\\new_folder\\test";

2. Compile Errors (CompileError)

Compile errors are caught during the AST-to-bytecode compilation phase. The compiler validates symbol resolution, variable mutability, scope binding, module dependencies, and constant tables before emitting VM opcodes.

let radius = 5;
let area = pi * radius * radius;

import "std/math" as math;
let radius = 5;
let area = math.PI * radius * radius;

const MAX_CONNS = 100;
MAX_CONNS = 200; // error!

let maxConns = 100;
maxConns = 200; // valid with 'let'

// In module_a.bmd:
import "./module_b" as b;

// In module_b.bmd:
import "./module_a" as a; // Circular Import Error!

3. Runtime Errors (RuntimeError)

Runtime errors occur during virtual machine opcode execution when an operation encounters an illegal state (e.g., division by zero, index out of range, invocation of a null reference).

let count = 0;
let average = total / count;

let count = 0;
let average = count == 0 ? 0 : total / count;

let list = [10, 20, 30];
let val = list[5]; // out of bounds!

let list = [10, 20, 30];
let idx = 5;
let val = idx < len(list) ? list[idx] : null;

let callback = null;
callback("data"); // crashes!

let callback = null;
if callback != null {
    callback("data");
}

4. Sandbox Security & Permissions (PermissionDenied)

BramandScript enforces an enterprise zero-trust security sandbox by default. File system writes, socket networking, subprocess execution, and elevated file reads require explicit command-line permission flags or package contract declarations.

✦ error[PermissionDenied]: unauthorized write operation to path '/var/log/app.log'
  --> src/logger.bmd:22:5
     |
  21 |     let entry = format_entry(level, msg);
  22 |     file_write("/var/log/app.log", entry);
     |     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Hint: Run with the required security permission flag: --allow-run, --allow-write, --allow-net, or --allow-all]
  23 | };
     |

Resolution: Run the binary with the appropriate permission flag: bramand run --allow-write src/logger.bmd or declare permissions.filesystem_write: true inside your project's bmdpkg.json manifest.

5. Concurrency & Deadlocks (ConcurrencyError)

BramandScript utilizes lightweight concurrent tasks (spawn), typed channels (chan(cap)), and mutual exclusion locks (mutex()). Thread-safety violations, sends to closed channels, or unbuffered deadlock stalls trigger concurrency diagnostics.

let ch = chan(5);
ch.close();

// Guard against closed channel before sending
let ok = ch.try_send("payload");
if !ok {
    println("Channel closed or buffer full; discarded gracefully.");
}

let m = mutex();
let sharedCounter = 0;

spawn(fn() {
    m.lock();
    sharedCounter += 1;
    m.unlock();
});

6. Package Manager & Bundler (PackageManagerError)

The centralized package engine (bramand pkg, bramand install, bramand build) enforces SHA-256 supply-chain verification and offline determinism.

7. Stack Overflow & Cyclic Limits (StackOverflowError)

To protect systems from runaway recursion or cyclic data structure crashes, the Bramand VM implements hardware-safe depth limits.

Canonical Language Truthiness & Falsy Evaluation Semantics

BramandScript enforces an unambiguous, standardized truthiness model across the Pratt parser, bytecode compiler, and VM runtime execution loop. The evaluation logic is synchronized between vm.isTruthy(), opcode jumps (OpJumpNotTruthy, OpJumpTruthy), short-circuit operators (&&, ||), logical negation (!), and builtin conversions (bool()).

// 1. Logical OR Fallback (Preserves operands)
let user_name = "" || "Guest";       // "Guest" (empty string is falsy)
let timeout = 0 || 30;               // 30 (0 is falsy)
let buffer = bytes(0) || bytes(128); // bytes(128)

// 2. Control Flow Branching (Direct falsy jumping)
if ("") {
    println("Will not execute");
} else {
    println("Empty string is cleanly falsy");
}

// 3. Logical NOT Inversion
println(!0);        // true
println(!"");       // true
println(!bytes(0)); // true
println(!null);     // true

// 4. Canonical Boolean Coercion
println(bool(""));        // false
println(bool(0));         // false
println(bool("Bramand")); // true

Defensive Engineering & Exception Recovery

BramandScript provides modern error handling constructs including structured exceptions (try-catch-finally), custom throw, LIFO defer statements, safe navigation, and resilient stdlib packages.

try {
    let res = parse_user_input(payload);
    if res.age < 0 {
        throw "InvalidAge: age cannot be negative";
    }
    process_user(res);
} catch (err) {
    println("✦ Caught Error: " + str(err));
} finally {
    // Guarantees resource cleanup even after exceptions
    cleanup_temp_buffers();
}

LIFO Defer Statement Cleanup

The defer keyword schedules cleanup actions to execute in strict Last-In, First-Out (LIFO) order when the enclosing function returns or unwinds via exception:

fn process_file(path) {
    let fd = file_open(path, "r");
    defer file_close(fd); // Guarantees closure upon return
    
    let content = file_read(path);
    return parse(content);
}

Safe Navigation & Nullish Operators

Prevent runtime null reference exceptions without cluttered nested conditional branches:

Monadic Safety & The Try-Propagation Operator (?)

While try / catch is suited for unrecoverable infrastructure crashes, application domain logic in BramandScript is designed around first-class Algebraic Monads (Result and Option). Combining monadic containers with the postfix ? operator enables zero-overhead error propagation without viral try-catch wrapping.

1. Result Monad: Ok(v) and Err(e)

Functions that may fail return a Result container. Callers can unwrap safely, provide default fallbacks, or transform the inner value via functional chaining:

2. Option Monad: Some(v) and None()

Nullable or optional values are represented by Option. Calling .is_some(), .is_none(), or .unwrap_or(default) avoids unexpected null pointer runtime bugs:

let find_user = fn(id) {
    if id == 42 {
        return Some({ "id": 42, "name": "Kiran" });
    }
    return None();
};

let user_opt = find_user(100);
println("User exists:", user_opt.is_some()); // false

let fallback_user = user_opt.unwrap_or({ "id": 0, "name": "Guest" });
println("Active user:", fallback_user["name"]); // "Guest"

3. The Postfix Try-Propagation Operator (?)

In BramandScript, the ? operator evaluates expressions containing Result or Option. If the value is Ok(v) or Some(v), it extracts v and execution proceeds sequentially. If the value is Err(e) or None(), the current frame unwinds immediately and returns the failure to the caller:

let read_port = fn(raw_str) {
    if len(raw_str) == 0 {
        return Err("empty port string");
    }
    let p = int(raw_str);
    if p < 1 || p > 65535 {
        return Err("port out of range [1, 65535]");
    }
    return Ok(p);
};

let load_server_config = fn(port_str) {
    // If read_port fails, load_server_config immediately returns the Err!
    let port = read_port(port_str)?;
    
    return Ok({
        "host": "0.0.0.0",
        "port": port,
        "ready": true
    });
};

let valid_conf = load_server_config("8080");
println("Port configured:", valid_conf.unwrap()["port"]); // 8080

let invalid_conf = load_server_config("99999");
println("Error caught:", invalid_conf.unwrap_err()); // "port out of range [1, 65535]"

Resilience: Retry, Circuit Breaker & Structured Logging

For network and distributed systems, the standard library provides battle-tested resilience primitives in std/retry, std/circuitbreaker, and std/log:

import "std/retry" as retry;
import "std/circuitbreaker" as cb;
import "std/log" as log;

let breaker = cb.new_circuit_breaker(5, 10000); // 5 failures -> Open for 10s

let result = retry.with_retry(fn() {
    return breaker.execute(fn() {
        return fetch_remote_resource();
    });
}, 3, 200); // 3 retries, 200ms initial exponential backoff

Quick Reference Troubleshooting Matrix