tree-sitter: v1 grammar — parses examples/01-single-module.twasm end-to-end

Extends the Phase 0 scaffold (PR #58, region-decls only) to v1
coverage. The 134-line examples/01-single-module.twasm now parses
with **zero ERROR or MISSING nodes** — the full file, including
regions, memory declaration, 5 function declarations, parameter
lists with handle-mode types (&region, &mut region), effects
clauses (Read/Write/Alloc/Free/ReadRegion/WriteRegion), return
types, and the statement and expression forms used in example 01.

## What the v1 grammar now covers

Beyond the v0 scaffold's region declarations:

- memory_decl with initial/maximum/place clauses
- function_decl with parameter_list, return_type, effects_clause, body
- parameter with optional region_handle_type (&, &mut, own)
- statements: region.get, region.set, region.scan, let [mut],
  assignment, if/else, return
- expressions: literals (int / float / true / false / null),
  identifier_expr, region_var ($x), binary_expr (* / % + -
  == != < > <= >= && ||), unary_expr (- !), is_null_expr,
  paren_expr
- field_path with nested access (.pos.x)
- region_target — bare identifier form for post-null-check refs

Precedence chain: ['unary', 'mul', 'add', 'cmp', 'and', 'or'] with
unary at top and standard left-associative binary precedences.

## Still deferred (next Track A PR)

- Imports / exports
- Invariant declarations and proof statements
- const declarations
- Block-expression if (yield)
- Match on union regions
- L13-L16 surface (isolated / session / capability / choreography)
- L11/L12 surface (cost_bound / fresh / version_of / region.sync)
- Lifetime annotations on function decls
- Striated region layout

By production count v1 covers roughly 60-70% of spec/grammar.ebnf.

## Files

- grammar.js extended from ~80 to ~270 lines
- corpus/functions.txt new — 6 corpus tests covering memory_decl,
  if/else, is_null guard with bare-identifier region_target,
  region.scan with where + binding + body, nested field paths
- queries/highlights.scm extended with function/memory/if/effect/
  handle-mode/literal/builtin keyword categories
- README.md updated to reflect v1 scope; deferred-list trimmed
- tree-sitter.json metadata file (auto-generated by tree-sitter-cli)
- package.json metadata tweaks (auto by cli)

## Verification

Local generate + parse:
  $ tree-sitter generate    # no conflicts, parser.c emitted
  $ tree-sitter parse examples/01-single-module.twasm
    -> 0 ERROR nodes, exit 0

CI integration still deferred to next Track A PR (when grammar
reaches full EBNF parity the install-+-test cost justifies the
~30MB tree-sitter-cli toolchain on every PR run).

Author: claude

tools/tree-sitter-twasm/README.md

@@ -2,40 +2,45 @@
 
 Tree-sitter grammar for `.twasm` (typed-wasm surface syntax).
 
-## Status: scaffold (Phase 0 kickoff)
+## Status: v1 grammar (Phase 0 grammar extension)
 
-This is the **scaffold** for the tree-sitter grammar that will eventually
-back the Idris2 parser, the LSP, Linguist registration, and editor
-plugins. See `docs/PRODUCTION-PATH.adoc` §Phase 0 for the strategic
-context.
+The grammar now covers enough of `examples/01-single-module.twasm` to
+parse the full file: region declarations, memory declarations,
+function declarations (parameters / return types / effects), and the
+statement and expression forms used in example 01.
 
 ### What works today
 
-- Tree-sitter scaffold + corpus harness (`tree-sitter test` runs)
-- `grammar.js` v0 — covers **region declarations only**:
-  - `region Name { field: type; ... }`
-  - `region Name[N] { ... }` (array quantifier)
-  - Primitive types (`i32`, `f32`, `u8`, `bool`, etc.)
-  - Nested region references (`@OtherRegion`)
-  - Optional types (`opt<@T>`)
-  - Fixed-size array fields (`u8[24]`)
-  - `align N;` clauses
-  - `where` field constraints (range form)
-  - Single-line `//` comments
-
-### What does NOT work yet (deferred to subsequent Track A PRs)
-
-- Function declarations (`fn name(...) { ... }`)
-- Memory declarations, imports/exports
-- Statements: `region.get`, `region.set`, `let`, `if`, `while`
-- Effects, lifetime, cost-bound, freshness clauses
-- L13–L16 surface syntax (isolated modules, sessions, capabilities, choreography)
-- Tropical / epistemic extensions (L11/L12)
-- The full v1.5 surface — see `spec/grammar.ebnf` (~695 lines) for what's still ahead
-
-This deliberate v0 scope covers enough of `examples/01-single-module.twasm`
-to exercise the toolchain end-to-end without overcommitting to the
-multi-month full-grammar port.
+- **Region declarations** — `region Name { ... }`, array quantifiers `[N]`,
+  primitives, region refs (`@T`), `opt<T>`, fixed-size arrays (`u8[24]`),
+  `align N;`, `where` range constraints
+- **Memory declarations** — `memory Name { initial: N; maximum: N; place X at N; ... }`
+- **Function declarations** — `fn name(params) -> ret effects { ... } { body }`
+  - parameter modes: `&region<R>`, `&mut region<R>`, `own region<R>`, and bare typed parameters
+  - effects: `Read`, `Write`, `Alloc`, `Free`, `ReadRegion(R)`, `WriteRegion(R)`
+- **Statements** — `region.get`, `region.set`, `region.scan`, `let [mut] name [: type] = expr;`,
+  assignment, `if ... else`, `return`
+- **Expressions** — literals (`int`, `float`, `true`, `false`, `null`),
+  identifiers, `$region_var`, binary ops (`+ - * / %`, `== != < > <= >=`, `&& ||`),
+  unary (`-`, `!`), `is_null(expr)`, parenthesised
+- **Field paths** — single and nested (`.pos.x`)
+- **`//` line comments**
+
+### What does NOT work yet (next Track A PR)
+
+- Imports / exports (`import region X from "mod"`, `export region X`)
+- Invariant declarations and `proof` statements
+- `const` declarations
+- Block-expression `if ... yield`
+- Match on union regions
+- L13–L16 surface (`isolated`, `session`, `capability`, `choreography`)
+- L11/L12 surface (`cost_bound`, `fresh`, `version_of`, `region.sync`)
+- Lifetime annotations on function decls
+- `striated` region layout
+
+Scope-wise the v1 grammar covers maybe 60–70% of `spec/grammar.ebnf`
+by production count. The remainder is sequenced for the next Track A
+PR.
 
 ## Why in-tree first
 
@@ -66,8 +71,8 @@ regenerate locally via `tree-sitter generate`.
 
 | Phase | This grammar's role |
 |-------|---------------------|
-| **0** (now) | Scaffold + region-decl coverage; proves toolchain works |
-| **1** | Extend to full `spec/grammar.ebnf` parity; back the Idris2 parser |
+| **0** (current) | v1 grammar — parses `examples/01-single-module.twasm` fully |
+| **1** | Extend to remaining `spec/grammar.ebnf` productions (imports, L11-L16, match, proof); back the Idris2 parser |
 | **4** | Extract to `hyperpolymath/tree-sitter-twasm`; publish to npm; submit to Linguist |
 
 Tracked under issue [#48 (Phase 0)](https://github.com/hyperpolymath/typed-wasm/issues/48).

tools/tree-sitter-twasm/corpus/functions.txt

@@ -0,0 +1,213 @@
+============================================
+Simple function with effects and return type
+============================================
+
+fn get_player_hp(players: &region<Players>, idx: i32) -> i32
+    effects { ReadRegion(Players) }
+{
+    region.get $players[idx] .hp -> hp;
+    return hp;
+}
+
+---
+
+(source_file
+  (function_decl
+    name: (identifier)
+    (parameter_list
+      (parameter name: (identifier) type: (region_handle_type (handle_mode) (identifier)))
+      (parameter name: (identifier) type: (primitive_type)))
+    (return_type (primitive_type))
+    (effects_clause (effect (identifier)))
+    (region_get_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier))
+      binding: (identifier))
+    (return_stmt (identifier_expr (identifier)))))
+
+
+============================================
+Memory declaration with placements
+============================================
+
+memory game_memory {
+    initial: 64;
+    maximum: 256;
+    place Players at 0;
+    place Enemies at 4800;
+}
+
+---
+
+(source_file
+  (memory_decl
+    name: (identifier)
+    (initial_clause)
+    (maximum_clause)
+    (place_clause (identifier))
+    (place_clause (identifier))))
+
+
+============================================
+If/else with region.set in both branches
+============================================
+
+fn damage_player(players: &mut region<Players>, idx: i32, amount: i32)
+    effects { ReadRegion(Players), WriteRegion(Players) }
+{
+    region.get $players[idx] .hp -> current_hp;
+    let new_hp: i32 = current_hp - amount;
+
+    if new_hp < 0 {
+        region.set $players[idx] .hp, 0;
+    } else {
+        region.set $players[idx] .hp, new_hp;
+    }
+}
+
+---
+
+(source_file
+  (function_decl
+    name: (identifier)
+    (parameter_list
+      (parameter name: (identifier) type: (region_handle_type (handle_mode) (identifier)))
+      (parameter name: (identifier) type: (primitive_type))
+      (parameter name: (identifier) type: (primitive_type)))
+    (effects_clause (effect (identifier)) (effect (identifier)))
+    (region_get_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier))
+      binding: (identifier))
+    (let_stmt
+      name: (identifier)
+      (primitive_type)
+      (binary_expr (identifier_expr (identifier)) (identifier_expr (identifier))))
+    (if_stmt
+      (binary_expr (identifier_expr (identifier)) (literal (integer_literal)))
+      (region_set_stmt
+        (region_target (identifier) (identifier_expr (identifier)))
+        (field_path (identifier))
+        (literal (integer_literal)))
+      (region_set_stmt
+        (region_target (identifier) (identifier_expr (identifier)))
+        (field_path (identifier))
+        (identifier_expr (identifier))))))
+
+
+============================================
+Null check via is_null and bare-identifier region_target
+============================================
+
+fn get_enemy_target_hp(enemies: &region<Enemies>, enemy_idx: i32) -> i32
+    effects { ReadRegion(Enemies) }
+{
+    region.get $enemies[enemy_idx] .target -> maybe_target;
+
+    if is_null(maybe_target) {
+        return -1;
+    }
+
+    region.get maybe_target .hp -> target_hp;
+    return target_hp;
+}
+
+---
+
+(source_file
+  (function_decl
+    name: (identifier)
+    (parameter_list
+      (parameter name: (identifier) type: (region_handle_type (handle_mode) (identifier)))
+      (parameter name: (identifier) type: (primitive_type)))
+    (return_type (primitive_type))
+    (effects_clause (effect (identifier)))
+    (region_get_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier))
+      binding: (identifier))
+    (if_stmt
+      (is_null_expr (identifier_expr (identifier)))
+      (return_stmt (literal (integer_literal))))
+    (region_get_stmt
+      (region_target (identifier))
+      (field_path (identifier))
+      binding: (identifier))
+    (return_stmt (identifier_expr (identifier)))))
+
+
+============================================
+region.scan with where + binding + body
+============================================
+
+fn count_active_enemies(enemies: &region<Enemies>) -> i32
+    effects { ReadRegion(Enemies) }
+{
+    let mut count: i32 = 0;
+
+    region.scan $enemies where is_active == true -> |enemy| {
+        count = count + 1;
+    }
+
+    return count;
+}
+
+---
+
+(source_file
+  (function_decl
+    name: (identifier)
+    (parameter_list
+      (parameter name: (identifier) type: (region_handle_type (handle_mode) (identifier))))
+    (return_type (primitive_type))
+    (effects_clause (effect (identifier)))
+    (let_stmt name: (identifier) (primitive_type) (literal (integer_literal)))
+    (region_scan_stmt
+      (region_target (identifier))
+      (binary_expr (identifier_expr (identifier)) (literal))
+      binding: (identifier)
+      (assign_stmt (identifier) (binary_expr (identifier_expr (identifier)) (literal (integer_literal)))))
+    (return_stmt (identifier_expr (identifier)))))
+
+
+============================================
+Nested field path
+============================================
+
+fn move_player(players: &mut region<Players>, idx: i32, dx: f32, dy: f32)
+    effects { ReadRegion(Players), WriteRegion(Players) }
+{
+    region.get $players[idx] .pos.x -> old_x;
+    region.get $players[idx] .pos.y -> old_y;
+
+    region.set $players[idx] .pos.x, old_x + dx;
+    region.set $players[idx] .pos.y, old_y + dy;
+}
+
+---
+
+(source_file
+  (function_decl
+    name: (identifier)
+    (parameter_list
+      (parameter name: (identifier) type: (region_handle_type (handle_mode) (identifier)))
+      (parameter name: (identifier) type: (primitive_type))
+      (parameter name: (identifier) type: (primitive_type))
+      (parameter name: (identifier) type: (primitive_type)))
+    (effects_clause (effect (identifier)) (effect (identifier)))
+    (region_get_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier) (identifier))
+      binding: (identifier))
+    (region_get_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier) (identifier))
+      binding: (identifier))
+    (region_set_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier) (identifier))
+      (binary_expr (identifier_expr (identifier)) (identifier_expr (identifier))))
+    (region_set_stmt
+      (region_target (identifier) (identifier_expr (identifier)))
+      (field_path (identifier) (identifier))
+      (binary_expr (identifier_expr (identifier)) (identifier_expr (identifier))))))