Make verified-patterns.md the canonical idiom reference and slim ION_SPEC §9/§12 to link to it.

Author: Cod-e-Codes

.cursor/skills/ion-lang/SKILL.md

@@ -25,6 +25,7 @@ Ion is a move-only, no-GC systems language transpiled to C. This skill orients y
 | [CHANGELOG.md](../../../CHANGELOG.md) | Release notes by month |
 | [SECURITY.md](../../../SECURITY.md) | Security reporting scope and policy |
 | [tests/README.md](../../../tests/README.md) | Integration test catalog |
+| [writing-ion-code/references/verified-patterns.md](../writing-ion-code/references/verified-patterns.md) | Canonical idioms (ION_SPEC §12 indexes this) |
 
 **Compiler pipeline** (see [references/compiler-pipeline.md](references/compiler-pipeline.md)):
 

.cursor/skills/ion-lang/references/language-constraints.md

@@ -21,7 +21,7 @@ References `&T` and `&mut T` are stack-local views. **Rejected:**
 
 **Borrow conflicts** (ION_SPEC section 5.3): at most one `&mut T` or any number of `&T` on the same **root owner binding**. Lasting borrows come from `let r = &x`, `let r = &mut s.field`, etc., and end when the binding's scope ends; field and index paths borrow the root owner, not disjoint field slots. Ephemeral `&` / `&mut` in call arguments are checked but not stored. While a lasting borrow is active, the owner cannot be read, assigned, or moved (including copy types and other field paths).
 
-APIs that would return `&T` in Rust must use owned values, indices, or callbacks in Ion.
+APIs that would return `&T` in Rust must use owned values, indices, or the patterns in [writing-ion-code/references/verified-patterns.md](../writing-ion-code/references/verified-patterns.md).
 
 ## Concurrency
 

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

@@ -32,7 +32,7 @@ Task progress:
 
 For ownership and no-escape rules, see [ion-lang/references/language-constraints.md](../ion-lang/references/language-constraints.md).
 
-For syntax templates and anti-patterns, see [references/verified-patterns.md](references/verified-patterns.md).
+For syntax templates and verified idioms, see [references/verified-patterns.md](references/verified-patterns.md) (canonical; ION_SPEC §12 indexes it).
 
 ## Program workflow
 
