Fix VM-style compiler gaps (get_ref dispatch, field assign, method desugaring, match-arm flow) and Option/extern call-site typing so idiomatic programs and all examples build. Add integration tests, bytecode_vm example, refresh showcase/todo/http/text_summary, and update docs.

Author: Cod-e-Codes

.cursor/skills/writing-ion-code/SKILL.md

@@ -150,7 +150,7 @@ Import with paths like `import "stdlib/io.ion" as io;`:
 
 No stdlib stdin/line input. For POSIX `read` on fd 0, see [examples/todo_demo/](../../../examples/todo_demo/).
 
-Built-ins: `Vec<T>`, `String`, `Box<T>`, `Option<T>`, `Result<T, E>` (define enums in-file or import). `Vec::get` / `Vec::pop` move elements out; use `Vec::get_ref(&v, i)` for read-only in-function peek (`Option<&T>`, local only). `String` literals assign to `String`; use `String::from("...")` when a owned copy is needed.
+Built-ins: `Vec<T>`, `String`, `Box<T>`, `Option<T>`, `Result<T, E>` (define enums in-file or import). `Vec::get` / `Vec::pop` move elements out; use `Vec::get_ref(&v, i)` for read-only in-function peek (`Option<&T>`, local only). Match on `&Enum` from `get_ref` dispatches variants directly (no `*` deref). Struct field paths support `=` and `+=` on owned and `&mut` receivers. Nested generics such as `Vec<Vec<int>>` parse as consecutive `>` closings. String literals and `&String` coerce to `&str` at call sites.
 
 ## Build and verify
 

.cursor/skills/writing-ion-code/references/verified-patterns.md

@@ -47,7 +47,24 @@ s.push_str("hi");
 let lit: String = "hello";
 ```
 
-`Vec::get` / `Vec::pop` return `Option<T>` and **move** the element out. For read-only scans use `Vec::get_ref(&v, i)` which returns `Option<&T>` (local temporary only; cannot return or store). In `match Option::Some(x)`, `x` is `&T`: copy types bind by value; structs with owned fields bind as a pointer so nested `Vec` fields are not dropped. `Vec::set(&mut v, index, value)` returns `int` (0 = ok).
+`Vec::get` / `Vec::pop` return `Option<T>` and **move** the element out. For read-only scans use `Vec::get_ref(&v, i)` which returns `Option<&T>` (local temporary only; cannot return or store). In `match Option::Some(x)`, `x` is `&T`: copy types bind by value; structs and enums with non-copy fields bind as a pointer. Inner `match x` on `&Enum` dispatches variants without deref. `Vec::set(&mut v, index, value)` returns `int` (0 = ok). Method syntax (`v.push(x)`, `v.get_ref(i)`) desugars to `Vec::` builtins with correct receiver borrows.
+
+## Struct field mutation
+
+```ion
+struct VM { ip: int; stack: Vec<int>; }
+
+fn step(vm: &mut VM) {
+    vm.stack.push(1);
+    vm.ip += 1;
+}
+```
+
+Field paths are valid assignment targets on owned structs and `&mut` parameters.
+
+## VM dispatch loop
+
+See [tests/test_vm_execute.ion](../../../../tests/test_vm_execute.ion): `match vm.code.get_ref(vm.ip)` then inner `match op` on `&Op`, field updates, and `break` inside `match` within `loop`.
 
 ## Box
 
@@ -68,10 +85,6 @@ let elem: int = arr[0];  // bounds checked unless unsafe
 ## Borrowing (same function only)
 
 ```ion
-fn bump(x: &mut int) {
-    *x = *x + 1;
-}
-
 fn read_len(v: &Vec<int>) -> int {
     return v.len();
 }

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2026-07
+
+- **VM-style idioms**: `match` on `&Enum` from `Vec::get_ref`; struct field assignment and `+=` on owned/`&mut` paths; method desugaring (`vec.push`, `vec.get_ref`) with correct borrows; nested generic types (`Vec<Vec<int>>`); match-arm control-flow unification (`break`/`return` with value arms); `&str` call-site coercion; enum literals in `Vec::push`/`set` without double-wrapped C; `&mut Struct` field access via `->` in codegen. Integration tests and examples `bytecode_vm`, updated `showcase`, `todo_demo`, `http_server`, `text_summary`. Fix extern call typing so `&T` arguments match `&T` parameters (no erroneous copy-type ref stripping). Fix `Option<T>` match codegen to use the scrutinee type instead of the first registered monomorph. Former negative match-arm rvalue tests now pass as positive runs.
+
 ## 2026-06
 
 - **Readiness hardening**: beta compatibility and runtime ABI documents, a lightweight security policy, CLI/`ion-build` multi-error type diagnostics, sanitizer CI smoke (6 tests), and full integration harness `-Wall -Wextra -Werror` on Linux CI. Cgen warning-hygiene improvements (binding usage tracking and `(void)` silences, borrow/defer silences, string literal `.data`/`uint8_t*` casts, string `for...in` length casts), `String` runtime data as `uint8_t*`, and `CFLAGS`/`LDFLAGS` support in the integration harness.

