Dryad Conventions

Dryad distinguishes itself through: (i) a triple execution architecture — tree-walking interpreter, stack-based bytecode VM, and AOT compiler; (ii) a structured error system where all errors carry unique codes, source locations, and correction suggestions; (iii) the namespace operator (::) for qualified access (C++/Rust style); (iv) native directives via #<module> for loading native modules; and (v) native template string interpolation with ${expr}.

The Dryad alphabet consists of: (i) Unicode UTF-8 encoded characters; (ii) letters [a-zA-Z] and underscore _; (iii) digits [0-9]; (iv) special symbols { } ( ) [ ] ; , . : = + - * / % & | ^ ~ ! < > ? @ # $ \ ' " `; and (v) whitespace (spaces, tabs, line breaks).

The Dryad lexer produces the following token types: Identifier (matching [a-zA-Z_][a-zA-Z0-9_]*), Number (f64, supporting decimal, hex 0x, binary 0b, octal 0o), String (delimited by " or '), Boolean (true, false), Null (null), TemplateString (comprising TemplateStart, TemplateContent, Interpolation markers, TemplateEnd), Keyword, Operator, Symbol, NativeDirective (#<name>), and Eof.

A native directive has the form #<module_name> where module_name is a valid identifier delimited by < and >. Example: #<io> loads the I/O native module. If whitespace appears between # and <, a lexer error is produced.

Dryad implements a dynamic type system where types are associated with values, not variables. Variables may change type during execution. Type checking occurs at runtime. Type annotations are optional and serve primarily for documentation and tooling support.

The fundamental primitive types of Dryad are: number (IEEE 754 f64 floating point), string (UTF-8 encoded character sequence), bool (boolean value), null (null/undefined value), and any (universal type, implicit when omitted).

Dryad supports the following composite types: Type[] (arrays — ordered, dynamically-sized, heterogeneous collections with zero-based indexing); (T1, T2, ...) (tuples — fixed-size, potentially heterogeneous, accessed via numeric index like tuple.0); fn(P1, P2, ...) -> R (function types — first-class values supporting closures); objects (key-value collections with dot and bracket access); and classes (user-defined types with state, behavior, and inheritance).

The AOT compiler employs a three-level gradient approach to resolve types for code compiled under "use strict types" or when the compiler can statically prove type safety: (i) Static CFG Inference — the compiler traverses the Control Flow Graph and propagates type constraints forward, promoting variables to their most specific native type (e.g., f64, i32) whenever all paths produce the same type; (ii) Annotation-Guided Resolution — user-provided type annotations (e.g., let x: i32) are treated as authoritative binding directives, bypassing inference for the annotated variable; (iii) Dynamic Fallback — when the inference engine cannot determine a single type (genuine polymorphism, e.g., a variable receiving both number and string across paths), the Variant Enum is preserved for that variable alone. This fallback is scoped to the individual binding, not the entire function.

Expressions in Dryad follow a strict precedence hierarchy (highest to lowest): (1) primary: ., [], (), new (left-associative); (2) postfix ++, -- (left); (3) prefix ++, --, !, -, +, ~ (right); (4) exponentiation ** (right); (5) multiplicative *, /, % (left); (6) additive +, - (left); (7) bitwise shift (left); (8) relational (left); (9) equality (left); (10-14) bitwise AND/XOR/OR and logical AND/OR (left); (15) assignment (right).

a + b: if both are numbers, performs addition; if either is a string, performs concatenation. a - b: subtraction (requires numbers). a * b: multiplication (requires numbers). a / b: division (requires numbers; division by zero raises Runtime Error 3000-3999). a % b: modulo (requires numbers). a ** b: exponentiation (requires numbers).

a && b: returns a if falsy, otherwise b. a || b: returns a if truthy, otherwise b. !a: boolean negation. Falsy values: false, null, 0, "", NaN. Truthy values: all others.

The match expression provides functional branching via pattern matching. Syntax: match value { pattern1 => result1, pattern2 => result2, _ => default }. Supported patterns: literals (1, "text", true), wildcard (_), and optional guards (boolean conditions following the pattern).

let declares a mutable, block-scoped variable. Syntax: let identifier [: type] [= value];. If not initialized, the value defaults to null. Multiple declarations are supported: let a = 1, b = 2;. const declares an immutable, block-scoped variable. Syntax: const identifier [: type] = value;. Must be initialized at declaration. For objects and arrays, the binding is immutable but the content may be modified.

The if statement executes conditionally. Syntax: if (condition) { ... } else if (condition2) { ... } else { ... }. The condition is evaluated as truthy/falsy. Only the first true block is executed. else and else if are optional.

Dryad supports four loop constructs: (i) while (condition) { ... } — executes while condition is truthy; (ii) do { ... } while (condition) — executes at least once; (iii) for (init; condition; update) { ... } — C-style iteration; (iv) for (element in iterable) { ... } — for-each iteration over collections. break exits the innermost loop; continue skips to the next iteration.

Exception handling uses the try { ... } catch (error) { ... } finally { ... } construct. The try block is monitored for exceptions. catch binds the caught exception to a variable. finally executes unconditionally (on both success and failure). At least one of catch or finally must be present.

throw expression; raises an exception that propagates up the call stack until caught by a catch block or reaches the top-level, terminating the program.

return [expression]; exits the current function immediately and returns the specified value (or null if omitted). Valid only within function and thread bodies.

Functions are declared with the function keyword. They are hoisted (can be called before their declaration in the same scope). Functions create closures over their surrounding scope. Parameters support default values (param = defaultValue) and rest parameters (...rest). Arrow functions ((params) => expression or (params) => { statements }) are not hoisted and provide implicit return for single-expression bodies.

Functions declared with async function may use await to suspend execution until a Promise resolves. Async functions implicitly return a Promise. Execution may be paused at each await expression.

Functions declared with thread function execute in a separate OS thread. Invocation: let handle = thread name(args); returns a handle to retrieve the result. Threads provide context isolation. Communication between threads is done via mutexes.

Classes are declared with the class keyword. They support instance properties, a constructor method, instance methods, and static members. Inheritance is supported via extends. Access modifiers: public (default, accessible from anywhere), private (class-internal only), protected (class and subclasses). The super keyword references the parent class; this references the current instance.

Dryad supports four import forms: (i) Named imports — import { name1, name2 } from "module";; (ii) Namespace import — import * as ns from "module";, accessed as ns.function(); (iii) Side-effect import — import "module"; executes the module for side effects; (iv) Identifier import — import moduleName; imports without quotes, accessed via the namespace operator: moduleName::function.

Direct export: export function name() { }, export const VALUE = 42;, export class ClassName { }. Re-export: export { name1, name2 } from "other_module";, export * from "other_module";.

Native modules (implemented in C or Rust) are loaded via #<module_name> directives. Available native modules include: #io (file I/O operations), #crypto (cryptography), #http (HTTP client/server), #math (mathematical functions), #tcp, #udp (networking), #time (date and time), and others. Native functions are loaded into the global scope following the C calling convention.

Dryad supports three execution strategies: (i) Tree-Walking Interpreter — executes the AST directly; the default mode, optimized for development and debugging; (ii) Bytecode VM — compiles the AST to stack-based bytecode; enabled with set_compile_mode(true); offers intermediate performance; (iii) AOT Compiler — compiles bytecode/IR to native code for ARM64 and x86_64, producing ELF or PE executables; maximum performance.

The scope hierarchy in Dryad follows: Global Scope → Module Scope → Function Scope → Block Scope. The variable lookup algorithm checks the current scope first, then walks up the parent scope chain to the global scope. If the variable is not found in any scope, a ReferenceError is raised. let and const are block-scoped; function declarations are hoisted to the enclosing function or module scope.

Functions capture variables from their definition scope. Captured variables remain alive as long as the function exists. Modifications to captured variables are visible across all closures sharing the same captured scope. Multiple closures may share the same captured variables.

Runtime values are represented as a discriminated variant enum: Number(f64), String(String), Bool(bool), Null, Array(Vec<Value>), Object(HashMap<String, Value>), Function(...), Class(...), and Thread(...).

The Bytecode VM does not emit generic opcodes — it emits type-specialized instructions based on type observations collected during the interpretation phase. When the interpreter detects that variable soma is always f64, the VM emits ADD_F64 instead of ADD_GENERIC. Each compiled function carries a Metadata Header containing: (i) the observed type signature for every slot and parameter; (ii) the total number of opcodes; (iii) the stack depth required; and (iv) a per-slot type confidence level (STATIC, OBSERVED, UNKNOWN). The AOT compiler reads this header to pre-populate its symbol table, eliminating the need to re-infer types from scratch. If a slot's type is STATIC (inferred with certainty via CFG analysis) or OBSERVED (seen consistently during interpretation), the emitted bytecode uses the fast native opcode directly. If UNKNOWN, the generic Variant opcode is emitted. This design distributes type intelligence across all three layers: the interpreter observes, the VM annotates, and the AOT consumes.

The @compile(mode) decorator replaces the global set_compile_mode() function for fine-grained compilation control. It may be applied to function declarations or block statements. Accepted modes: @compile("interpreter") — forces AST interpretation for this scope (useful for debugging); @compile("bytecode") — compiles the scope to bytecode VM instructions; @compile("AOT") — marks the scope for AOT compilation when producing a native binary. When applied to a block: @compile("bytecode") { ... }, the statements inside the block are compiled in the specified mode while the surrounding code retains its default mode. When applied to a function declaration, all invocations of that function use the specified mode. The decorator is transitive: a function called from within an @compile(AOT) scope is also compiled to native, unless it has its own @compile override.

All errors in Dryad are instances of DryadError carrying: a unique numeric code, a category label, a human-readable message, source location (file, line, column), a stack trace, and debug context (suggestions, local variables, documentation references).

Functions declared with async may use the await keyword to suspend execution until a Promise resolves. Async functions implicitly return a Promise. The await keyword permits non-blocking asynchronous code with synchronous-style syntax.

Functions declared with thread function execute in a separate OS thread. Threads provide full context isolation. Communication between threads is performed via mutexes or return value handles. Invocation returns a thread handle that can be awaited to retrieve the result.

The mutex() primitive creates a new mutex. The API provides mu.lock() (acquires the lock, blocking if occupied) and mu.unlock() (releases the lock). Mutexes protect critical sections in multi-threaded code.

The mu.lock(timeout_ms: number): bool variant attempts to acquire the lock within the specified timeout in milliseconds. Returns true if the lock was acquired, false if the timeout expired. This enables non-blocking synchronization patterns and guards against deadlock scenarios where a thread fails to release its lock. The blocking variant mu.lock() is equivalent to mu.lock(Infinity).

Native modules are implemented in C or Rust and exposed to Dryad via native directives (#<module>). Functions from native modules become available in the global scope. The interface uses dynamic typing at the boundary. The calling convention follows the C ABI (cdecl on x86).

When a Dryad object reference crosses the FFI boundary into native code, the garbage collector may move or reclaim the object during the call, producing a dangling pointer. The gc.pin(obj) intrinsic prevents the GC from moving or collecting the object for the duration of the FFI call. It returns a raw pointer (ptr<u8>) valid for the pinned scope. gc.unpin(obj) releases the pin, allowing the GC to resume normal management. Pins are reference-counted: nested pin calls require an equal number of unpin calls.

Dryad adopts a self-hosting architecture where the C++ runtime provides only approximately 50 primitive intrinsics (syscalls). The entire standard library is implemented in 100% pure Dryad. There is zero need to write FFI bindings manually. High-level libraries (HTTP, JSON, cryptography) are written in pure Dryad atop the intrinsic layer.

An intrinsic is a special function recognized by the compiler that does not generate a normal CALL instruction. Instead, it compiles directly to a specialized opcode or inline assembly sequence with near-zero execution overhead. Intrinsics are declared with the @intrinsic("syscall.name") decorator and map directly to C++ runtime code.

The VM dispatches intrinsics via a flat lookup table of function pointers indexed by syscall ID, replacing the traditional switch-based dispatch. The lookup table is a const fn_ptr[N] array populated at compile time. Dispatch cost: two loads (base + offset) plus an indirect call — constant time regardless of N. For the bytecode VM, the INTRINSIC_SYSCALL opcode carries the syscall ID directly; for AOT-compiled code, the syscall ID is resolved to an absolute address at link time. Future work includes direct-threaded dispatch, where each syscall handler appends its own successor address, eliminating the central dispatch loop entirely.

When the runtime is compiled with DRYAD_DEBUG_INTRINSICS=1, every intrinsic call emits a structured trace record containing: timestamp (monotonic ns), thread ID, syscall ID, argument values (truncated to 64 bytes), return value, and elapsed time (ns). Traces are written to a ring buffer (configurable size, default 4096 entries) accessible at runtime via #<debug>.dump_trace(). The ring buffer is lock-free (single producer per thread). Production builds compile out all tracing code with zero overhead.

The native Buffer type represents a contiguous byte region with an embedded length and capacity. Every read and write operation validates the offset and extent against the buffer's length: out-of-bounds access raises Runtime Error 3000-3999 with the attempted range and buffer capacity. The bounds check compiles to a single cmp + jae (ARM64: cmp + b.cs) and is elided only when the AOT optimizer can statically prove the access is within bounds via range analysis.

The intrinsic set is partitioned into a portable HAL that abstracts OS-specific syscall differences. The HAL exposes uniform operations: hal_open(path, flags, mode) — maps to open(2) (POSIX) or CreateFileW (Windows); hal_mmap(addr, len, prot, flags, fd, offset) — maps to mmap(2) (POSIX) or MapViewOfFile (Windows); hal_spawn(path, args) — maps to fork+exec (POSIX) or CreateProcessW (Windows). Only the HAL layer contains platform-specific code; all intrinsics above the HAL are pure abstract syscalls. This limits porting effort to approximately 10-15 HAL primitives.

The @intrinsic("syscall.mmap") and @intrinsic("syscall.munmap") intrinsics expose virtual memory management directly. __mmap(addr, len, prot, flags, fd, offset): ptr<u8> maps a file or anonymous region into the process address space. __munmap(addr, len): void unmaps the region. These enable efficient memory-mapped file I/O and custom allocator construction in pure Dryad. The Buffer type may optionally back its storage with mmap for large regions (>64 KB), falling back to malloc for smaller allocations.

STDLIB functions follow a consistent error handling protocol: (i) functions that can fail due to external conditions (I/O, network, OS) return a Result type: `Result` where `E` is an error type carrying a numeric code and message. The caller MUST handle both variants. (ii) Functions that can fail due to programmer error (invalid arguments, precondition violations) throw a typed exception that propagates up the call stack. (iii) Every exported function documents its error conditions and the error codes it may produce. (iv) Error codes follow the module prefix convention: I/O errors use 5000-5999, networking uses 6000-6099, JSON uses 6100-6199, crypto uses 6200-6299, OS uses 6300-6399.

Each STDLIB module is a single `.dryad` file placed in the `lib/` directory. Every module follows this structure: (i) a module-level comment block describing the module's purpose and error codes; (ii) intrinsic and FFI declarations (wrapped in safe functions); (iii) type and class definitions; (iv) public function declarations, each with a documentation comment; (v) a consistent `export` block at the end. Public API functions are explicitly listed in the export statement; all other identifiers are module-private. Breaking changes to exported APIs require a major version bump.

The Buffer type (`Buffer`) represents a contiguous byte region with embedded length and capacity. API contract: (i) `Buffer.new(capacity: number): Buffer` — allocates a new buffer with the given initial capacity (zero-filled). (ii) `buf.len(): number` — returns the current length of valid data. (iii) `buf.capacity(): number` — returns the total allocated capacity. (iv) `buf.read(offset: number, len: number): Buffer` — returns a copy of the byte range [offset, offset+len). Raises Runtime Error 3000-3999 if the range exceeds length. (v) `buf.write(offset: number, data: Buffer): void` — writes data at the given offset, growing the buffer if necessary. (vi) `buf.slice(offset: number, len: number): BufferView` — returns a zero-copy view into the buffer's memory (no allocation). The view shares the backing store and is reference-counted. Modifications to the view are visible in the parent buffer. (vii) `buf.resize(new_len: number): void` — changes the length. If new_len exceeds capacity, the buffer grows using a doubling strategy. (viii) `buf.fromPtr(ptr: ptr, len: usize): Buffer` — wraps a raw pointer in a Buffer without copying (intended for use with mmap'd regions). The caller is responsible for ensuring the pointer remains valid for the Buffer's lifetime. (ix) Bounds checking: every read and write validates the offset and extent against `len`. Out-of-bounds access raises Runtime Error 3000-3999 with the attempted range and buffer capacity. The bounds check compiles to a single `cmp + jae` on both ARM64 and x86_64 and is elided only when the AOT optimizer can statically prove safety.

The STDLIB provides three collection types with defined contracts: (i) **List** — ordered, dynamically-sized sequence. Contract: `add(item)`, `get(index): any`, `set(index, value)`, `remove(index): void`, `len(): number`, `isEmpty(): bool`, `contains(item): bool`, `indexOf(item): number`, `sort(comparator?)`, `map(fn): List`, `filter(fn): List`, `reduce(fn, initial): any`, `forEach(fn)`, `slice(start, end): List`, `concat(other): List`, `toArray(): any[]`. (ii) **Map** — key-value dictionary (hash-based). Contract: `set(key, value)`, `get(key): any`, `has(key): bool`, `delete(key): void`, `len(): number`, `keys(): any[]`, `values(): any[]`, `entries(): [any, any][]`, `forEach(fn)`. (iii) **Set** — unique value collection (hash-based). Contract: `add(item)`, `has(item): bool`, `delete(item): void`, `len(): number`, `values(): any[]`. All three collections support the Iterator protocol via `[Symbol.iterator]()` returning an object with `next(): { value, done }`.

The Dryad bytecode consists of stack-based OpCodes organized into the following categories: Stack management (Push, Pop, Dup); Arithmetic (Add, Sub, Mul, Div, Mod, Pow); Logical (And, Or, Not); Bitwise (BitwiseAnd, BitwiseOr, BitwiseXor, Shift); Comparison (Equal, NotEqual, Less, Greater, LessEqual, GreaterEqual); Control Flow (Jump, JumpIfFalse, JumpIfTrue, Call, Return); Variables (GetLocal, SetLocal, GetGlobal, SetGlobal); Functions (DefineFunction, CallFunction); Objects (GetProperty, SetProperty, NewObject, NewArray); Classes (DefineClass, NewInstance, CallMethod).

The VM maintains four core structures: the Value Stack (operands and intermediate results), the Instruction Pointer (IP — current position in the bytecode stream), the Call Stack (function frame chain), and the Global Environment. The execution cycle is: Fetch (read OpCode at IP), Decode (identify operation and operands), Execute (perform the operation, manipulating the stack), Advance (increment IP), Repeat until a Return opcode or program end.

The IR is a register-based representation (unlike the stack-based bytecode) used by the AOT compiler. It is more abstract than assembly but more concrete than the AST. The IR is architecture-independent and enables classical compiler optimizations before code generation. Core structures: IrModule (compilation unit), IrFunction (function definition with parameters and body), IrInstruction (Load, Store, Add, Call, etc.), and IrValue (constants, variables, virtual registers).

The AOT compiler follows four phases: (1) Bytecode-to-IR Conversion — translates stack-based OpCodes to register-based IR, performs control flow analysis, and constructs a Control Flow Graph (CFG); (2) IR Optimization — applies constant folding, dead code elimination, and register allocation; (3) Backend Code Generation — performs instruction selection for the target architecture, physical register allocation, and assembly generation; (4) Object File Generation — produces the executable format (ELF or PE) and links with runtime libraries to produce a native binary.

ARM64: RISC 64-bit architecture with 32-bit fixed instructions, registers x0-x30, sp, pc. x86_64: CISC 64-bit architecture with variable-length instructions, registers rax, rbx, rcx, rdx, rsi, rdi, rsp, rbp, r8-r15. Object formats: ELF (Linux/Unix, sections .text, .data, .bss, .rodata) and PE (Windows, sections .text, .data, .rdata).

The AOT backend resolves function calls through statically-defined linker symbols rather than dynamic dispatch tables. Each function in the compiled IR is assigned a unique, deterministic symbol name following the scheme _D<module_hash>_<function_name>. The linker resolves cross-module references at link time, eliminating all runtime dispatch overhead. Virtual method calls on classes with a single known implementation (monomorphic sites) are devirtualized during IR optimization and replaced with direct static calls. Polymorphic sites fall back to a call *rax indirect dispatch through a vtable, but the vtable is populated at link time and resides in .rodata.

For each function with dynamic parameters, the AOT compiler generates monomorphized variants based on the types inferred at compile time. A function function add(a, b) { return a + b; } produces add_f64(f64 a, f64 b) -> f64 and add_str(string a, string b) -> string stubs. Each variant eliminates the Variant Enum discriminant check for all operations within the function body. The binding is performed once at compile time — there is no deoptimization or reoptimization (no JIT feedback loop). This avoids the runtime stutter and complexity of adaptive optimization systems (V8's TurboFan, SpiderMonkey's Warp), replacing it with a deterministic compilation that always produces the same binary for the same source.

When the AOT compiler encounters object literal construction or class instantiation, it infers a Shape (also called Hidden Class or Map) that describes the layout of properties in memory. Each Shape encodes property names and their byte offsets relative to the object base pointer. Objects sharing the same Shape access properties via load [obj + offset] instead of a HashMap lookup. Shape transitions occur when properties are added or removed; the compiler generates fast-path inline cache checks for the common Shape and a slow-path fallback. For monomorphic sites (a single Shape throughout the program), the compiler eliminates all Shape checks, producing a direct memory load identical to C++ struct member access.

The AOT compiler does not generate machine code or object files directly. Instead, it emits LLVM Intermediate Representation (LLVM IR), a low-level, platform-independent language that LLVM's optimization passes and code generation backend consume. The pipeline is: (1) Bytecode → Micro-IR (3-Address, SSA) — the stack-based bytecode is converted to a register-based intermediate representation in Static Single Assignment form, where each instruction has the form R1 = R2 op R3. This conversion uses a simple stack-to-register algorithm that tracks the expected operand types from the Metadata Header. (2) Micro-IR → LLVM IR — each Micro-IR instruction maps to one or more LLVM IR instructions. Types are mapped: f64 → double, i32 → i32, string → i8* (pointer), object → i8* (opaque pointer). Structures (tuples, objects with known Shapes) are emitted as LLVM struct types with named fields. (3) LLVM Optimization — LLVM's built-in pass manager applies constant folding, dead code elimination, loop unrolling, vectorization (SIMD), and inlining. (4) Code Generation — LLVM's backend selects target-specific instructions for ARM64 or x86_64, performs physical register allocation, and emits an object file (.o). (5) Linking — the object file is linked against the Dryad runtime library (containing the ~50 intrinsic implementations and the reference counting GC) to produce the final ELF or PE executable.

Every intrinsic syscall (open, read, write, socket, etc.) has two entry points in the C++ runtime. Fast Path (syscall_read_fast(i32 fd, ptr<u8> buf, usize len) → isize) — expects unboxed native types matching the C ABI. Arguments are passed in CPU registers following the platform calling convention. No Variant Enum construction or destruction occurs. The AOT compiler emits a direct call instruction to this entry point when the Metadata Header confirms all argument types statically. Slow Path (syscall_read_variant(Variant* args) → Variant) — accepts a Variant array, extracts and validates each argument at runtime, calls the same internal implementation, and wraps the result in a Variant. Both paths share the same internal logic (internal_read). The VM and interpreter always use the Slow Path. The AOT compiler selects between Fast and Slow Path per-call-site: if all arguments have STATIC or OBSERVED types, Fast Path is used; if any argument is UNKNOWN (genuinely dynamic), Slow Path is used. This dual-port design ensures zero overhead for statically-typed code paths while preserving correctness for dynamic code — without duplicating the intrinsic implementation.

Dryad supports full OOP: encapsulation via access modifiers (public, private, protected), single inheritance via extends, polymorphism via method overriding, and abstraction via classes and interfaces. Static members belong to the class rather than instances.

Functional features include: first-class functions (functions as values), higher-order functions (functions accepting or returning functions), closures (lexical scope capture), arrow functions (concise syntax with implicit return for single-expression bodies), and partial immutability via const declarations.

Procedural programming is supported through top-level functions (no class wrapper required), global and local variables, structured control flow (loops, conditionals), and no mandatory object-oriented constructs. This paradigm is ideal for scripts, automation tasks, and small-to-medium programs.