Viper Compiler Platform - Release Notes

Development Status: Pre-Alpha
These are early development releases. Viper is under active development and not ready for production use.
Future milestones will define supported releases when appropriate.

Version 0.2.3 - Pre-Alpha (March 25, 2026)

Release Overview

Version 0.2.3 is a major hardening, tooling, and infrastructure release. Highlights:

3D Graphics Engine — 28-class engine with scene graph, skeletal animation, physics, particles, terrain, post-processing, and FBX loading. Four backends: Metal, D3D11, OpenGL, software rasterizer.
Native Assembler + Linker — zero external tool dependencies. Source → executable using only Viper's own code. DWARF v5 debug info, ICF, branch trampolines, Mach-O two-level namespace.
Enum Types — for both Zia and BASIC, with match exhaustiveness checking.
Language Server — dual-protocol (LSP + MCP) zia-server for editors and AI assistants.
AArch64 Performance — post-RA scheduler, register coalescer, loop-invariant hoisting, cross-block store-load forwarding, division strength reduction. 24-87% benchmark improvements on Apple M4 Max.
3 New IL Optimizer Passes — EH optimization, loop rotation, reassociation. Full O2 pipeline restored (10 passes were missing from native codegen).
Interactive REPL — viper repl for both Zia and BASIC with tab completion, persistent history, and meta-commands.
O1 Native Codegen Correctness — 10+ optimizer bug fixes enabling reliable -O1 compilation across all demos. Inliner escape analysis, DCE alloca observation, SimplifyCFG param preservation, and compilation performance (27x speedup for medium modules).
Network Runtime Expansion — comprehensive security audit of 14K lines + 10 new networking classes (HttpServer, WebSocketServer, ConnectionPool, SmtpClient, etc.) + AES-128-GCM cipher suite.
Comprehensive Safety Audits — VM, codegen, runtime, network, 3D graphics, and concurrency hardening with TSan verification.
Backend Codegen Review — decomposed monolithic files, CFG-aware register allocation liveness, shared infrastructure across both backends.
Game Engine Framework — GameBase/IScene, screen transitions, A* pathfinding, SaveData, DebugOverlay, SoundBank/Synth.
Language Audit — comprehensive Zia/BASIC feature verification (13 findings: 6 confirmed fixed, 7 filed as open bugs), reference doc corrections, 13 new Zia feature/runtime tests.
Frontend Decomposition — shared utilities, parser/lowerer file splits, CRTP LexerBase.
Codebase Reorganization — demos consolidated into examples/, devdocs merged into docs/, 900+ doc fixes.

By the Numbers

Metric	Value
Commits	100
Files changed	3,557
Lines added	~279K
Lines removed	~323K
Source files	2,671
Test count	1,351
Codebase	~348K SLOC (production C/C++/ObjC)

New Features

Interactive REPL

A full-featured interactive REPL accessible via viper repl, zia (no args), or vbasic (no args).
Built on the TUI framework's TerminalSession/InputDecoder for raw-mode terminal I/O — zero external
dependencies.

Expression auto-print with type-aware coloring (Bool/Int/Num/String/Object)
Variable and function persistence across inputs via statement replay
Entity, value, and interface definition support
Multi-line input via bracket depth (Zia) and block keyword tracking (BASIC)
Tab completion via CompletionEngine (Zia) and keyword matching (BASIC)
Meta-commands: .help, .quit, .clear, .vars, .funcs, .binds, .type,
.il, .time, .load, .save
Persistent history (~/.viper/repl_history_{lang}), double Ctrl-C exit
Non-interactive piped input mode
Windows support via _pipe/_dup/_dup2/_read stdout capture
86 unit tests (51 Zia + 35 BASIC)

$ zia
zia> var x = 42
zia> x * 2
84 : Integer
zia> .il
; IL output for last expression...

Native Assembler and Linker

A complete in-process assembler and linker that eliminates all external tool dependencies (as, ld,
link.exe) from the native compilation pipeline. Viper can now go from source to executable using
only its own code — zero external dependencies, true to the project philosophy.

Assembler (MIR → .o)

Binary encoders for both x86-64 (49 opcode encodings, REX/ModR/M/SIB, RIP-relative relocations)
and AArch64 (70+ opcodes, branch resolution, FP literal materialization)
Object file writers for ELF (x86_64 + AArch64), Mach-O (x86_64 + AArch64), and PE/COFF (Windows)
Per-function text sections for dead stripping
--native-asm / --system-asm CLI flags to choose pipeline

Linker (.o + archives → executable)

Archive reader supporting GNU ar, BSD ar, and COFF archive formats
Object file readers for ELF, Mach-O, and COFF with unified ObjFile API
Symbol resolution with weak/strong precedence and archive demand-pull
Section merging with ObjC metadata preservation and page-aligned layout
Relocation application for x86-64 and AArch64 (PC-rel, absolute, ADRP/PageOff12)
Executable writers for Mach-O (dyld bind opcodes, GOT generation), ELF (program headers,
dynamic section), and PE (import tables, DOS stub)
Native ad-hoc code signing with CS_LINKER_SIGNED flag (arm64 macOS)
--native-link / --system-link CLI flags

Optimizations

Mark-and-sweep dead section stripping (DeadStripPass) — ~53% binary size reduction
Cross-module string deduplication (promotes duplicate LOCAL rodata to shared GLOBAL symbols)
Segment-level VA packing instead of per-section page alignment
Debug/metadata section filtering

Debug Info & Advanced Linker Features

DWARF v5 .debug_line section encoding via DebugLineTable — maps machine instructions back
to source file, line, and column for debugger integration
Non-alloc debug section handling across all three executable writers:
ELF (SHT_PROGBITS without SHF_ALLOC, emitted after PT_LOAD segments),
Mach-O (__DWARF segment with vmaddr=0, no VM permissions),
PE (IMAGE_SCN_MEM_DISCARDABLE, excluded from SizeOfImage)
Identical Code Folding (ICF) pass — merges functions with byte-identical .text content and
matching relocations, reducing binary size for template-heavy or copy-heavy codegen output
Branch trampoline generation for out-of-range relocations — automatically inserts veneer stubs
when branch targets exceed architecture-specific displacement limits (±128MB on AArch64,
±2GB on x86-64)
OutputSection.alloc flag distinguishes loadable sections from debug/metadata sections

Mach-O Two-Level Namespace

Add MH_TWOLEVEL flag to Mach-O header, replacing flat namespace resolution. Required for
macOS ARM64 — without it, CoreAnimation PAC pointer authentication traps fire ~1 second after
window creation
Per-symbol dylib ordinal assignment in bind opcodes using
BIND_OPCODE_SET_DYLIB_ORDINAL_IMM/ULEB instead of flat lookup
Flat lookup (ordinal -2) fallback for OBJC_CLASS_$/OBJC_METACLASS_$ symbols whose defining
framework can't be determined by prefix alone
Fix dylib detection to strip leading underscores before prefix matching (handles
_objc_empty_cache, __CFConstantStringClassReference)
Update nlist library ordinals in symbol table for two-level namespace compatibility

Hardening

Archive member size limits, relocation bounds checks, section/symbol count caps
isCStringSection flag prevents string dedup from corrupting binary data sections
Expanded dynamic symbol recognition to avoid false undefined-symbol errors

Assembler & Linker Layer Review (15 items)

Systematic review and refactoring of the native assembler/linker infrastructure:

