Glossary
Glossary
Section titled “Glossary”Terminology and definitions used throughout the Nox documentation.
AST (Abstract Syntax Tree) A tree-structured representation of source code produced by the parser. Each node represents a syntactic construct (e.g., a variable declaration, a function call, an arithmetic expression). The AST preserves line and column metadata for error reporting.
ANTLR 4
A parser generator used by Nox to produce the lexer and parser from a formal grammar definition. ANTLR generates Kotlin code that transforms raw .nox text into an AST.
as (keyword)
The explicit cast operator. Converts a json value to a struct type with runtime structural validation. Syntax: expr as Type. Throws CastError on failure. See Type System, Explicit Casting.
Base Pointer (bp)
An integer offset into the register arrays (pMem, rMem) that marks where the current function’s registers begin. Function calls “slide” the base pointer forward; returns slide it back. See Memory Model.
Bytecode
A flat array of 64-bit long instructions produced by the compiler. The VM executes bytecode sequentially, jumping as directed by control flow instructions.
Capability-Based Security A security model where code has no inherent permissions. Every action that affects the outside world must be explicitly requested and approved through the Permission Bridge. See Security Model.
Constant Pool A deduplicated array of static data (strings, large numbers, type identifiers) generated by the compiler. Instructions reference pool entries by index. See Instruction Set.
Dual-Bank Register File
Nox’s memory architecture: two separate pre-allocated arrays long[] pMem for primitives and Object[] rMem for references. This eliminates boxing/unboxing overhead. See Memory Model.
Exception Table A metadata table generated by the compiler that maps instruction ranges to catch handlers. Used for zero-cost exception handling. See Error Handling.
FFI (Foreign Function Interface)
The mechanism by which NSL scripts call Kotlin code. Nox uses MethodHandle-based linking for near-direct-call performance. See FFI Internals.
Global Memory (gMem)
A dedicated memory space for global variables, separate from per-function register windows. Instructions use a global flag [G] to indicate global memory access.
Host The trusted application that embeds and drives the Nox runtime. The Host configures execution policies, handles output, and adjudicates permissions. A Host can be a CLI tool, a server, a game engine, or any Kotlin/JVM application. The Host never executes untrusted code directly. See Architecture Overview.
HMOD (Host Modify) A super-instruction that modifies a property on a host object in a single VM cycle. Replaces multiple load-compute-store sequences. See Super-Instructions.
HACC (Host Access) A super-instruction that reads a property from a host object into a register.
import (keyword)
A declaration that loads functions and types from another .nox file into a user-chosen namespace. Syntax: import "path.nox" as namespace;. Paths are resolved relative to the importing file’s directory. The namespace must not clash with built-in (Tier 0) or external plugin (Tier 1) namespaces. See Plugin Guide, Tier 2 and File Format, Import Declarations.
ImportDecl
An AST node representing an import statement. Holds the raw path, user-chosen namespace, and resolved absolute path (set during import resolution).
Instruction Counter A watchdog that increments on every VM loop iteration. Terminates execution if the count exceeds a configurable limit. Prevents infinite loops.
KILL_REF An instruction emitted by the compiler at scope exits to null out reference registers, enabling garbage collection of objects that are no longer needed.
Kotlin Coroutine
A lightweight concurrency primitive managed by the Kotlin runtime. Sandboxes run on coroutines, enabling thousands of concurrent executions. Suspending a coroutine (e.g., during requestPermission()) does not consume OS threads.
Landing Zone
The register area where a caller places arguments before a CALL instruction. After the base pointer slides forward, these become the callee’s first parameters.
Library Registry A registry that defines every available library function, including its namespace, parameters, return type, and the Kotlin implementation behind it. Populated at runtime startup from built-in libraries and registered plugins.
Linker
The component that transforms developer-written Kotlin methods (with clean typed signatures) into NoxNativeFunc instances compatible with the VM’s raw memory interface. Uses MethodHandle combinators and LambdaMetafactory.
Liveness Analysis A compiler phase that determines the exact lifespan (first declaration to last use) of every variable. Enables aggressive register reuse.
MethodHandle
A JVM mechanism for dynamically invoking methods with near-direct-call performance. Access checks happen once at creation time, not per-call. The JVM JIT compiler can inline MethodHandle calls.
ModuleMeta
Per-module metadata in a CompiledProgram. Tracks the module’s namespace, source path, global memory offset (globalBaseOffset), exported functions, and exported types. Each imported file becomes one ModuleMeta entry. See Code Generation, ModuleMeta.
NoxArray
A lightweight wrapper around ArrayList<Object> used to represent JSON arrays inside the VM. Replaces GSON’s JsonArray with a zero-dependency alternative. Supports index access and .size().
NoxNativeFunc
The functional interface that all linked plugin functions implement. Signature: void invoke(long[] pMem, Object[] rMem, int bp, int bpRef, int argStart, int destReg).
NoxObject
A lightweight wrapper around HashMap<String, Object> used to represent JSON objects and structs inside the VM. Replaces GSON’s JsonObject with a zero-dependency alternative. Supports .get(), .put(), .has(), .keys(), and .size().
NoxResult
The return type from NoxRuntime.execute(). Contains yielded interim outputs, the final result, success/failure status, and any error information. See Embedding API.
NoxRuntime
The main entry point for embedding Nox in a Kotlin/JVM application. Provides a builder API for configuring execution limits, registering plugins, setting permission handlers, and executing .nox programs. See Embedding API.
NSL (Nox Scripting Language)
The statically-typed, C-family programming language executed by the Nox runtime. Files use the .nox extension.
NullAccessError
A runtime exception thrown when code attempts to access a property or call a method on a null reference. Can be caught with try-catch. See Type System, Null.
Opcode
The primary operation identifier in a VM instruction (e.g., IADD, CALL, HMOD). Encoded in the top 8 bits of the 64-bit instruction.
Opcode Compression The design philosophy of encoding multiple logical operations into single VM instructions. One complex instruction is faster than several simple ones because it reduces VM loop iterations.
Output Handler
A Host-provided callback that receives yield and return output from scripts. The default CLI handler prints to stdout. Servers might stream over WebSocket. See Architecture Overview.
Permission Bridge
The protocol by which the VM pauses to request permission from the Host before executing sensitive operations (file I/O, network access). Constructs a typed PermissionRequest and suspends the coroutine until the Host returns a PermissionResponse. See Security Model.
Permission Handler
A Host-provided policy that pattern-matches on PermissionRequest types to decide whether to grant or deny capability requests from scripts. Can return typed constraints via PermissionResponse.Granted subclasses. See Architecture Overview.
PermissionRequest
A sealed class hierarchy representing every type of permission the sandbox can request. File variants: File.Read, File.Write, File.Append, File.Delete, File.List, File.Metadata, File.CreateDirectory. Http variants: Http.Get, Http.Post, Http.Put, Http.Delete. Env variants: Env.ReadVar, Env.SystemInfo. The Plugin(category, action, details) variant is an escape hatch for plugin-defined permissions. See Architecture Overview.
PermissionResponse
A sealed class hierarchy returned by the Host in response to a PermissionRequest. Granted subclasses carry typed constraints: FileGrant (maxBytes, allowedDirectories, allowedExtensions, readOnly), HttpGrant (allowedDomains, allowedPorts, httpsOnly, timeoutMs), EnvGrant (allowedVarNames), PluginGrant (values), and Unconstrained. Denied(reason) carries an optional human-readable denial reason. See Architecture Overview.
pMem (Primitive Memory)
The long[] array that stores primitive values (int, double, boolean). Part of the dual-bank register file.
Register Allocation The compiler process of mapping variable names to integer register indices. Uses liveness analysis to reuse registers when variables’ lifetimes don’t overlap.
rMem (Reference Memory)
The Object[] array that stores reference types (String, NoxObject, arrays). Part of the dual-bank register file.
RuntimeContext
The interface bridging Sandboxes to the Host. Provides yield(), returnResult(), and requestPermission(PermissionRequest). See Architecture Overview.
Sandbox
An ephemeral, isolated execution environment created to run one .nox program. Runs on a Kotlin Coroutine. Has no direct access to host resources; all capabilities are proxied through the RuntimeContext. See Architecture Overview.
SCALL (System Call)
The VM opcode for calling linked plugin functions via the FFI. Dispatches to a NoxNativeFunc by function ID.
Semantic Validation A compiler phase that checks the AST for logical errors (type mismatches, undeclared variables, arity mismatches) before bytecode generation. See Compilation Pipeline.
Sliding Window The mechanism for function call frames. Instead of copying data, the base pointer slides forward over the same arrays. Arguments are pre-placed by the caller in the “landing zone.” See Memory Model.
Sub-Opcode
The secondary intent field (bits 55–48) in the instruction layout. Used by super-instructions to specify the exact operation (e.g., ADD_INT, SET_STRING).
Super-Instruction
An instruction that performs a complex, multi-step operation in a single VM cycle. The two super-instructions are HMOD and HACC. See Super-Instructions.
@NoxTypeMethod
An annotation used to register a Kotlin method as a type-bound method in NSL. Specifies boundTo (the NSL type) and name (the method name). Enables syntax like myInt.toDouble(). See Plugin Guide, Type-Bound Methods.
UFCS (Unified Function Call Syntax)
A syntactic feature where variable.method(args) is equivalent to method(variable, args). Provides method-call ergonomics without requiring classes. See Functions.
Watchdog A resource guard that monitors Sandbox execution and terminates it if limits are exceeded. Types: instruction counter, wall-clock timeout, memory cap, recursion limit. See Resource Guards.
yield
An NSL keyword that sends intermediate output from the Sandbox to the Host without terminating execution. What happens with the output depends on the Host implementation (print to stdout, stream over network, etc.).
Zero Trust The foundational security principle: all code running inside the sandbox is assumed potentially malicious or incorrect. No implicit permissions, no assumed safety.