tree-sitter: v1 grammar — parses examples/01-single-module.twasm end-to-end (zero ERROR nodes) (#62)

## Summary

Extends the Phase 0 tree-sitter scaffold (PR #58, region-decls only) to
**v1 grammar** that parses `examples/01-single-module.twasm`
**end-to-end with zero parse errors**.

## Verification (local)

```bash
cd tools/tree-sitter-twasm
npm install
tree-sitter generate    # no conflicts; parser.c emitted
tree-sitter parse ../../examples/01-single-module.twasm
# → 0 ERROR / 0 MISSING nodes, exit 0, full AST for all 134 lines
```

## What v1 now covers (beyond region declarations)

- **`memory_decl`** — `memory Name { initial: N; maximum: N; place X at
N; }`
- **`function_decl`** — `fn name(params) -> ret effects { ... } { body
}`
  - `parameter_list` with `region_handle_type` (`&`, `&mut`, `own`)
- `effects_clause` — `Read / Write / Alloc / Free / ReadRegion(R) /
WriteRegion(R)`
  - `return_type` including `void`
- **Statements** — `region.get`, `region.set`, `region.scan` (with
`where` + binding + body), `let [mut] name [: type] = expr;`,
assignment, `if`/`else`, `return`
- **Expressions** — literals (int/float/bool/null), `identifier_expr`,
`region_var` (`$x`), `binary_expr` (full operator set with precedence),
`unary_expr`, `is_null_expr`, `paren_expr`
- **Field paths** — including nested access (`.pos.x`)
- **`region_target`** — bare-identifier form for post-null-check
references

Precedence chain: `['unary', 'mul', 'add', 'cmp', 'and', 'or']` with
unary at top.

## Still deferred (next Track A PR)

- Imports / exports
- Invariant declarations + 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 ~60–70% of `spec/grammar.ebnf`.

## Files

| File | Change |
|---|---|
| `grammar.js` | ~80 → ~270 lines |
| `corpus/functions.txt` | new — 6 corpus tests covering memory_decl,
if/else, is_null guard with bare-ident target, scan, nested field paths
|
| `queries/highlights.scm` | extended with
function/memory/if/effect/handle-mode/literal/builtin categories |
| `README.md` | updated to reflect v1 scope |
| `tree-sitter.json` | new — tree-sitter-cli metadata |
| `package.json` | minor metadata tweaks |

## CI integration

Still deferred to the next Track A PR. When the grammar reaches full
EBNF parity, the install-and-test cost (~30MB tree-sitter-cli toolchain
on every PR run) is justified by the regression value. Today the 6-test
corpus + the local parse-of-example-01 covers the regression risk well
enough.

## Phase 0 impact

This PR plus the existing Track A scaffold (PR #58) moves the Phase 0
§Track A checklist from "scaffold landed" to "scaffold + v1 grammar
landed, parses simplest example end-to-end". Remaining Track A items
(full EBNF parity, Idris2 parser, ReScript cut, codegen v0) are still
ahead.

## Test plan

- [x] `tree-sitter generate` succeeds (no conflicts)
- [x] `tree-sitter parse examples/01-single-module.twasm` returns 0
ERROR / 0 MISSING nodes
- [ ] Corpus tests pass on a CI runner with tree-sitter-cli installed
(deferred to next PR with CI wiring)
- [ ] Smoke test, structural E2E, claim-envelope, property,
security-envelope, proof regression — none touch
tools/tree-sitter-twasm/ so no regressions expected


---
_Generated by [Claude
Code](https://claude.ai/code/session_01ExgUTJmU5UQQNLKynwxDjm)_

Author: hyperpolymath

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))))))