Reverse-index map for findOutputLocation (O(S×C) → O(1) lookup)
Named relocation constants (RelocConstants.hpp) replacing magic numbers
Shared ObjFileWriterUtil.hpp deduplicating 3× appendLE/alignUp/padTo implementations
Centralized Mach-O name mangling (NameMangling.hpp)
Extracted relocation classification (RelocClassify.hpp, 189 LOC)
Immediate range validation asserts (AArch64 imm12, x86-64 imm32)
Dead-strip statistics reporting to stderr
Shared segment layout utilities (classifySections, computeSegmentSpan)
Local symbol offset bounds check in RelocApplier
Split MachOExeWriter (1,029 → 670 LOC) into MachOCodeSign + MachOBindRebase modules
Data-driven framework detection (kFrameworkRules[] table replacing ad-hoc prefix checks)

All 11 demos build and run with the native pipeline. 13 new assembler tests, 6 string dedup tests,
11 debug line tests, 9 debug section tests, 10 ELF exe writer tests, 7 linker integration tests,
plus ICF, branch trampoline, symbol resolver, and relocation edge-case test suites.

Zia Language Server (zia-server)

A dual-protocol language server supporting both MCP (for AI assistants) and LSP (for editors):

JSON value type + recursive-descent parser/emitter (zero dependencies)
MCP transport (newline-delimited) with 11 tool definitions for AI assistants
LSP transport (Content-Length framed) with diagnostics, completions, hover, and document symbols
JSON-RPC 2.0 request/response handling
CompilerBridge facade wrapping Zia compiler APIs, including entity field hover
VS Code extension with auto-discovery of zia-server binary
Completion engine improvements for both Zia and BASIC frontends

Zia Language Features

Enum Types

Enumeration types for both Zia and BASIC frontends:

enum Color { Red, Green = 5, Blue }
match c {
    Color.Red => Say("red")
    Color.Green => Say("green")
    _ => Say("other")
}

Zia: enum declaration, explicit/auto-increment values, expose visibility, match exhaustiveness
checking, variant access via dot notation
BASIC: ENUM...END ENUM blocks, explicit/negative values, keyword-as-name collision handling
Variants lowered as I64 constants; 16 Zia + 8 BASIC enum tests

Match OR Patterns

match x {
    1 | 2 | 3 => Say("small")
    10 | 20 => Say("round")
    _ => Say("other")
}

New Pattern::Kind::Or supports pipe-separated alternatives in match arms. Lowered as a waterfall
of test blocks — each subpattern's success jumps to the arm body, failure falls through to the next.

Typed Catch with List Shorthand

Exception handlers can now specify a type for the caught error, with list-literal shorthand syntax.

Say/Print Auto-Dispatch

Say(42), Say(3.14), Say(true) now work without explicit .ToString() conversion via typed
runtime variants (SayInt, SayNum, SayBool, PrintBool).

.Len → .Length Rename

Collection .Len property renamed to .Length across List, Map, and Set for consistency with the
language specification. .Len remains as an alias for backward compatibility.

Bible Audit Remediation

Three missing platform features identified by the comprehensive documentation audit:

Http.Put/Delete: Http.Put(), PutBytes(), Delete(), DeleteBytes() completing the full
REST verb set
Range iteration: .rev() for reverse iteration and .step(n) for stepped iteration in
for i in range loops
Color constants: Color.RED through Color.ORANGE (10 named constants) as static properties

Plus 900+ documentation fixes across the Bible reference manual.

Language Audit

Comprehensive end-to-end verification of all documented Zia and BASIC language features against the
live compiler and runtime. Validated every feature claimed in the reference documentation, filed a
structured bug report (docs/bugs/language_audit_2026_03_25.md) with 13 findings:

Confirmed Fixed (6)

Enum variant values (previously all evaluated to 0)
String instance methods (.Trim(), .Replace(), .Split())
Async/await syntax and runtime execution
Deinit destructor field bindings
BASIC EXPORT keyword
Entity property getter/setter resolution

Open Bugs Filed (7)

ZIA-BUG-001: Guard clause narrowing for optional primitives at lowering
ZIA-BUG-003: Match arms don't accept bare return after =>
ZIA-BUG-004: Properties — getters/setters parse but hit sema/lowering errors
ZIA-BUG-005: Typed catch (catch (e: Error)) not yet supported
ZIA-BUG-006: Tuple destructuring not supported in Zia
ZIA-BUG-007: Child entity overriding parent init() with different args
BASIC-BUG-001: FOR EACH loop off-by-one on collection iteration

Reference Documentation Corrections

Zia reference: fixed try/catch syntax examples, added OR pattern documentation,
added limitation notes for properties and tuples, removed stale enum bug note
BASIC reference: added EXPORT keyword documentation

New Runtime Test Programs (6)

33_enum_runtime.zia — enum declaration, variant access, match exhaustiveness
34_async_functions.zia — async/await with Future.Get runtime calls
35_optional_primitive_narrowing.zia — guard clause narrowing for Integer?
36_entity_properties.zia — getter/setter property declarations
37_string_instance_methods.zia — .Trim(), .Replace(), .Split(), .Contains()
38_deinit_bindings.zia — destructor field binding propagation

IL Optimizer — Three New Passes

EH Optimization (eh-opt)

Removes redundant eh.push/eh.pop pairs when the protected region contains no
potentially-throwing instructions (calls, traps, checked operations). Dead handler blocks are
cleaned up by subsequent DCE/SimplifyCFG. Registered in the O2 pipeline after check-opt.

Loop Rotation (loop-rotate)

Converts while-style loops into do-while form by duplicating the header condition into the latch
block and inserting a guard for the initial check. Eliminates one branch per iteration and improves
LICM/unrolling opportunities. Conservative: only rotates single-latch, single-exit loops with pure
headers. Registered in the O2 pipeline after loop-simplify.

Reassociation (reassociate)

Canonicalizes operand order for commutative+associative integer ops (Add/Mul/And/Or/Xor). Placed
before EarlyCSE in the O2 pipeline to expose more common subexpression elimination opportunities.

IL Optimizer — Pass Improvements

EarlyCSE: Fixpoint iteration (max 4 passes) for multi-pass CSE
LICM: Refined load hoisting — allows non-escaping alloca loads past modifying calls via
BasicAA::isNonEscapingAlloca() accessor
ValueKey: Add ConstStr and GAddr to safe CSE opcodes, eliminating redundant address
materializations in EarlyCSE/GVN
Verifier: Replace reachability check with full Cooper-Harvey-Kennedy dominator computation
for proper dominance verification of SSA uses
SCCP: Block parameters treated as SSA φ-nodes merging only from executable predecessors
Inliner: CallGraph SCC analysis (Tarjan) to prevent inlining mutually-recursive functions;
cost model tuning (maxCodeGrowth=2000) and O1 pipeline integration
SimplifyCFG: Convert hard verification asserts to soft early-returns for fuzz test
compatibility
CheckOpt: Remove incorrect overflow-to-plain demotion that violated IL spec (verifier
requires signed arithmetic to use .ovf variants); overflow constant folding deferred to
ConstFold pass
DCE: Fix predEdges map invalidation after instruction removal (vector pointer stability)

O1 Optimizer Correctness & Performance

Major O1 optimization pipeline audit fixing multiple correctness bugs discovered through native
demo testing. All 11 demos now compile at O1; 9 of 11 run correctly at native -O1.

Correctness Fixes

