MaddLang Gold Standard

This document specifies the gold profile, including source parsing, bytecode encoding, opcode tags, runtime flags, and file I/O behavior.

1. File Roles

.mlg: gold source.
.mlb: serialized MaddLang bytecode.
.mls: silver source, interpreted with restricted runtime permissions.

2. Source Syntax

Identifiers, function names, suite names, and variable names are case-sensitive.
Source keywords are lowercase and matched exactly.
Typed declaration syntax: type name = value.
Typed arrays: type[] name = [value, value].
Indexed assignment: name[index] = value.
Runtime reference read: $name or $name[index].
Call syntax: name(arg, arg) or space/comma-separated invocation forms.
Blocks: if ... { ... }, while ... { ... }, fn ... { ... }, suite ... { ... }.
suite is supported for compatibility, but it is not the recommended gold form; use fn for new code.

3. Type Names

Accepted lowercase source types are:

any
null
bool
string
number
array, array<type>, array[type]
u8, u16, u32, u64, uint, umax
i8, i16, i32, i64, int

Semantic mapping:

umax is the canonical machine-sized unsigned bridge type for address conversion.
uint is an accepted alias for umax in source, but umax is the standard spelling for pointer creation and address-bearing values.
int means machine-sized signed integer and maps to IMax in the compiler type model.
Typed references are runtime-safe handles to storage, not raw pointers.
Only umax may be converted into a pointer-like runtime address bridge in gold mode.

4. Source Compilation Pipeline

Normalize newlines to \n.
Apply compile-time preprocessing directives.
Parse blocks and top-level lines.
Run type checking.
Emit in-memory chunk bytecode.
Optionally serialize to .mlb.

5. Compile-Time Directives

Directives are evaluated before normal parsing.

Directive	Meaning	Notes
`$(name: value)`	Sets a compile-time variable.	The stored value may itself reference other compile-time variables.
`$(define: name = value)`	Defines an expanded alias.	The right-hand side is recursively expanded before storage.
`$(if expr)`	Begins compile-time conditional inclusion.	Nested conditionals are supported.
`$(else)`	Switches the active branch.	Only valid inside an open `$(if)`.
`$(endif)`	Closes the conditional.	Only valid inside an open `$(if)`.

Condition operators supported by the compile-time evaluator:

==
!=
contains
startswith
endswith
truthy fallback when no operator is present

6. Compiler Flags

The CLI seeds the compile-time environment before parsing.

Flag	Effect
`--std VALUE`	Sets compile-time `STD` to `VALUE`.
`--define NAME=VALUE`	Sets a compile-time name/value binding.
`--flag NAME`	Sets `NAME=true`.
`--flag NAME=VALUE`	Sets `NAME` to the explicit string value.

7. Bytecode File Format

All multibyte integers are little-endian. String lengths are encoded as u64 byte counts followed by raw UTF-8 bytes.

7.1 Program layout

magic[4] = "MLB1"
main_chunk
function_count: u64
repeat function_count times:
  name: string
  chunk
suite_count: u64
repeat suite_count times:
  name: string
  chunk

7.2 Chunk layout

constant_count: u64
repeat constant_count times:
  value
code_count: u64
repeat code_count times:
  opcode

7.3 Value encoding

Tag	Name	Payload
`0x00`	Null	none
`0x01`	Bool	1 byte, `0x00` false or `0x01` true
`0x02`	Number	8-byte IEEE-754 f64 little-endian
`0x03`	String	`u64` length + UTF-8 bytes
`0x04`	Array	`u64` item count + recursively encoded values
`0x05`	Ref	`u64` length + UTF-8 reference name

7.4 Opcode encoding

The opcode tag is one byte, followed by the payload shown below.

Tag	Opcode	Payload	Meaning
`0x00`	`LoadConst`	`u64 const_index`	Push constant at index.
`0x01`	`LoadVar`	string variable name	Load runtime variable value.
`0x02`	`DeclareVar`	string name + string type_name	Declare a typed runtime variable.
`0x03`	`StoreIndex`	string name + `u64 index`	Store into array element.
`0x04`	`StoreVar`	string name	Store into a variable.
`0x05`	`LoadArray`	`u64 count` + encoded values	Push array literal.
`0x06`	`Concat`	`u64 count`	Concatenate stack values as strings.
`0x07`	`Add`	none	Add two numeric operands.
`0x08`	`Sub`	none	Subtract two numeric operands.
`0x09`	`Mul`	none	Multiply two numeric operands.
`0x0A`	`Div`	none	Divide two numeric operands.
`0x0B`	`Mod`	none	Modulo two numeric operands.
`0x0C`	`Neg`	none	Negate the top numeric operand.
`0x0D`	`Call`	string name + `u64 argc`	Invoke builtin or chunk.
`0x0E`	`Jump`	`u64 target_ip`	Unconditional branch.
`0x0F`	`JumpIfFalse`	`u64 target_ip`	Pop condition; branch if falsey.
`0x10`	`Return`	none	Return from current chunk.
`0x11`	`Pop`	none	Discard top of stack.
`0x12`	`Noop`	none	No operation.

Exact byte tags are fixed and must remain stable for cross-platform .mlb compatibility.

8. Runtime Semantics

Truthiness rules apply to numbers, strings, arrays, bools, and null.
Variables are stored with optional declared types.
Typed assignments are checked at compile time and again at runtime where needed.
Array element writes are validated against the array element type.
String concatenation uses runtime scratch allocation for transient assembly.
Arithmetic is supported via dedicated opcodes for +, -, *, /, %, and unary negation.

9. Expression Precedence

Expression parsing follows a C-like precedence hierarchy. Higher rows bind tighter.

Level	Operators	Associativity	Notes
1	parentheses `( )`, indexing `[ ]`	left-to-right	Grouping and indexed access are resolved first.
2	unary `-`	right-to-left	Negates a single numeric operand.
3	`*`, `/`, `%`	left-to-right	Multiplicative operators.
4	`+`, `-`	left-to-right	Additive operators.
5	comparisons and condition operators	left-to-right	Handled in conditional parsing, not general arithmetic.

10. File I/O Rules

Only gold mode may access files.
open(path, mode) returns a VM-owned integer handle.
Supported modes are r, w, and a.
read(handle), write(handle, value), and close(handle) operate through the VM handle table.
Silver mode must return a silver-specific access error.

11. Reference Model

$name resolves the current value of a variable and respects identifier case.
$name[index] resolves an array element or null if invalid.
These are runtime references, not raw pointers.
Pointer arithmetic is not part of the source language.
Low-level address conversion, if exposed, must be gated through umax only.

12. Reference and Pointer Bridge

Gold may expose pointer creation only from umax.
Gold references are typed storage handles, not raw pointers.
ref<T> refers to a typed reference handle used for mutation and typed access.
ref<T> construction from a umax value must be explicit and validated by the runtime.
Silver does not expose direct pointers; it only uses references.

13. Function Parameters

Functions may declare parameters in the block header: fn name(param, ref<type> target) { ... }.
Plain parameters are passed by value into a local scope.
ref<type> parameters receive reference handles and can mutate the caller-visible storage.
Local variables shadow outer variables inside the function scope.
Function calls evaluate arguments left to right before entering the callee scope.

14. Example

string name = "gold"
umax fh = open("./testfile.txt", "w")
write(fh, "hello\n")
close(fh)
print($name)

That program is valid in gold mode and invalid in silver mode if it attempts file I/O.

Silver is also the debugging-oriented interpreted profile, so gold authors should prefer fn over suite unless compatibility with older source matters.