ION_SPEC.md

@@ -184,7 +184,7 @@ Ion uses the following operators:
 - Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=`
 - Logical: `&&`, `||`, `!`
 - Bitwise: `&` (AND), `|` (OR), `^` (XOR), `<<` (left shift), `>>` (right shift)
-- Assignment: `=`, `+=` (compound assignment desugars to `x = x + e` for supported `+` types)
+- Assignment: `=`, `+=` (compound assignment desugars to `x = x + e` for supported `+` types). Assignment targets may be locals, index expressions, or field paths on owned structs or `&mut Struct` receivers (for example `vm.ip += 1`).
 - Type casting: `as` keyword for explicit type conversions
 - Field access: `.`
 - Address-of / borrow: `&` (borrow shared) and `&mut` (borrow exclusive)
@@ -1021,7 +1021,7 @@ Note that:
 - `Vec<T>` is `Send` if `T: Send`.
 - `Vec::new()` and `Vec::with_capacity()` infer `T` from a `let` type annotation when present (e.g. `let v: Vec<i32> = Vec::new()`).
 - `Vec::get()` and `Vec::pop()` return `Option<T>` to handle out-of-bounds or empty cases. Both **move** the element out of the vector. To preserve vector length after a read-only scan, either use `Vec::get_ref()` (below) or copy fields and `Vec::set()` a rebuilt struct literal to put the value back (nested `Vec` fields still move on put-back).
-- `Vec::get_ref()` returns `Option<&T>`: a **local, stack-only borrow** of an in-place element. It does not move or hollow the slot. The result is only valid as a short-lived binding within the current function (for example in a `match` arm). Match arms bind the element as `&T`; codegen uses `T*` for types with owned fields and copies by value for copy types, so repeated scans over `Vec<struct-with-nested-Vec>` do not double-free nested fields. It cannot be returned, stored in structs or enums, sent on channels, or cross `spawn`. While an `&T` from `get_ref` is active, the root owner of the vector (the binding behind `&Vec<T>`) is shared-borrowed: `&mut Vec<T>` on that owner, `Vec::set`, `Vec::push`, and `Vec::pop` on the same vector are rejected until the borrow ends. Out-of-range or negative indices yield `Option::None`. Nested inspection (`order.lines` then `get_ref`) follows the same root-owner borrow rules as field paths (Section 5.3).
+- `Vec::get_ref()` returns `Option<&T>`: a **local, stack-only borrow** of an in-place element. It does not move or hollow the slot. The result is only valid as a short-lived binding within the current function (for example in a `match` arm). Match arms bind the element as `&T`; for enum elements, an inner `match` on that binding dispatches variants directly (no unary `*` deref). Copy fields in struct or enum variant patterns bind as `T`; non-copy fields bind as `&T`. Codegen uses `T*` for types with owned fields and copies by value for copy types, so repeated scans over `Vec<struct-with-nested-Vec>` do not double-free nested fields. It cannot be returned, stored in structs or enums, sent on channels, or cross `spawn`. While an `&T` from `get_ref` is active, the root owner of the vector (the binding behind `&Vec<T>`) is shared-borrowed: `&mut Vec<T>` on that owner, `Vec::set`, `Vec::push`, and `Vec::pop` on the same vector are rejected until the borrow ends. Out-of-range or negative indices yield `Option::None`. Nested inspection (`order.lines` then `get_ref`) follows the same root-owner borrow rules as field paths (Section 5.3). Field paths through `&Struct` that are already references (for example `order.lines` when `order: &Order`) are passed to `Vec` methods without an extra `&`.
 - `Vec::set()` requires a mutable reference and returns an error code (0 for success, non-zero for failure). After shared borrows from `get_ref` end, `Vec::set` on the same index is allowed.
 
 For cross-function or long-lived access, Ion still favors an **index/handle style**: helpers return indices or keys and callers re-index within their own function bodies.
@@ -1055,7 +1055,8 @@ Note that:
 - `String::push_byte()` appends a single byte to an existing `String`.
 - `==` and `!=` compare UTF-8 byte content (value equality), not pointer identity.
 
-`&str` is always a **borrowed view** into existing UTF-8 data; it cannot be returned or stored in long-lived structures in ways that would violate the no-escape rule. The standard library intentionally avoids APIs that would expose `&str` values across function boundaries in ways that require complex lifetime reasoning (e.g., `String::as_str` methods that return borrowed views).
+- `String::from` and stdlib APIs accepting `&str` also accept string literals and `&String` at call sites.
+- `&str` is always a **borrowed view** into existing UTF-8 data; it cannot be returned or stored in long-lived structures in ways that would violate the no-escape rule. The standard library intentionally avoids APIs that would expose `&str` values across function boundaries in ways that require complex lifetime reasoning (e.g., `String::as_str` methods that return borrowed views).
 
 #### 8.4 Channels
 

README.md

@@ -181,7 +181,8 @@ On Linux or macOS, use `./target/release/ion-build` and drop `.exe`. Windows cha
 | [spawn_channel/](examples/spawn_channel/) | `spawn` with cross-thread channels |
 | [channel_worker/](examples/channel_worker/) | Channel worker |
 | [worker_pool/](examples/worker_pool/) | Three workers with per-worker job/result channels |
-| [showcase/](examples/showcase/) | Mixed language features |
+| [showcase/](examples/showcase/) | Mixed language features (includes bytecode VM dispatch) |
+| [bytecode_vm/](examples/bytecode_vm/) | Stack VM: `get_ref` enum dispatch, field `+=`, method calls on `&mut` struct fields |
 | [access_log/](examples/access_log/) | Log parsing, spawn, channels, fmt/io |
 | [http_server/](examples/http_server/) | Sockets FFI, spawn per client, stdin `quit` to stop; see [http_server/README.md](examples/http_server/README.md) |
 | [text_summary/](examples/text_summary/) | `fs` read, string iteration, counts |

examples/bytecode_vm/bytecode_vm.ion

@@ -0,0 +1,62 @@
+// Stack bytecode VM: idiomatic Ion patterns for interpreter-style loops.
+//
+// - Vec<Op> with method calls on struct fields (vm.code.push, vm.code.get_ref)
+// - match on &Op from get_ref (no unary * deref)
+// - struct field assignment and += on &mut VM
+// - break inside match within loop
+
+enum Op { Push { val: int }; Add; Halt; }
+
+struct VM {
+    ip: int;
+    stack: Vec<int>;
+    code: Vec<Op>;
+}
+
+fn execute(vm: &mut VM) -> int {
+    loop {
+        match vm.code.get_ref(vm.ip) {
+            Option::Some(op) => {
+                match op {
+                    Op::Push { val: v } => {
+                        vm.stack.push(v);
+                        vm.ip += 1;
+                    }
+                    Op::Add => {
+                        let b = match vm.stack.pop() {
+                            Option::Some(v) => { v; }
+                            Option::None => { return 0; }
+                        };
+                        let a = match vm.stack.pop() {
+                            Option::Some(v) => { v; }
+                            Option::None => { return 0; }
+                        };
+                        vm.stack.push(a + b);
+                        vm.ip += 1;
+                    }
+                    Op::Halt => { break; }
+                };
+            }
+            Option::None => { break; }
+        };
+    }
+    return 0;
+}
+
+fn main() -> int {
+    let mut vm: VM = VM {
+        ip: 0,
+        stack: Vec::new(),
+        code: Vec::new(),
+    };
+    // Program: push 10, push 32, add -> 42, halt
+    vm.code.push(Op::Push { val: 10 });
+    vm.code.push(Op::Push { val: 32 });
+    vm.code.push(Op::Add);
+    vm.code.push(Op::Halt);
+    execute(&mut vm);
+    match vm.stack.pop() {
+        Option::Some(n) => { return n; }
+        Option::None => { return 1; }
+    };
+}

examples/bytecode_vm/ion.toml

@@ -0,0 +1,5 @@
+name = "bytecode_vm"
+main = "bytecode_vm.ion"
+output = "bytecode_vm"
+mode = "single"
+out_dir = "target"

examples/http_server/http_server.ion

@@ -86,7 +86,7 @@ fn dispatch_peer(peer_fd: int) {
 }
 
 fn send_string_bytes(fd: int, text: String) {
-    let nbytes: int = String::len(&text);
+    let nbytes: int = text.len();
     unsafe {
         let _sent: int = send_sys(&fd, text.data, nbytes, 0);
     }
@@ -103,7 +103,7 @@ fn handle_client(client_fd: int) -> int {
         }
 
         let body: String = http_body();
-        let body_len: int = String::len(&body);
+        let body_len: int = body.len();
         let digits: String = fmt::int_to_string(body_len);
 
         let _sent1: int = send_sys(&client_fd, "HTTP/1.1 200 OK\r\n", 17, 0);

examples/showcase/showcase.ion

@@ -80,7 +80,7 @@ fn vec_example() -> int {
         return 1;
     }
 
-    match numbers.get(0) {
+    match numbers.get_ref(0) {
         Option::Some(value) => {
             if value != 10 {
                 return 2;
@@ -373,7 +373,7 @@ fn complex_example() -> int {
         return 1;
     }
 
-    match numbers.get(0) {
+    match numbers.get_ref(0) {
         Option::Some(value) => {
             if value != 1 {
                 return 2;
@@ -384,7 +384,7 @@ fn complex_example() -> int {
         }
     };
 
-    match numbers.get(1) {
+    match numbers.get_ref(1) {
         Option::Some(value) => {
             if value != 3 {
                 return 4;
@@ -406,6 +406,70 @@ fn complex_example() -> int {
     return 0;
 }
 
+// ============================================
+// 15. BYTECODE VM - get_ref dispatch, field mutation, method calls
+// ============================================
+
+enum Op { Push { val: int }; Add; Halt; }
+
+struct BytecodeVM {
+    ip: int;
+    stack: Vec<int>;
+    code: Vec<Op>;
+}
+
+fn run_bytecode(vm: &mut BytecodeVM) -> int {
+    loop {
+        match vm.code.get_ref(vm.ip) {
+            Option::Some(op) => {
+                match op {
+                    Op::Push { val: v } => {
+                        vm.stack.push(v);
+                        vm.ip += 1;
+                    }
+                    Op::Add => {
+                        let b = match vm.stack.pop() {
+                            Option::Some(v) => { v; }
+                            Option::None => { return 0; }
+                        };
+                        let a = match vm.stack.pop() {
+                            Option::Some(v) => { v; }
+                            Option::None => { return 0; }
+                        };
+                        vm.stack.push(a + b);
+                        vm.ip += 1;
+                    }
+                    Op::Halt => { break; }
+                };
+            }
+            Option::None => { break; }
+        };
+    }
+    return 0;
+}
+
+fn bytecode_vm_example() -> int {
+    let mut vm: BytecodeVM = BytecodeVM {
+        ip: 0,
+        stack: Vec::new(),
+        code: Vec::new(),
+    };
+    vm.code.push(Op::Push { val: 10 });
+    vm.code.push(Op::Push { val: 32 });
+    vm.code.push(Op::Add);
+    vm.code.push(Op::Halt);
+    run_bytecode(&mut vm);
+    match vm.stack.pop() {
+        Option::Some(n) => {
+            if n != 42 {
+                return 1;
+            }
+        }
+        Option::None => { return 2; }
+    };
+    return 0;
+}
+
 // ============================================
 // MAIN - Run all examples
 // ============================================
@@ -462,5 +526,9 @@ fn main() -> int {
         return 11;
     }
 
+    if bytecode_vm_example() != 0 {
+        return 12;
+    }
+
     return 0;
 }

examples/text_summary/text_summary.ion

@@ -35,7 +35,7 @@ fn main() -> int {
     match fs::read_to_string_result(path) {
         ReadResult::Ok(content) => {
             let text: String = content;
-            let bytes: int = String::len(&text);
+            let bytes: int = text.len();
             let counts: TextCounts = summarize_text(text);
 
             io::println(String::from("file: sample.txt"));