Inliner escaped value type resolution: Call instruction types are canonically Void in the
parser. The inliner's escaped value analysis now resolves actual return types from the module's
function lookup table instead of using the Void instruction type — fixes paint app O1 crash
Inliner temp name uniquification: Append _il{id} suffix to cloned block params and
instruction results to prevent name collisions between caller and callee scopes
DCE alloca observation tracking: Split alloca tracking into two passes (collect then observe)
to prevent late-defined allocas from overwriting earlier observation marks. Added observation
checks for store-value operands, return operands, and branch arguments
DCE entry block param protection: Never remove function-argument block parameters from the
entry block — external callers pass a fixed argument count matching the function signature.
Uses positional ABI prefix preservation with funcParamId fast-path
SimplifyCFG entry block param protection: Same fix applied to canonicalizeParamsAndArgs
in SimplifyCFG's parameter canonicalization pass
BranchVerifier Void compatibility: Allow Void-typed branch arguments (from DCE-orphaned
definitions) as compatible with any parameter type, since the register allocator tracks
liveness independently of IL types
AArch64 LoopOpt disabled: The hoistLoopConstants peephole pass incorrectly identified
non-loop control flow (if/else merges, function exits) as loops, removing MovRI instructions
from mutually exclusive code paths — caused black ghosts in pacman and crashes in paint
Multi-block inlining restricted: blockBudget=1 limits inlining to single-block callees
until multi-block continuation value threading is hardened. Single-block functions (getters,
setters, simple helpers) are the highest-value inline targets
IL peephole removed from O1: The peephole's global replaceAll creates cross-block SSA
violations when DCE's block param compaction runs afterward. SCCP already handles constant
folding; the AArch64 codegen peephole handles machine-level optimizations
LICM readonly call safety: Conservative guard prevents hoisting readonly calls when the
loop contains mutating memory operations

Compilation Performance

SimplifyCFG verification hooks removed: Debug-only Verifier::verify() calls inside
SimplifyCFG verified the entire module per function per iteration (up to 40 full-module
verifications for a single SimplifyCFG invocation). Replaced with no-ops — the PassManager's
-verify-each flag provides equivalent functionality when needed. 27x speedup for
medium-sized modules (viperide: 4 minutes → 8.5 seconds)
Large module auto-downgrade: Modules exceeding 100K instructions skip IL optimization
entirely to avoid O(n^2) behavior in SimplifyCFG and other passes. The AArch64 codegen
peephole still runs. Reduces sqldb compilation from 8+ minutes to 11 seconds

Alloca Escape Verification

New Pass 4 in FunctionVerifier warns when a ret instruction directly returns an alloca-derived
pointer, catching dangerous stack-pointer escapes at verification time.

Zia Lowering Optimizations

Virtual dispatch: O(N) if-else chain replaced with SwitchI32 for multi-implementation
method dispatch
Match expressions: SwitchI32 fast path for integer-only match arms without guards,
falling back to generic lowering otherwise

Async/Await Syntax

New async/await keywords with AST nodes, parser support, semantic checking, and lowering to
Future.Get runtime calls:

func fetchData() -> String {
    var result = await Http.GetAsync("https://example.com/data");
    return result;
}

Multi-Language Benchmark Suite

Cross-language benchmark programs for performance comparison across C, C#, Java, Lua, Python, and
Rust. Covers arithmetic stress, branch stress, call stress, fibonacci, inline stress, mixed stress,
redundant stress, string stress, and unsigned division stress. Matching IL benchmark programs for
direct Viper performance measurement.

AArch64 Exception Handling

Full EH opcode support for the AArch64 backend: EhPush, EhPop, EhEntry, TrapDiv,
TrapOvf, TrapIdx, TrapNull, TrapCast, ErrGetMsg, ErrGetCode, Resume.

SipHash-2-4 Hash Function

Replace FNV-1a with keyed SipHash-2-4 using per-process random seed from OS CSPRNG for HashDoS
resistance in all runtime hash maps.

GC Epoch Tagging

Per-entry survival counter skips promoted objects in trial-deletion, with periodic full scans to
catch new cycles. Reduces GC overhead for long-lived objects.

AArch64 PassManager

Wire existing pass infrastructure into AArch64 CodegenPipeline, replacing monolithic per-function
loop. Brings the ARM64 backend architecture in line with x86-64.

AArch64 Performance Optimizations

Major performance work across the AArch64 backend, adding several new optimization passes:

Post-RA Instruction Scheduler

List scheduler running after register allocation with latency-based priority ordering and
anti-dependency tracking. Reorders instructions within basic blocks to improve pipeline utilization
while respecting data dependencies and register constraints.

Register Coalescer

Pre-regalloc MovRR/FMovRR elimination via live interval interference analysis (~270 LOC).
Reduces unnecessary register-to-register moves by merging compatible live ranges before linear scan
allocation. Integrated into the pipeline before the register allocator pass.

MIR Loop-Invariant Constant Hoisting

Hoists MovRI (move-immediate) instructions from loop bodies into preheader blocks when the
register is callee-saved (x19-x28) and defined only by MovRI with the same immediate value
throughout the loop. Uses natural loop body computation via reverse-reachability BFS from the latch
through predecessors, correctly handling non-contiguous loop bodies (blocks placed after the latch in
layout order).

Cross-Block Store-Load Forwarding

Peephole optimization that forwards stores to loads across basic block boundaries when the layout
predecessor has a single successor and the store/load access the same FP-relative offset. Includes
reachability verification to ensure the predecessor actually reaches the successor (unconditional
branch, conditional branch target, or fallthrough).

Division/Modulo Strength Reduction

Peephole pass that replaces expensive SDIV/UDIV/SREM/UREM instructions with cheaper sequences:

SDIV by power-of-2: sign-corrected arithmetic shift (22 cycles → 4 cycles)
SDIV by arbitrary constant: magic number multiply-high (22 cycles → 6-8 cycles)
UREM by power-of-2: AND mask (26 cycles → 1 cycle)
SREM by power-of-2: sign-corrected AND+SUB (26 cycles → 5 cycles)

Full O2 Pipeline Restoration

Restored 10 missing IL optimization passes to the native codegen O2 pipeline: loop-simplify,
loop-rotate, indvars, loop-unroll, check-opt, eh-opt, sibling-recursion, constfold, licm,
reassociate. The codegen pipeline was running a stripped-down O1-level optimizer despite requesting
-O2. Also fixed x86-64 codegen O2 gating threshold.

Benchmark Results (Apple M4 Max, native -O2 vs previous baseline):

Benchmark	Before	After	Improvement
branch_stress	180ms	24ms	-87%
redundant_stress	315ms	104ms	-67%
mixed_stress	83ms	30ms	-63%
udiv_stress	180ms	74ms	-59%
inline_stress	144ms	79ms	-46%
call_stress	45ms	34ms	-24%
arith_stress	140ms	119ms	-15%

Additional Peephole Optimizations

CSET+branch fusion: Fuses compare-and-set with subsequent conditional branch for tighter
conditional sequences
Dead FP store elimination: Removes redundant floating-point stores to the same stack slot
Leaf function register preference: Prefers low-numbered (caller-saved) registers for leaf
functions that don't need callee-saved save/restore
Logical immediate emission: Proper AArch64 encoding for AND/ORR/EOR immediate operands
Dead overflow DCE: Correct elimination of unused overflow-checked arithmetic results
SmulhRRR opcode: New MIR opcode for proper signed multiply-high overflow detection

Peephole Decomposition

Split the monolithic 2,750-line AArch64 Peephole.cpp into 6 focused sub-passes under peephole/:
IdentityElim, StrengthReduce, CopyPropDCE, BranchOpt, MemoryOpt, LoopOpt. Shared
peephole templates (PeepholeDCE.hpp, PeepholeCopyProp.hpp) parameterized on target traits are
used by both AArch64 and x86-64 backends.

x86-64 Backend Improvements

Comprehensive Backend Codegen Review — 20-item systematic review of both backends with
improvements across modularity, shared infrastructure, and test coverage:

x86-64 Peephole Decomposition

Split the 1,470-line monolithic Peephole.cpp into 4 focused sub-passes under peephole/:
ArithSimplify (MOV-zero→XOR, CMP-zero→TEST, strength reduction), MovFolding (redundant MOV
elimination), DCE (dead code elimination with implicit register tracking), BranchOpt (branch
optimization and cold block reordering). Peephole iteration now bounded by kMaxIterations=100.

