docs: add project README

Add README.md documenting WASURO's architecture, implemented opcodes,
parsed sections, build instructions, testing, and constraints.

Covers:
- Project overview (WASM VM for Asuro OS, Standard Pascal, bare-metal)
- Source tree layout and key components (VM, parser, stack, heap, emu layer)
- Full table of implemented opcodes (control, variables, constants,
  i32/i64 arithmetic/bitwise/comparison, f32/f64 comparison,
  memory loads/stores, memory.size/grow)
- Parsed WASM binary sections
- Build and test instructions (build.bat / build.bat test)
- Kernel compatibility constraints (no RTL, no classes)

.gitignore

@@ -1,2 +1,3 @@
 bin
 lib
+AGENTS.md

README.md

@@ -0,0 +1,89 @@
+# WASURO
+
+A WebAssembly virtual machine for the [Asuro](https://github.com/Nosfex/Asuro) operating system, written in Standard Pascal.
+
+WASURO parses and executes WASM binaries directly in a bare-metal kernel environment — no runtime library, no classes, no heap manager beyond what the OS provides.
+
+## Architecture
+
+```
+src/
+├── emu/            # OS emulation layer (types, console, memory, LEB128)
+├── wasm/
+│   ├── parser/     # WASM binary parser
+│   │   └── sections/  # Section-specific parsers (type, function, export,
+│   │                   #   code, global, memory, start, data, etc.)
+│   ├── types/      # WASM type system, stack, and linear memory (heap)
+│   ├── vm/         # VM tick loop and opcode jump table
+│   └── test/       # Test suite
+│       ├── infra/      # Stack, heap, LEB128 tests
+│       ├── opcodes/    # Per-opcode test units
+│       └── parsers/    # Per-section parser tests
+└── project/        # Lazarus project files
+```
+
+### Key components
+
+- **VM** (`wasm.vm`) — Tick-based execution loop dispatching opcodes through a 256-entry jump table.
+- **Parser** (`wasm.parser`) — Validates the WASM magic/version header, then routes each binary section to its handler.
+- **Stack** (`wasm.types.stack`) — Operand and control stacks supporting i32, i64, f32, f64 push/pop.
+- **Heap** (`wasm.types.heap`) — Paged linear memory with read/write at 8/16/32/64-bit widths.
+- **Emulation layer** (`src/emu/`) — Provides the same `types`, `console`, `lmemorymanager`, and `leb128` interfaces that exist in the real Asuro kernel, allowing development and testing on a host OS.
+
+### Implemented opcodes
+
+| Category | Opcodes |
+|---|---|
+| Control | `nop`, `unreachable`, `drop`, `select`, `return` |
+| Variables | `local.get/set/tee`, `global.get/set` |
+| Constants | `i32.const`, `i64.const`, `f32.const`, `f64.const` |
+| i32 Arithmetic | `add`, `sub`, `mul`, `div_s/u`, `rem_s/u`, `clz`, `ctz`, `popcnt` |
+| i32 Bitwise | `and`, `or`, `xor`, `shl`, `shr_s/u`, `rotl`, `rotr` |
+| i32 Comparison | `eqz`, `eq`, `ne`, `lt_s/u`, `gt_s/u`, `le_s/u`, `ge_s/u` |
+| i64 Arithmetic | `add`, `sub`, `mul`, `div_s/u`, `rem_s/u`, `clz`, `ctz`, `popcnt` |
+| i64 Bitwise | `and`, `or`, `xor`, `shl`, `shr_s/u`, `rotl`, `rotr` |
+| i64 Comparison | `eqz`, `eq`, `ne`, `lt_s/u`, `gt_s/u`, `le_s/u`, `ge_s/u` |
+| f32/f64 Comparison | `eq`, `ne`, `lt`, `gt`, `le`, `ge` |
+| Memory Loads | `i32/i64/f32/f64.load`, sign/zero-extending variants (8/16/32-bit) |
+| Memory Stores | `i32/i64/f32/f64.store`, narrowing variants (8/16/32-bit) |
+| Memory Mgmt | `memory.size`, `memory.grow` |
+
+### Parsed sections
+
+Type, Function, Export, Code, Global, Memory, Start, Data, Import (stub), Table (stub), Element (stub), Custom (stub).
+
+## Constraints
+
+- **Standard Pascal only** — no runtime library, no classes.
+- **Kernel-compatible** — all arithmetic (including `shr_s`) uses manual implementations, no RTL intrinsics.
+- **Emulation layer** — `src/emu/` mirrors the real Asuro kernel API; only these interfaces are available.
+
+## Requirements
+
+- [Free Pascal Compiler](https://www.freepascal.org/) 3.2.2+ (x86_64-win64)
+- Windows (build script is a `.bat` file)
+
+## Building
+
+```bat
+# Normal build
+build.bat
+
+# Build with test suite
+build.bat test
+```
+
+Output: `bin\WASURO.exe`
+
+## Testing
+
+```bat
+build.bat test
+bin\WASURO.exe
+```
+
+Runs 374 tests across 108 test units. Exit code equals the number of failed tests (0 on success), making it CI/CD-friendly.
+
+## License
+
+See repository for license details.

build.bat

@@ -0,0 +1,39 @@
+@echo off
+setlocal
+
+set ROOT=%~dp0
+set SRC=%ROOT%src
+set BIN=%ROOT%bin
+set LIB=%ROOT%lib
+set FPC=C:\Lazarus\fpc\3.2.2\bin\x86_64-win64\fpc.exe
+
+set TESTFLAGS=
+if "%1"=="test" set TESTFLAGS=-dRUN_TESTS
+
+if not exist "%BIN%" mkdir "%BIN%"
+if not exist "%LIB%" mkdir "%LIB%"
+
+"%FPC%" ^
+  %TESTFLAGS% ^
+  -FE"%BIN%" ^
+  -FU"%LIB%" ^
+  -Fu"%SRC%\emu" ^
+  -Fu"%SRC%\wasm" ^
+  -Fu"%SRC%\wasm\parser" ^
+  -Fu"%SRC%\wasm\parser\sections" ^
+  -Fu"%SRC%\wasm\test" ^
+  -Fu"%SRC%\wasm\test\opcodes" ^
+  -Fu"%SRC%\wasm\test\parsers" ^
+  -Fu"%SRC%\wasm\test\infra" ^
+  -Fu"%SRC%\wasm\types" ^
+  -Fu"%SRC%\wasm\vm" ^
+  -gw3 ^
+  -o"%BIN%\WASURO.exe" ^
+  "%SRC%\project\WASURO.lpr"
+
+if %ERRORLEVEL% NEQ 0 (
+    echo Build failed with error code %ERRORLEVEL%
+    exit /b %ERRORLEVEL%
+)
+
+echo Build succeeded: %BIN%\WASURO.exe

src/wasm/parser/sections/wasm.parser.sections.dataSection.pas

@@ -4,16 +4,76 @@ interface
 
 uses
     types, lmemorymanager, console, leb128,
-    wasm.types;
+    wasm.types, wasm.types.heap;
 
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
 
 implementation
 
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
+var
+   pos, bend : puint8;
+   bytesRead : uint8;
+   segCount : uint32;
+   i, j : uint32;
+   memIdx : uint32;
+   offset : uint32;
+   dataSize : uint32;
+   opcode : uint8;
+   tmpU32 : uint32;
+
 begin
     writestring('[wasm.parser] Handle Section: Data - Size: ');
     writeintlnWND(section_length, 0);
+
+    pos := buffer;
+    bend := puint8(buffer + section_length);
+
+    { Read segment count }
+    bytesRead := read_leb128_to_uint32(pos, bend, @segCount);
+    Inc(pos, bytesRead);
+
+    for i := 0 to segCount - 1 do begin
+        { Read memory index }
+        bytesRead := read_leb128_to_uint32(pos, bend, @memIdx);
+        Inc(pos, bytesRead);
+
+        { Evaluate offset init expression (expect i32.const N, end) }
+        offset := 0;
+        opcode := pos^;
+        Inc(pos);
+        if opcode = $41 then begin { i32.const }
+            bytesRead := read_leb128_to_uint32(pos, bend, @tmpU32);
+            Inc(pos, bytesRead);
+            offset := tmpU32;
+        end else begin
+            writestring('[wasm.parser] Warning: unsupported data offset opcode: ');
+            writehexpair(opcode);
+            writestringln(' ');
+            while (pos < bend) and (pos^ <> $0B) do Inc(pos);
+        end;
+
+        { Consume end ($0B) }
+        if (pos < bend) and (pos^ = $0B) then
+            Inc(pos);
+
+        { Read data byte count }
+        bytesRead := read_leb128_to_uint32(pos, bend, @dataSize);
+        Inc(pos, bytesRead);
+
+        writestring('[wasm.parser]     Data Segment ');
+        writeintWND(i, 0);
+        writestring(' - Offset: ');
+        writeintWND(offset, 0);
+        writestring(' Size: ');
+        writeintlnWND(dataSize, 0);
+
+        { Copy bytes into linear memory }
+        for j := 0 to dataSize - 1 do begin
+            wasm.types.heap.write_uint8(offset + j, ctx^.ExecutionState.Memory, pos^);
+            Inc(pos);
+        end;
+    end;
 end;
 
 end.

src/wasm/parser/sections/wasm.parser.sections.globalSection.pas

@@ -10,10 +10,113 @@ procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContex
 
 implementation
 
+procedure walk(ctx : PWASMProcessContext);
+var
+   i : uint32;
+   entry : PWASMGlobalEntry;
+begin
+    for i := 0 to ctx^.ExecutionState.Globals^.GlobalCount - 1 do begin
+        entry := @ctx^.ExecutionState.Globals^.Globals[i];
+        writestring('[wasm.parser]     Global ');
+        writeintWND(i, 0);
+        writestring(' - Type: ');
+        writestring(GetWasmValueTypeString(entry^.ValueType));
+        if entry^.Mutable then
+           writestring(' (mut)')
+        else
+           writestring(' (const)');
+        writestring(' = ');
+        case entry^.ValueType of
+            vti32: writeintlnWND(entry^.Value.i32Value, 0);
+            vti64: writeintlnWND(entry^.Value.i64Value, 0);
+        else
+            writestringln('<value>');
+        end;
+    end;
+end;
+
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
+var
+   pos, bend : puint8;
+   bytesRead : uint8;
+   globalCount : uint32;
+   i : uint32;
+   entry : PWASMGlobalEntry;
+   valType : uint8;
+   mutFlag : uint8;
+   opcode : uint8;
+   tmpU32 : uint32;
+   tmpU64 : uint64;
+
 begin
     writestring('[wasm.parser] Handle Section: Global - Size: ');
     writeintlnWND(section_length, 0);
+
+    pos := buffer;
+    bend := puint8(buffer + section_length);
+
+    { Read global count }
+    bytesRead := read_leb128_to_uint32(pos, bend, @globalCount);
+    Inc(pos, bytesRead);
+
+    { Allocate globals on ExecutionState }
+    ctx^.ExecutionState.Globals := PWASMGlobals(kalloc(sizeof(TWASMGlobals)));
+    ctx^.ExecutionState.Globals^.GlobalCount := globalCount;
+    ctx^.ExecutionState.Globals^.Globals := PWASMGlobalEntry(kalloc(sizeof(TWASMGlobalEntry) * globalCount));
+
+    for i := 0 to globalCount - 1 do begin
+        entry := @ctx^.ExecutionState.Globals^.Globals[i];
+
+        { Read value type }
+        valType := pos^;
+        Inc(pos);
+        entry^.ValueType := TWasmValueType(valType);
+
+        { Read mutability }
+        mutFlag := pos^;
+        Inc(pos);
+        entry^.Mutable := (mutFlag = 1);
+
+        { Initialize value to zero }
+        entry^.Value.i64Value := 0;
+        entry^.Value.ValueType := entry^.ValueType;
+
+        { Evaluate constant init expression }
+        opcode := pos^;
+        Inc(pos);
+        case opcode of
+            $41: begin { i32.const }
+                bytesRead := read_leb128_to_uint32(pos, bend, @tmpU32);
+                Inc(pos, bytesRead);
+                entry^.Value.i32Value := int32(tmpU32);
+            end;
+            $42: begin { i64.const }
+                bytesRead := read_leb128_to_uint64(pos, bend, @tmpU64);
+                Inc(pos, bytesRead);
+                entry^.Value.i64Value := int64(tmpU64);
+            end;
+            $43: begin { f32.const }
+                entry^.Value.f32Value := pfloat(pos)^;
+                Inc(pos, 4);
+            end;
+            $44: begin { f64.const }
+                entry^.Value.f64Value := pdouble(pos)^;
+                Inc(pos, 8);
+            end;
+        else
+            writestring('[wasm.parser] Warning: unsupported global init opcode: ');
+            writehexpair(opcode);
+            writestringln(' ');
+            { Skip to end opcode }
+            while (pos < bend) and (pos^ <> $0B) do Inc(pos);
+        end;
+
+        { Consume the end ($0B) opcode }
+        if (pos < bend) and (pos^ = $0B) then
+            Inc(pos);
+    end;
+
+    walk(ctx);
 end;
 
 end.

src/wasm/parser/sections/wasm.parser.sections.memorySection.pas

@@ -4,16 +4,81 @@ interface
 
 uses
     types, lmemorymanager, console, leb128,
-    wasm.types;
+    wasm.types, wasm.types.heap;
 
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
 
 implementation
 
+procedure walk(ctx : PWASMProcessContext);
+var
+   i : uint32;
+   mem : PWASMMemoryLimits;
+begin
+    for i := 0 to ctx^.Sections.MemorySection^.MemoryCount - 1 do begin
+        mem := @ctx^.Sections.MemorySection^.Memories[i];
+        writestring('[wasm.parser]     Memory ');
+        writeintWND(i, 0);
+        writestring(' - Initial: ');
+        writeintWND(mem^.InitialPages, 0);
+        if mem^.HasMax then begin
+            writestring(' Max: ');
+            writeintWND(mem^.MaxPages, 0);
+        end;
+        writestringln(' ');
+    end;
+end;
+
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
+var
+   pos, bend : puint8;
+   bytesRead : uint8;
+   memCount : uint32;
+   i : uint32;
+   mem : PWASMMemoryLimits;
+   flags : uint32;
+
 begin
     writestring('[wasm.parser] Handle Section: Memory - Size: ');
     writeintlnWND(section_length, 0);
+
+    pos := buffer;
+    bend := puint8(buffer + section_length);
+
+    { Read memory count }
+    bytesRead := read_leb128_to_uint32(pos, bend, @memCount);
+    Inc(pos, bytesRead);
+
+    { Allocate memory section }
+    ctx^.Sections.MemorySection := PWASMMemorySection(kalloc(sizeof(TWASMMemorySection)));
+    ctx^.Sections.MemorySection^.MemoryCount := memCount;
+    ctx^.Sections.MemorySection^.Memories := PWASMMemoryLimits(kalloc(sizeof(TWASMMemoryLimits) * memCount));
+
+    for i := 0 to memCount - 1 do begin
+        mem := @ctx^.Sections.MemorySection^.Memories[i];
+
+        { Read limits flags: 0 = no max, 1 = has max }
+        bytesRead := read_leb128_to_uint32(pos, bend, @flags);
+        Inc(pos, bytesRead);
+        mem^.HasMax := (flags = 1);
+
+        { Read initial page count }
+        bytesRead := read_leb128_to_uint32(pos, bend, @mem^.InitialPages);
+        Inc(pos, bytesRead);
+
+        { Read max page count if present }
+        if mem^.HasMax then begin
+            bytesRead := read_leb128_to_uint32(pos, bend, @mem^.MaxPages);
+            Inc(pos, bytesRead);
+        end else
+            mem^.MaxPages := $FFFF; { no limit }
+
+        { Expand heap to match initial pages (heap starts with 1 page) }
+        while ctx^.ExecutionState.Memory^.PageCount < mem^.InitialPages do
+            wasm.types.heap.expand_heap(ctx^.ExecutionState.Memory);
+    end;
+
+    walk(ctx);
 end;
 
 end.

src/wasm/parser/sections/wasm.parser.sections.startSection.pas

@@ -11,9 +11,20 @@ procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContex
 implementation
 
 procedure handle(buffer: puint8; section_length: uint32; ctx: PWASMProcessContext);
+var
+   bytesRead : uint8;
+   funcIdx : uint32;
+
 begin
     writestring('[wasm.parser] Handle Section: Start - Size: ');
     writeintlnWND(section_length, 0);
+
+    { Read the start function index }
+    bytesRead := read_leb128_to_uint32(buffer, puint8(buffer + section_length), @funcIdx);
+    ctx^.Sections.StartIndex := int32(funcIdx);
+
+    writestring('[wasm.parser]     Start Function Index: ');
+    writeintlnWND(funcIdx, 0);
 end;
 
 end.

src/wasm/parser/wasm.parser.pas

@@ -39,6 +39,13 @@ begin
     ctx^.Sections.FunctionSection:= nil;
     ctx^.Sections.ExportSection:= nil;
     ctx^.Sections.CodeSection:= nil;
+    ctx^.Sections.MemorySection:= nil;
+    ctx^.Sections.StartIndex:= -1;
+
+    // Initialize globals (empty until global section is parsed)
+    ctx^.ExecutionState.Globals:= PWASMGlobals(kalloc(sizeof(TWASMGlobals)));
+    ctx^.ExecutionState.Globals^.GlobalCount:= 0;
+    ctx^.ExecutionState.Globals^.Globals:= nil;
 
     newContext:= ctx;
 end;

src/wasm/types/wasm.types.pas

@@ -275,11 +275,38 @@ type
     end;
     PWASMCodeSection = ^TWASMCodeSection;
 
+    TWASMGlobalEntry = record
+      ValueType : TWasmValueType;
+      Mutable   : boolean;
+      Value     : TWASMValueEntry;
+    end;
+    PWASMGlobalEntry = ^TWASMGlobalEntry;
+
+    TWASMGlobals = record
+      GlobalCount : uint32;
+      Globals     : PWASMGlobalEntry;
+    end;
+    PWASMGlobals = ^TWASMGlobals;
+
+    TWASMMemoryLimits = record
+      HasMax   : boolean;
+      InitialPages : uint32;
+      MaxPages     : uint32;
+    end;
+    PWASMMemoryLimits = ^TWASMMemoryLimits;
+
+    TWASMMemorySection = record
+      MemoryCount : uint32;
+      Memories    : PWASMMemoryLimits;
+    end;
+    PWASMMemorySection = ^TWASMMemorySection;
+
     TWASMState = record
       Code   : puint8;
       Limit  : uint32;
       Locals : PWASMLocals;
       Memory : PWasmHeap;
+      Globals : PWASMGlobals;
       Control_Stack : PWASMStack;
       Operand_Stack : PWASMStack;
       IP : uint32;
@@ -292,6 +319,8 @@ type
       FunctionSection : PWASMFunctionSection;
       ExportSection   : PWASMExportSection;
       CodeSection     : PWASMCodeSection;
+      MemorySection   : PWASMMemorySection;
+      StartIndex      : int32;  { -1 = no start function }
     end;
 
     TWASMProcessContext = record