@@ -133,7 +133,7 @@ Fn literals lower to static C functions and must not reference outer bindings (o
 
 ## Documentation comments
 
-Ion uses plain `//` line comments only. No `///` or `//!`. Contiguous `//` lines **immediately above** a declaration (no blank line before the declaration) are attached as documentation for IDE hover; the same rule applies when `pub` precedes the item. A blank line breaks association. File-level overview comments go at the top of the file before imports. Section-divider comment blocks in examples should be separated from declarations by a blank line. See ION_SPEC section 12.6.
+Ion uses plain `//` line comments only. No `///` or `//!`. Contiguous `//` lines **immediately above** a declaration (no blank line before the declaration) are attached as documentation for IDE hover; the same rule applies when `pub` precedes the item. A blank line breaks association. File-level overview comments go at the top of the file before imports. Section-divider comment blocks in examples should be separated from declarations by a blank line. See ION_SPEC §12.1.
 
 **Unsafe and FFI**
 
@@ -187,7 +187,7 @@ These are **not** in Ion today. Check ION_SPEC.md section 10.3 before using anyt
 - Union types `A | B` (reserved; use enums)
 - Nested tuples, tuple `==`, or generic tuple type parameters
 - `mut` on function parameters (use `&mut T` in the signature instead)
-- `///` / `//!` doc comment syntax (use adjacent `//` instead; see ION_SPEC §12.6)
+- `///` / `//!` doc comment syntax (use adjacent `//` instead; see ION_SPEC §12.1)
 - File APIs beyond `fs::read_to_string_result` (streaming `File` is deferred in spec)
 
 When unsure, **grep** `tests/` and `examples/` for the construct. If nothing matches, tell the user it is likely unsupported rather than inventing syntax.

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

@@ -1,5 +1,7 @@
 # Verified Ion Patterns
 
+**Canonical idiom reference** for agents and authors. [ION_SPEC.md](../../../ION_SPEC.md) §12 indexes this file; keep long examples here, not in the spec. Every `ion` block should match a pattern in `tests/` or `examples/` (linked inline). When semantics change, update this file and tests together.
+
 Copy patterns from here or from linked test files. Do not add constructs not shown in ION_SPEC.md or this repo.
 
 ## Types
@@ -62,6 +64,147 @@ fn step(vm: &mut VM) {
 
 Field paths are valid assignment targets on owned structs and `&mut` parameters.
 
+## Ownership move
+
+```ion
+struct Packet {
+    id: i32;
+    data: Vec<u8>;
+}
+
+fn make_packet(data: Vec<u8>) -> Packet {
+    Packet { id: 1, data: data }
+}
+
+fn main() -> int {
+    let buf: Vec<u8> = Vec::new();
+    let pkt = make_packet(buf);
+    // buf is invalid after the move; pkt owns the data
+    return 0;
+}
+```
+
+See [tests/test_move_basic.ion](../../../../tests/test_move_basic.ion).
+
+## Index and handle search
+
+When another language would return `&T`, return an index (`int`) or handle and re-index locally. Read-only scans use `Vec::get_ref` (does not hollow the vector). See [tests/test_vec_search_index_ok.ion](../../../../tests/test_vec_search_index_ok.ion) and [tests/test_vec_get_ref_scan.ion](../../../../tests/test_vec_get_ref_scan.ion).
+
+```ion
+enum Option<T> {
+    Some(T);
+    None;
+}
+
+struct Customer {
+    id: int;
+    active: int;
+}
+
+fn find_customer_index(customers: &Vec<Customer>, target_id: int) -> int {
+    let mut i: int = 0;
+    let len: int = Vec::len(customers);
+    while i < len {
+        match Vec::get_ref(customers, i) {
+            Option::Some(c) => {
+                if c.id == target_id {
+                    return i;
+                }
+            }
+            Option::None => {
+                return -1;
+            }
+        };
+        i = i + 1;
+    }
+    return -1;
+}
+
+fn main() -> int {
+    let mut customers: Vec<Customer> = Vec::new();
+    let idx: int = find_customer_index(&customers, 42);
+    if idx >= 0 {
+        match Vec::get(&customers, idx) {
+            Option::Some(c) => {
+                let id: int = c.id;
+                Vec::set(
+                    &mut customers,
+                    idx,
+                    Customer {
+                        id: id,
+                        active: 1,
+                    },
+                );
+            }
+            Option::None => {}
+        };
+    }
+    return 0;
+}
+```
+
+## Mutating Vec elements
+
+`Vec::get` moves the element out. Copy fields, rebuild the struct, and `Vec::set` it back ([tests/test_vec_get_putback.ion](../../../../tests/test_vec_get_putback.ion)). Helpers can take `&mut T` on an owned local:
+
+```ion
+fn mark_active(c: &mut Customer) {
+    c.active = 1;
+}
+```
+
+## Comparing borrowed structs
+
+Read fields through `&Struct` parameters. Ion does not allow reference fields in structs.
+
+```ion
+struct Customer {
+    id: int;
+    score: int;
+}
+
+fn compare(a: &Customer, b: &Customer) -> int {
+    if a.score != b.score {
+        return a.score - b.score;
+    }
+    return a.id - b.id;
+}
+```
+
+## Concurrency and ownership transfer
+
+Move owned values into `spawn` and channels; no shared mutable state across threads. See [examples/spawn_channel/spawn_channel.ion](../../../../examples/spawn_channel/spawn_channel.ion) and [examples/channel_worker/channel_worker.ion](../../../../examples/channel_worker/channel_worker.ion).
+
+```ion
+struct Job {
+    data: Vec<u8>;
+}
+
+fn worker(rx: Receiver<Job>) {
+    let mut rx_mut: Receiver<Job> = rx;
+    loop {
+        let job: Job = recv(&mut rx_mut);
+        // use job.data
+    }
+}
+
+fn main() -> int {
+    let (tx, rx): (Sender<Job>, Receiver<Job>) = channel<Job>();
+
+    spawn {
+        worker(rx);
+    };
+
+    let job = Job { data: Vec::new() };
+    send(&tx, job);
+    return 0;
+}
+```
+
+## Owned API boundaries
+
+At module exports and public functions, prefer owned results (`Vec<T>`, `String`, structs with owned fields) over borrowed views. Use `&T`, `&str`, and local `Option<&T>` from `Vec::get_ref` inside a single function only.
+
 ## 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`.
@@ -193,14 +336,12 @@ let w = v;
 let _ = v.len();
 ```
 
-See [tests/test_ref_return_error2.ion](../../../../tests/test_ref_return_error2.ion), [tests/test_spawn_ref_error.ion](../../../../tests/test_spawn_ref_error.ion), and ION_SPEC.md section 9.4.
+See [tests/test_ref_return_error2.ion](../../../../tests/test_ref_return_error2.ion), [tests/test_spawn_ref_error.ion](../../../../tests/test_spawn_ref_error.ion), and ION_SPEC.md §9.4.
 
 ## Design alternatives (no borrowed returns)
 
 When another language would return `&T`:
 
 - Return an owned value or `Option<T>` by move
-- Return an index or handle, caller re-indexes locally
-- Pass a callback that receives `&T` inside the callee's stack frame
-
-See ION_SPEC.md section 12 (non-normative).
+- Return an index or handle; caller re-indexes locally (see **Index and handle search** above)
+- Call a helper with `&mut T` on an owned local after `Vec::get` / before `Vec::set`