CFG-Aware Register Allocation Liveness

Replaced the conservative "unconditional spill" hack (which force-spilled ALL cross-block vregs)
with proper backward dataflow liveness analysis. The new LivenessAnalysis class computes per-block
liveIn/liveOut sets using the standard fixed-point iteration, so only vregs that are truly live
across block boundaries get spill slots. This is the same algorithm used by production compilers.

Shared Dataflow Solver

Extracted the backward dataflow liveness algorithm into a shared template
(common/ra/DataflowLiveness.hpp) used by both x86-64 and AArch64 backends. The AArch64 allocator's
inline liveness code was extracted into a separate Liveness class (matching x86-64's pattern),
both now delegating to the shared solver. Also includes a shared buildPredecessors() utility.

Shared Linker Utilities

Common encoding utilities (ExeWriterUtil.hpp) shared between Mach-O and PE executable writers:
writeLE16/32/64, writeBE32/64, writeULEB128, writePad, padTo, and resolveMainAddress().
ObjC dynamic stub generation extracted from the native linker into DynStubGen.hpp/cpp.

Additional Improvements

LoweringRuleTable.hpp declarations moved to .cpp for faster incremental compile times
AArch64 division handlers parameterized (4 near-identical → shared lowerDivisionChk)
AArch64 OpcodeDispatch refactored with handler table replacing 1K-line switch
AArch64 AsmEmitter consolidated with emit2Op/emit3Op primitives
SchedulerPass hash maps replaced with vector<optional<>> for O(1) cache-friendly lookup
CopyPropDCE MovRR/FMovRR logic parameterized (90% duplication eliminated)
Shared prologue/epilogue iteration (FrameCodegen.hpp) eliminates callee-saved
register save/restore duplication between AsmEmitter and BinaryEncoder
x86-64 peephole fixed-point iteration with kMaxIterations=100 bound

Game Engine Framework (10-Item Improvement Plan)

A comprehensive game development infrastructure built as pure Zia libraries and C runtime additions:

GameBase + IScene (Zia library) — Reusable game loop framework. GameBase entity handles canvas
creation, frame pacing, DeltaTime clamping, and scene management. IScene interface defines
update/draw/onEnter/onExit lifecycle. Eliminates ~100 lines of boilerplate per game.

Screen Transitions — transitionTo() on GameBase orchestrates fade-out → scene switch → fade-in
using ScreenFX. Also adds shake() and flash() for screen effects.

Action Presets (C runtime) — Action.LoadPreset("platformer") loads standard input bindings in
one call. Four presets: standard_movement, menu_navigation, platformer, topdown.

Canvas Frame Helpers (C runtime) — BeginFrame() combines Poll + ShouldClose check.
SetDTMax() auto-clamps DeltaTime. Text layout: TextCentered, TextRight, TextCenteredScaled.

SaveData (C runtime) — Cross-platform key-value persistence. JSON storage in platform-appropriate
directories (macOS Application Support, Linux XDG, Windows AppData).

DebugOverlay (C runtime) — Real-time FPS/dt/watch variable overlay with color-coded FPS,
16-frame rolling average, and up to 16 custom watch entries.

SoundBank + Synth (C runtime) — Named sound registry maps string names to Sound objects.
Procedural synth generates tones, sweeps, noise, and 6 preset game SFX (jump/coin/hit/explosion/
powerup/laser) without WAV files. Uses Bhaskara I sine approximation and in-memory WAV generation.

Platformer Showcase Demo — ~600 LOC across 6 files demonstrating 11+ runtime APIs in one
cohesive game: Tilemap, Camera, CollisionRect, StateMachine, SpriteAnimation, ObjectPool,
PathFollower, ButtonGroup, DebugOverlay, ScreenFX, and Action presets.

Demo Refactoring — Sidescroller demo refactored to use StateMachine (replacing manual integer
state tracking) and ButtonGroup (replacing manual selection management).

New Runtime APIs

AnimStateMachine — Combined state machine and animation playback controller. Maps each
state to an animation clip (frame range, duration, loop flag). Transitions automatically
reconfigure the internal animation. Surfaces CurrentFrame, IsAnimFinished, Progress,
JustEntered/JustExited edge flags, and FramesInState. Eliminates the boilerplate of
manually wiring StateMachine and SpriteAnimation together in every character controller.

TextureAtlas — Named-region 2D sprite sheet atlas. Maps string names to rectangular sub-regions
of a Pixels buffer, enabling content pipelines where frames are referenced by name instead of raw
pixel coordinates. Supports grid-based auto-slicing (LoadGrid) and manual region definition (Add).
Integrates with SpriteBatch via DrawAtlas, DrawAtlasScaled, and DrawAtlasEx methods.

Canvas.DeltaTime — Milliseconds elapsed since the last frame, available as a property. Combined
with Canvas.SetDTMax() for automatic delta-time clamping, this enables frame-rate-independent
physics without manual timer management.

ParticleEmitter Rendering — ParticleEmitter.Draw(), DrawAt(), and DrawToPixels() methods
for rendering particle systems directly, eliminating the need for manual particle array iteration in
game loops.

Camera Parallax Layers — Camera.AddParallaxLayer(), RemoveLayer(), ClearLayers(), and
DrawParallax() for multi-layer parallax scrolling backgrounds with configurable scroll speeds.

Camera.SnapTo — Instant camera repositioning for level transitions and respawn events, bypassing
the normal smooth-follow interpolation.

3D Graphics Engine (Graphics3D)

A complete 3D graphics engine built as a zero-dependency C runtime module with pluggable GPU backends.

Core Architecture

Scene graph with frustum culling and node hierarchy (Scene3D, SceneNode3D)
Transform system with parent-child propagation (Transform3D)
Material system with PBR properties, environment mapping, and emissive surfaces (Material3D)
Camera system with shake, follow, and smooth interpolation (Camera3D)
Light system with point, directional, and spot lights (Light3D)

Rendering

Four backends: Metal (macOS), D3D11 (Windows), OpenGL (Linux), software rasterizer (fallback)
Multi-pass rendering pipeline with alpha blending and depth sorting
Render-to-texture for post-processing and offscreen rendering (RenderTarget3D)
Post-processing effects: bloom, vignette, color grading, screen-space effects (PostFX3D)
Skybox rendering with cubemap support (CubeMap3D)
Instance batching for efficient rendering of repeated meshes (InstanceBatch3D)
Decal projection (Decal3D), terrain rendering (Terrain3D), water simulation (Water3D)

Animation & Physics

Skeletal animation with bone hierarchies and blend trees (Skeleton3D, Animation3D, AnimBlend3D, AnimPlayer3D)
Morph targets for facial animation and mesh deformation (MorphTarget3D)
Character controller combining skeletal animation and physics (Character3D)
3D physics with rigid bodies and trigger volumes (Physics3DBody, Physics3DWorld, Trigger3D)

Navigation & Loading

Navigation mesh for AI pathfinding (NavMesh3D)
Path system for waypoint-based movement (Path3D)
FBX file loader for importing meshes, skeletons, and animations (FBX)
Raycasting for object picking and interaction (RayHit3D)
Particle systems (Particles3D)

28 classes total. Documented in Graphics3D Guide and Graphics3D Architecture.

Comprehensive Safety Audits

The bulk of this release is a multi-phase safety audit touching every layer of the platform.

VM Execution Loop (8 fixes)

Convert assert-only guards to runtime traps in branch target lookup, switch index, and EH handlers
Add null guard for prepareTrap handler
Fix fr.func->name null checks in trap diagnostics
Add defensive operand checks for trap/EH ops

x86-64 Codegen (9 fixes)

EFLAGS clobber: Guard MOV-zero→XOR peephole against EFLAGS clobber between TEST and CMOV
(silent miscompilation for select with falseVal=0)
Block arguments: Extend EdgeArg with argValues to carry full ILValue data for constant
block arguments; materialize constants into fresh vregs via MOVri/MOVSDmr before PX_COPY
Peephole DCE: Fix implicit register liveness for CQO (reads RAX) and IDIV/DIV (reads RAX+RDX)
— DCE was incorrectly eliminating dividend loads
Deterministic labels: Replace three static uint32_t counters with per-function
nextLocalLabelId(), reset to 0 per function for output determinism
Parallel move resolution: Replace entry parameter MOV loop with PX_COPY pseudo-instruction
for topological sort and cycle-breaking (fixes crash in multi-param entity init calls)
GNU-stack marking: Add .note.GNU-stack section to ELF output for non-executable stack
PE/COFF directives: .rdata section and ELF .type @function in AsmEmitter
PIE support: -pie flag for Linux linker

AArch64 Codegen (5 fixes)

Dominator intersect guard: Add runtime guard in Dominators.cpp intersect() for release builds
AsmEmitter refactor: Extract resolveBaseOffset() helper from four duplicated base+offset
load/store functions
Loop body BFS over-inclusion: Fix natural loop body computation crawling backwards past
the header for BASIC two-header for-loop patterns, causing compilation crashes (SIGBUS)
SLF reachability: Add predecessor reachability verification for cross-block store-load
forwarding to prevent incorrect forwarding when the layout predecessor diverges
Fast-path param stores: Emit param-to-alloca stores for >8-argument functions in the call
fast path, fixing uninitialized stack reads in lowerCallWithArgs

Runtime — Resource Lifecycle (10 fixes)

GC epoch-counter overflow: uint8 → uint32 (rt_gc.c)
String intern table dangling pointer on GC collect (rt_string_intern.c)
TLS session cache stale pointer after context free (rt_tls.c)
Parallel worker thread-local cleanup on join (rt_parallel.c)
PkgDeflate double-free on realloc failure (PkgDeflate.cpp)
ThreadsRuntime detached-thread resource leak (ThreadsRuntime.cpp)
File watcher handle leak on rewatch (rt_watcher.c)
Audio waveOut handle leak on close (vaud_platform_win32.c)
Closure env pointer offset extracted to named constants with static_assert
GC shutdown flag guard for Windows re-init safety

Runtime — Capacity Overflow Guards (16 files)

Integer overflow guards before capacity doubling in seq, deque, map, set, bag, bimap, countmap,
defaultmap, frozenmap, frozenset, intmap, multimap, sortedset, sparsearray, treemap, and weakmap.
Prevents undefined behavior when capacity approaches INT64_MAX/2 or SIZE_MAX/2.

Runtime — String Operations (12 sites)

Replace strlen() with rt_string_len_bytes()/rt_str_len() in 5 case-conversion functions,
2 LIKE functions, box hash, bloomfilter, bimap/bag helpers, and playlist operations.

Runtime — File Operations (8 fixes)

32-bit ftell/fseek overflow on Windows → 64-bit equivalents (linereader, PNG loader)
Delete corrupt PNG file on partial write failure
Check fclose() return in HTTP download, remove partial file on failure
Validate stream state after Serializer::write
Check write result in ArWriter::finishToFile

Runtime — Allocation Failure Handling

Replace silent data-dropping on allocation failure with rt_trap in rt_list_push, rt_map_new,
rt_map_set, rt_set_add. Replace assert-only bounds checks in rt_arr_str and rt_arr_obj
get/put with rt_trap + rt_arr_oob_panic.

Runtime — Type System (5 fixes)

Zia lowerAs() missing numeric conversion instructions
Assignment coercion for Number↔Integer fields and vars
Checked fptosi (CastFpToSiRteChk) with NaN/overflow guards
Separate CastFpToSiRteChk from Fptosi in lowering pipeline

Network & TLS Security (8 findings)

Native ECDSA P-256 verification for Linux TLS CertificateVerify (no OpenSSL dependency)
WebSocket fragmentation reassembly capped at 64MB with RFC 6455 close code 1009
TLS transcript buffer increased from 8KB to 32KB for large cert chains
MSVC-compatible 128-bit arithmetic for ECDSA P-256 (_addcarry_u64, _subborrow_u64,
_umul128 replacing __uint128_t)
TOML parser nesting depth limit (kMaxTomlDepth=128)
BASIC parser peek() distance limit (kMaxPeekDistance=1000)
Volatile memset for crypto key material wiping (HKDF, TLS)
Replace atoi() with strtol() + range validation in WebSocket port parsing

Network Audit & New Classes

Comprehensive file-by-file security and correctness review of all 11 C source files (14,427 lines)
in the network runtime, plus 10 new networking classes.

Security Fixes

AES-128-GCM cipher suite implementation (~300 LOC) for TLS dual cipher support
ChaCha20 counter overflow protection and Poly1305 key zeroing
TLS buffered data check for WebSocket and HTTP keep-alive
Windows socket type fix in TLS layer
Thread-safe CA certificate DER cache with heap-allocated PEM base64
HTTP HEAD response Content-Length fix, 303 redirect method rewrite
Memory leak fixes in URL parsing (key_str unref, parse validation)
recv_line length cap to prevent unbounded reads
ViperDOS ifaddrs compatibility fix, INT_MAX socket send clamp

New Network Classes (10)

HttpRouter — path pattern matching with parameter extraction
HttpServer — multi-client event-loop HTTP server
ConnectionPool — connection reuse with idle timeout and health checks
MultipartParser — multipart/form-data streaming parser
NetUtils — DNS resolution, interface enumeration, port checking
WebSocketServer — multi-client WebSocket server with broadcast
SSEClient — Server-Sent Events client with auto-reconnect
HttpClient — high-level HTTP client with cookie jar and redirects
SmtpClient — SMTP email sending with AUTH and TLS
AsyncSocket — non-blocking socket with completion callbacks

Crypto Additions

HMAC-SHA256 implementation for message authentication
HKDF (HMAC-based Key Derivation Function) for key expansion

3D Graphics Hardening

Post-audit fixes across the 3D graphics subsystem:

Canvas3D depth buffer bounds validation and initialization guards
Mesh3D vertex/index bounds checking on construction
Scene3D node cleanup and dangling reference prevention
Software rasterizer triangle clipping and edge-case guards
Pixels module additional bounds checks for direct pixel operations

Concurrency Hardening (TSan-verified)

Pool allocator: block->next pointer uses atomic load/store to prevent ARM64 memory ordering
corruption in lock-free freelist
SipHash: Fix non-atomic rt_siphash_seeded_ fast-path check causing stale seed reads on ARM64
weak memory model
GC: Fix non-atomic g_shutdown_registered causing potential double atexit registration
GC: Remove TOCTOU race by eliminating unnecessary unlock/relock gap in snapshot
Init races: PTHREAD_MUTEX_INITIALIZER / InitOnceExecuteOnce for all global init paths
ARM64 barriers: __dmb(_ARM64_BARRIER_ISH) in rt_platform.h + rt_pool.c

Zia Compiler Fixes

Static Property Resolution

Color.RED, Color.WHITE, etc. now work — the sema's module field handler now tries the
get_ prefix convention when resolving static properties through alias bindings. Previously,
Color.RED errored with "Module has no exported symbol 'RED'" because the getter was
registered as Viper.Graphics.Color.get_RED but the lookup tried
Viper.Graphics.Color.RED. This fix applies to ALL static properties on ALL runtime classes,
not just Color.

P0 Bugs

BUG-EH-001: Exception handler param types corrected (Ptr/I64 → Error/ResumeTok)
BUG-OPT-001: Optional<String> mapping corrected (Str → Ptr for nullable boxing)

P1 Bugs

BUG-MATCH-002: String match return type (I64 → I1)
BUG-MATCH-003: Boolean match with Zext1 before ICmpEq
BUG-MATCH-001: Negative literal patterns in match arms

P2-P3 Bugs

BUG-VAL-001: Value type String field init/copy (raw ptr store + retain)
BUG-OPT-002: Nested coalescing inner type derivation
BUG-IL-001: Save/restore IRBuilder temp counter around lambda lowering
BUG-IL-002: Type annotations for Dynamic result types in IL serializer; add call.indirect
parser/serializer support

Entity & Inheritance Fixes

Init overload resolution: Entity init() methods now correctly match parameter count
and types against the call site. Previously, entities with inherited init from a parent
would fail with "no init overload matching the provided arguments"
Override keyword: override expose func on entity methods now works for method
dispatch. Child entities can override parent methods with the override keyword
Entity method dispatch: Improved codegen routing for entity method calls through
the inheritance chain

Destructor & Property Fixes

Deinit binding propagation: Destructor (deinit) blocks can now access entity fields
through self bindings — previously, field accesses inside deinit hit lowering errors
because the binding context wasn't propagated to the destructor scope
Destructor dispatch: Correct lowering of __dtor_TypeName IL function calls through
entity inheritance chains
Property access improvements: Sema now correctly resolves property getter/setter
declarations and validates return types against the backing field type

Async Improvements

ThreadsRuntime async execution: VM ThreadsRuntime improved for async function handling,
supporting Future.Get continuation semantics for await expressions
Async test coverage: New compiler and runtime tests validating async/await lowering
through the full pipeline (parser → sema → IL → VM execution)

Sema Fixes

Guard-clause narrowing interaction: assignment type checking uses original declared type
Clear narrowing on reassignment to prevent stale type info
Force-unwrap allows reference/nullable types after narrowing
Optional<String> maps to IL Str type (not Ptr) matching runtime externs
Call instructions use extern-declared return type for IL verification
Match exhaustiveness checking (W019)
Escape analysis in BasicAA (non-escaping allocas vs Param → NoAlias)
Warning suppression improvements for entity method self-parameter warnings
Import deduplication in ImportResolver to prevent redundant module loads

Sidescroller Demo — "Nova Run" (Full Game)

The sidescroller demo evolved from a single-level tech demo into a complete 5-level platformer
("Nova Run") across 8 phases of development:

Content

5 themed levels: Training Grounds, Crystal Caverns, Volcanic Depths, Sky Fortress, Ancient Ruins
5 parallax backgrounds with round stars, atmospheric blur, and volumetric clouds
7 new tile types across 3 level themes with 3D bevels, crystal facets, and lava veins
Gradient title screen with scrolling elements and pulsing animations
Data-driven boss health bar and all 5 level names displayed in HUD

Sprite Art Overhaul

All entities redrawn using DrawTriangle, DrawEllipse, DrawBezier, DrawThickLine, Blur,
and Tint — replacing the original rectangles-only rendering. Includes 4-frame player run cycle
(was 2), 4-frame slime animation (was 2), and boss attack wind-up frame.

Physics & Systems

Frame-rate-independent physics via DeltaTime scaling across all subsystems
Gamepad support via Action.BindPadButton with integer button constants
Persistent high scores via CSV file I/O
12 procedurally generated WAV sound effects with SoundManager entity integration
ParticleEmitter-based effects replacing manual particle arrays
Projectile particle trails for player and enemy bullets

Visual Effects

Landing dust, wall-slide sparks, jetpack flame, ambient lava glow, crystal shimmer, speed trail,
and level intro splash screens.

Bug Fixes

Fix lock-free pool allocator race: reserve first slab block before sharing remainder with freelist
Fix TILE_BRIDGE missing from isSolid() — players fell through bridges into spike pits
Fix PS_HURT state stuck permanently — allow state transitions once iframes expire
Fix turret/boss shared etimer corruption: hurt handler and AI timer cancelled each other out,
leaving enemies stuck in permanent hurt state. Added hurt-state guards to turret and boss AI
Clear nearby enemy bullets on enemy death to prevent ghost collision damage at dead turret
positions (4-tile radius despawn)

Dungeon of Viper — 3D FPS Demo

A first-person dungeon crawler built on the Graphics3D engine, demonstrating 3D game development
in Zia:

First-person camera with mouselook and WASD movement
Procedural dungeon generation with rooms and corridors
3D rendering using the software rasterizer backend
Enemy spawning and basic combat mechanics
HUD with health, ammo, and minimap

Located at examples/games/dungeon/. Built with viper build and the native ARM64 codegen.

Codebase Reorganization

Directory Consolidation

All demos and examples consolidated under a unified examples/ root:

examples/
├── apps/       (viperide, paint, sqldb, webserver, varc, telnet)
├── games/      (chess, pacman, centipede, sidescroller, frogger, vtris, ...)
├── embedding/  (C++ VM integration examples)
├── apiaudit/   (runtime API verification)
├── basic/      (BASIC language examples)
├── il/         (IL benchmark and test programs)
└── sqldb-basic/ (SQL demo in BASIC)

~80 trivial/redundant/dead demo files removed. 5 entire directories deleted (gfx_centipede,
gui_test, particles, classes, vedit). 7 broken/redundant scripts removed.

Documentation Consolidation

Eliminated devdocs/ directory: 28 files merged into docs/ tree
25 stale devdocs files deleted (outdated plans, superseded specs)
117 broken relative links fixed across docs/
docs/README.md rebuilt as clean navigation hub
286 obsolete test sources removed from docs/bugs/bug_testing/
YAML frontmatter added to 95 documentation files
548 bare code blocks tagged with language identifiers
Terminology standardized: "standard library" → "ViperLib", "interpreter" → "VM"

Frontend Decomposition

Systematic 10-item improvement across BASIC, Zia, and shared frontend infrastructure:

Shared Infrastructure (fe_common/)

Extract string escape processing to EscapeSequences.hpp (shared by both frontends)
Extract diagnostic formatter to DiagnosticFormatter.hpp
Replace O(n) linear searches with hash tables in BASIC parser/builtins

Zia File Splits

Parser_Expr.cpp (1,804 LOC → 3 files)
Lowerer_Decl.cpp (1,690 LOC → 3 files)
Lowerer_Expr_Complex.cpp (1,386 LOC → 3 files)
Extract entity layout helpers (computeEntityFieldLayout, buildEntityVtable,
inheritEntityMembers) from monolithic registerEntityLayout

BASIC Improvements

Consolidate member array field handling (4 bugs) into MemberArrayResolver
Migrate BASIC Lexer to LexerBase CRTP (shared cursor management with Zia)

Header Decomposition

Extract Zia type layout structs to LowererTypes.hpp (-195 LOC from header)
Extract Zia Sema support types to sema/SemaTypes.hpp (-159 LOC)
Extract BASIC require*() methods to lowerer/LowererRuntimeRequirements.hpp

Type Coercion Unification

Unified numeric coercion logic between BASIC and Zia frontends

Large File Splits

Readability refactoring of the largest source files:

Original	Split Into	Purpose
`BytecodeVM.cpp`	+ `BytecodeVM_threaded.cpp`	Threaded interpreter extracted
`rt_graphics.c`	+ `rt_canvas.c` + `rt_drawing.c` + `rt_drawing_advanced.c` + `rt_graphics_stubs.c`	Graphics rendering split (2,750 LOC) + stubs
`rt_network_http.c`	+ `rt_http_url.c`	URL parsing extracted
`rt_tls.c`	+ `rt_tls_verify.c` + `rt_tls_internal.h`	Cert verification extracted
`vg_ide_widgets.h`	Split into 6 focused sub-headers	Umbrella include preserved
`Peephole.cpp` (AArch64)	6 sub-passes in `peephole/` directory	AArch64 peephole decomposition (2,750 LOC)
`Peephole.cpp` (x86-64)	4 sub-passes in `peephole/` directory	x86-64 peephole decomposition (1,470 LOC)
`RegAllocLinear.cpp`	8 files in `ra/` directory	AArch64 register allocator decomposition (1,478 LOC)
`Lowerer.hpp`	+ `LowererTypes.hpp` + `LowererSymbolTable.hpp` + `LowererTypeLayout.hpp`	Zia lowerer decomposition foundation

Cross-Platform Improvements

Network tests (RTNetworkHardenTests, RTNetworkTimeoutTests) ported to Windows via
sock_t/SOCK_CLOSE/SOCK_INVALID abstractions + WinSock2
Windows build script parity improvements

Zia Review Cleanup

Removed zia-review/ directory (review complete). All findings resolved and tracked in main
issue tracker.

Testing

New Test Coverage

Suite	Tests Added	Description
Zia parser errors	25	Parser negative/error-recovery tests
Zia lexer	62	Lexer edge-case unit tests
REPL	86	51 Zia + 35 BASIC REPL tests
x86-64 determinism	357	Backend output determinism stress (8 scenarios, 407 compilations)
rt_map	24	Comprehensive map tests
rt_pool	11	Pool allocator tests
VM equivalence	5	VM vs BytecodeVM output equivalence
Zia frontend	75	35 parser + 24 sema + 16 lowerer unit tests
Zia/BASIC enums	24	16 Zia + 8 BASIC enum tests
Native assembler	13	Binary encoder + object file writer tests
String dedup	6	Cross-module string deduplication tests
Symbol resolver	13	Weak/strong symbol resolution + archive demand-pull
Relocation edge cases	8	Out-of-range branch, overflow, and boundary tests
Dataflow liveness	9	Shared backward dataflow solver (31 assertions)
Encoding validation	1	Opcode coverage validation for encoding tables
x86-64 peephole	1	Peephole sub-pass integration test
DWARF debug line	11	Line table encoding, file/directory entries, sequences
DWARF debug sections	9	Non-alloc section handling across ELF/Mach-O/PE
ICF	1	Identical Code Folding correctness
Branch trampolines	1	Out-of-range relocation veneer generation
ELF exe writer	10	ELF executable output validation
Linker integration	7	End-to-end linker pipeline (multi-object, archives)
Fuzz harnesses	2	libFuzzer harnesses for Zia lexer and parser
DCE param compaction	1	Entry-block ABI param preservation test
Alias precision	1	LICM alias analysis precision test
Inline round-trip	1	Continuation block def-before-use serialization test
Canonical pipeline	3	O0/O1/O2 pipeline configuration validation
Crypto (new)	2	HMAC-SHA256, HKDF implementation tests
Pixels (new)	3	Additional bounds-checking pixel operation tests
Canvas3D (new)	2	Depth buffer and 3D canvas validation tests
Scene3D (new)	2	Scene graph cleanup and node management tests
Network runtime	1	Network operation integration tests
AnimStateMachine	7	State transitions, frame advance, one-shot, progress, flags
TextureAtlas	3	Grid slicing, named regions, SpriteBatch integration
Zia async	3	Async function parsing, sema validation, lowering
Zia destructors	3	Deinit blocks, binding propagation, field access
Zia enums (runtime)	2	Enum variant values, match exhaustiveness at runtime
Zia properties	1	Static property resolution through module aliases
Zia string methods	2	Instance method dispatch (Trim, Replace, Split)
Zia guard narrowing	1	Optional primitive narrowing after guard clause
Zia runtime programs	6	End-to-end runtime tests (enums, async, properties, deinit, etc.)
AArch64 Linux ABI	1	Linux calling convention validation
Pipeline equivalence	1	x86-64 pipeline output consistency

Determinism Stress Test

8 scenarios with 407 total compilations verify byte-identical assembly output:

Repeated compilation (N=100): same module compiled 100 times
RegAlloc pressure (N=50): 16 live vregs forcing spills
RoData pool (N=50): string/f64 literals with dedup
Multi-function ordering (N=50): 10 functions, insertion order
Complex CFG (N=50): switch + nested if/else + while loop
Separate construction: pointer-address independence
ISel patterns (N=50): strength reduction hash map stability
Static counter awareness: label normalization for known counters

Runtime Consistency Audit

Systematic audit across all runtime C headers, runtime.def registrations, and viperlib documentation
to enforce naming, behavioral, and type-safety consistency.

C Function Naming (Phase 1)

Renamed 40+ C functions to follow rt_<type>_<verb> naming convention. Affected collections: List,
Set, Map, Stack, Queue, Deque, Ring, Heap, Seq, Bag, Bytes. Key renames include Contains→Has,
Count→Length, Size→Length, IsEmpty property additions, and TryPop/TryPeek safe-access
variants for Stack, Queue, Deque, and Heap.

runtime.def Registration (Phase 2)

Aligned all IL-level method names and signatures with their C implementations. Added missing
RT_METHOD/RT_PROP/RT_ALIAS entries for newly renamed functions and ensured every RT_FUNC
has corresponding class registrations.

Collection Behavioral Consistency (Phase 3)

Added missing operations to bring all collections to feature parity where semantically appropriate:
Clone() for Stack, Queue, Set, Map; First()/Last()/Reverse() for Ring; TryPopFront()/
TryPopBack() for Deque; Items() alias for Heap's ToSeq().

Enum Adoption (Phase 4)

Converted 12 #define constant groups to typedef enum { ... } rt_xxx_t; enums for compile-time
type safety. Affected: screen effect types, path-follow modes, easing types, string builder status,
input grow results, JSON token types, and XML node types.

Enum Naming Unification (Phase 5)

Normalized 7 existing enum types from mixed naming styles (Style A tagged enums, PascalCase names)
to a consistent Style B convention: anonymous typedef enum { ... } rt_xxx_t; with _t suffix.

Boolean Return Type Consistency (Phase 6)

Fixed 15 runtime functions that returned bool or int for boolean results to consistently return
int8_t, matching the IL i1 type. Affected: rt_string_is_handle, rt_output_is_batch_mode,
rt_is_main_thread, rt_type_is_a, rt_type_implements, rt_box_equal, sprite overlap/contains
functions, and GUI shortcut checks.

Documentation Alignment (Phase 7)

Updated viperlib collection documentation to reflect all API additions from Phases 1-3. Added
missing methods to sequential, maps-sets, and specialized collection docs. Updated runtime.def
table of contents to cover all 80+ sections.

Codegen Bug Fixes

Two-level namespace PAC crash: Native linker produced Mach-O binaries with flat namespace
(missing MH_TWOLEVEL), causing CoreAnimation PAC pointer authentication traps on macOS ARM64
~1 second after window creation. Fixed with proper two-level namespace support and per-symbol
dylib ordinal assignment
EH subsystem cleanup: Auto-pop exception handler at dispatch, TrapKind enum alignment across
VM and codegen layers for consistent exception handling semantics
AArch64 MOVN: Binary encoder now emits MOVN for simple negative immediates (e.g., -1 through
-65536) instead of a multi-instruction MOVZ/MOVK sequence, reducing code size
String dedup safety: isCStringSection flag prevents string deduplication from corrupting
binary data sections (rodata containing non-string data)
Native linker launch fixes: Correct dynamic symbol recognition for Zia/graphics demo
executables, preventing false undefined-symbol errors at link time

Runtime Bug Fixes

TextCenteredScaled: Fix swapped scale/color parameters in rt_canvas_text_centered_scaled
that caused enormous near-black rectangles covering the screen during level intro overlays
Comprehensive C Source Audit: 230+ bugs fixed across all runtime C source files in four
batches. Covers bounds checking, null guards, integer overflow, format string safety,
memory leak prevention, and error handling across graphics, network, collections, and core
subsystems
Graphics Audit: Canvas coordinate overflow guards, pixel bounds validation, bitmap font
character range checks, GUI widget input handling fixes, navmesh boundary validation,
FBX loader robustness improvements, scene graph cleanup
Input System: Keychord and action unboxing fixes, color hex alpha parsing correction
Drawing: Circle fill algorithm fix in rt_drawing.c, canvas coordinate guard in rt_canvas.c

Graphics

Present-before-events: Reorder vgfx_update to present the frame before polling events,
fixing visual glitches on rapid input during scene transitions
macOS resize alpha: Set opaque alpha (0xFF) on framebuffer clear during window resize,
preventing transparent flicker artifacts on macOS
Linux X11: Fix 32-bit TrueColor visual via XMatchVisualInfo; add RGBA→BGRA swizzle in
presentation buffer for correct color rendering
Linux linking: Add -lX11 for graphics demos
macOS: Guard frameworks behind #if defined(__APPLE__) in AArch64 backend

GUI Improvements

ListBox: Multi-select mode, search/filter with keyboard, scroll-to-selection
TextInput: Undo/redo stack, text selection with shift+arrows, clipboard integration
Layout: Improved dock layout edge cases, floating panel cleanup
Event handling: Refined widget focus and keyboard event dispatch

IL Pass Infrastructure

Pass registry: Strengthened pass lookup with better error messages for missing passes
GVN: Added safety guards for edge cases in global value numbering
Pipeline executor: Improved error reporting and pass metrics collection
Analysis manager: Extended with additional analysis invalidation hooks

Project Statistics

Metric	v0.2.2	v0.2.3	Change
Codebase (SLOC)	~310,000	~348,000	+38K
Source Files	2,288	2,671	+383
Test Count	1,261	1,351	+90
Commits	—	100	—
Files Changed	—	3,557	—
Lines Added	—	~279K	—
Lines Removed	—	~323K	—

Lines removed exceed lines added because ~1,100 stale files were deleted (obsolete test
fixtures, dead demos, devdocs, zia-review). Net production SLOC grew by ~38K across 3D
graphics, game engine, native toolchain, optimizer, and new runtime classes.

Breaking Changes

Directory restructure: demos/ consolidated into examples/. Update any hardcoded paths.
devdocs/ removed: All developer documentation now lives under docs/.
Runtime API renames: 40+ C functions renamed to rt_<type>_<verb> convention. Key changes:
Contains→Has, Count→Length, Size→Length, plus IsEmpty property additions.
runtime.def registrations updated accordingly.
Collection .Len → .Length: User-facing .Len property renamed to .Length across List, Map,
and Set. .Len retained as alias for backward compatibility.
Boolean return types: 15 runtime functions changed from bool/int to int8_t (matching
IL i1). Affects C FFI callers using these functions directly.

Architecture

┌──────────────┐  ┌──────────────┐
│ BASIC Source │  │  Zia Source  │
│    (.bas)    │  │    (.zia)    │
└──────┬───────┘  └──────┬───────┘
       │                 │
       ▼                 ▼
┌─────────────────────────────────────────────────────┐
│                     Viper IL                        │
│      SimplifyCFG → SCCP → Reassociate (NEW)         │
│       → EarlyCSE → Mem2Reg → DSE (MemorySSA)        │
│       → CheckOpt → EH-Opt (NEW) → LoopRotate (NEW)  │
│       → Inliner                                     │
│                                                     │
│      Alloca Escape Verification (NEW)               │
└─────────────────────┬───────────────────────────────┘
                      │
      ┌───────────────┼───────────────┐
      ▼               ▼               ▼
┌──────────┐    ┌──────────────┐ ┌───────────────┐
│  IL VM   │    │   x86-64     │ │    AArch64    │
│ Bytecode │    │ 4 Peephole   │ │  PassMgr (NEW)│
│    VM    │    │ CFG Liveness │ │  Coalescer    │ (NEW)
│  REPL    │    │   (NEW)      │ │  Scheduler    │ (NEW)
│  (NEW)   │    └──────┬───────┘ │  Loop Hoist   │ (NEW)
└──────────┘           │         │  6 Peephole   │ (NEW)
                       │         └──────┬────────┘
                       └────────┬───────┘
                                ▼
                  ┌───────────────────────────┐
                  │  Shared Infrastructure    │
                  │  DataflowLiveness (NEW)   │
                  │  PeepholeDCE/CopyProp     │
                  │  ParallelCopyResolver     │
                  └────────────┬──────────────┘
                               ▼
                  ┌───────────────────────────┐
                  │  Native Assembler (NEW)   │
                  │  MIR → Binary Encoder     │
                  │  → Object File Writer     │
                  │  (ELF / Mach-O / PE)      │
                  └────────────┬──────────────┘
                               ▼
                  ┌───────────────────────────┐
                  │  Native Linker (NEW)      │
                  │  Symbol Resolution        │
                  │  Section Merging + ICF    │ (NEW)
                  │  Dead Strip + String Dedup│
                  │  DWARF Debug Info         │ (NEW)
                  │  Branch Trampolines       │ (NEW)
                  │  Two-Level Namespace      │ (NEW)
                  │  → Executable Writer      │
                  └───────────────────────────┘

Feature Comparison

Feature	v0.2.2	v0.2.3
3D Graphics Engine	No	28-class engine: Metal/D3D11/OpenGL/software
Native Assembler/Linker	External as/ld/link	In-process, zero deps, DWARF v5
Interactive REPL	No	Full REPL for Zia and BASIC
Enum Types	No	Zia + BASIC, match exhaustiveness
Language Server	No	Dual MCP/LSP (zia-server)
Game Engine Framework	No	GameBase/IScene + 7 runtime APIs
Runtime Classes	226	272 (+46)
IL Optimizer Passes	35	38 (+EH-Opt, LoopRotate, Reassoc)
Test Count	1,261	1,351 (+90 net)
Full O2 Pipeline	O1-level only	All 10 missing passes restored
Benchmark Results	—	24-87% improvement (Apple M4 Max)
AArch64 Peephole	Monolithic (2750 LOC)	6 sub-passes + shared templates
x86-64 Peephole	Monolithic (1470 LOC)	4 sub-passes in peephole/
x86-64 Liveness	Unconditional spill	CFG-aware backward dataflow
AArch64 Scheduler	No	Post-RA list scheduler + coalescer
SipHash	FNV-1a	SipHash-2-4 with OS CSPRNG seed
ECDSA P-256	OpenSSL-dependent	Pure C, MSVC-compatible
Sidescroller Demo	1 level, rectangles	5 levels, sprite art, full game
O1 Native Codegen	Broken (paint, pacman crashes)	9/11 demos correct at O1
Network Classes	5	15 (+10 new classes)
Crypto	ChaCha20-Poly1305, ECDSA	+ AES-128-GCM, HMAC-SHA256, HKDF
3D Demo	No	Dungeon of Viper — 3D FPS
Codebase Organization	demos/ + devdocs/	Unified examples/ + docs/
Language Audit	No	13 findings validated, 6 fixed, 7 filed

v0.2.x Roadmap

Remaining v0.2.x focus areas:

Zia debugger integration with breakpoints and watch expressions
Native code generation coverage expansion
RISC-V backend exploration
GUI library maturation (accessibility, additional widget types)
Runtime API stability and performance improvements
Self-hosting compiler groundwork

Viper Compiler Platform v0.2.3 (Pre-Alpha) — DRAFT
Target: March 2026
Note: This is an early development release. Future milestones will define supported releases when appropriate.

v0.2.3-dev