plum

# Guard-Clause Match Arms Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a subject-less `match` form whose arms are boolean guard conditions (`| cond => body`) instead of value patterns, with `_` as a catch-all, per `docs/superpowers/specs/2026-07-24-guard-clause-match-design.md`.

**Architecture:** Bottom-up: grammar (new `guard_case` rule, `match` becomes a `choice` of subject-ful/subject-less) → AST (one new `CasePattern::Guard(Expr)` variant, no new top-level struct) → parser (new `guard_case`-parsing branch reusing `parse_match`'s existing subject-splitting logic, which already tolerates zero subjects) → checker (`check_match` branches on `m.subjects.is_empty()`) → codegen (new dedicated `compile_guard_match`, reusing `compile_if`'s if/else-if/else chain shape, bypassing the subject-scratch/pattern-fallthrough machinery entirely — the existing Collector pass needs no changes, since it already produces an empty scratch-type list and a no-op pattern-zip for a subject-less match, verified during design).

**Tech Stack:** tree-sitter (JS grammar), Rust (`plum-core`, `plum-checker`, `plum-wasm-codegen`).

## Global Constraints

- Spec: `docs/superpowers/specs/2026-07-24-guard-clause-match-design.md`

- Guard arm syntax: `"|" (expression | "_") "=>" (expression | body)` — leading `|` required, `=>` unchanged, no new punctuation elsewhere.

- `_` in guard position parses to the EXISTING `CasePattern::Wildcard` (not a new "always-true" node) — every downstream consumer that already understands `Wildcard` needs no new knowledge.

- Subject-ful `match` (today's form) is completely unchanged — this is purely additive, disambiguated by presence/absence of a subject expression before the indent.

- No stdlib `Ordering` type is added — out of scope.

- Run `cargo test --workspace` and (from `tooling/tree-sitter-plum/`) `npx --yes tree-sitter-cli test` after every task — all pre-existing tests must keep passing throughout.

---

### Task 1: Grammar — new `guard_case` rule and subject-less `match`

**Files:**

- Modify: `tooling/tree-sitter-plum/grammar.js`

- Modify: `tooling/tree-sitter-plum/test/corpus/match.txt`

**Interfaces:**

- Consumes: nothing (bottom of the pipeline).

- Produces: a regenerated parser where `match` accepts EITHER today's subject-ful form OR a new subject-less form whose body is `repeat(field("case", $.guard_case))`; `guard_case` is a new node kind `"guard_case"` with fields `"guard"` (an `expression` or the literal `"_"`) and `"body"`.

- [ ] **Step 1: Edit the `match` rule to add the subject-less alternative**

In `tooling/tree-sitter-plum/grammar.js`, find the current `match` rule:

```js

    match: ($) =>

      prec.left(

        seq(

          "match",

          commaSep1(field("subject", $.expression)), // remove comma use tuples (a, b) and match against tuples

          $._indent,

          repeat(field("case", $.case)),

          $._dedent,

        ),

      ),

```

Replace it with:

```js

    match: ($) =>

      prec.left(

        choice(

          seq(

            "match",

            commaSep1(field("subject", $.expression)), // remove comma use tuples (a, b) and match against tuples

            $._indent,

            repeat(field("case", $.case)),

            $._dedent,

          ),

          seq(

            "match",

            $._indent,

            repeat(field("case", $.guard_case)),

            $._dedent,

          ),

        ),

      ),

```

- [ ] **Step 2: Add the `guard_case` rule**

Add a new rule near `case`/`case_pattern` (find the existing `case`/`case_pattern`/`class_pattern` rules and add `guard_case` right after `case_pattern`):

```js

    guard_case: ($) =>

      seq(

        "|",

        field("guard", choice($.expression, "_")),

        "=>",

        field("body", choice($.expression, $.body)),

      ),

```

- [ ] **Step 3: Regenerate the parser**

Run: `cd tooling/tree-sitter-plum && npx --yes tree-sitter-cli generate`

Expected: succeeds with no conflicts. If tree-sitter reports a conflict (e.g. between the two `match` alternatives, or between `guard_case`'s `"_"` and `case_pattern`'s `"_"`), stop and report BLOCKED — that would mean the two forms aren't as structurally distinguishable as this plan assumes.

- [ ] **Step 4: Add corpus tests**

In `tooling/tree-sitter-plum/test/corpus/match.txt`, add a new test block (matching the file's existing format — a `====` header, source, a `----` divider, then the expected S-expression tree). Read the existing file first to match its exact section-separator style, then add:

```

================================================================================

match - guard-clause arms, no subject

================================================================================

compare(x: Int, y: Int) -> Int =

  match

    | x > y => 1

    | x == y => 0

    | _ => -1

--------------------------------------------------------------------------------

(source

  (fn

    (fn_identifier)

    (param

      (var_identifier)

      (type

        (type_identifier)))

    (param

      (var_identifier)

      (type

        (type_identifier)))

    (type

      (type_identifier))

    (body

      (match

        (guard_case

          (expression

            (comparison_operator

              (primary_expression

                (var_identifier))

              (primary_expression

                (var_identifier))))

          (expression

            (primary_expression

              (integer))))

        (guard_case

          (expression

            (comparison_operator

              (primary_expression

                (var_identifier))

              (primary_expression

                (var_identifier))))

          (expression

            (primary_expression

              (integer))))

        (guard_case

          (expression

            (primary_expression

              (unary_operator

                (primary_expression

                  (integer)))))))))))

```

Note: the exact tree shape for the `_` arm's body (`-1`, a unary-minus integer) and the precise nesting of `comparison_operator`/`expression` wrappers may not match this sketch exactly — **you must run Step 5 first, look at the ACTUAL generated tree via `tree-sitter parse`, and paste the real output into the corpus file rather than trusting this sketch verbatim.** This is standard practice for corpus tests (they encode ground truth from the real parser, not a hand-guess) and mirrors how earlier corpus updates in this codebase were done.

- [ ] **Step 5: Run the corpus tests, fix the expected tree from real output, iterate to green**

Run: `cd tooling/tree-sitter-plum && npx --yes tree-sitter-cli test 2>&1 | tail -100`

If the new test fails, run `echo '<the exact source from Step 4>' | npx --yes tree-sitter-cli parse -` (or write it to a temp `.plum` file and parse that) to see the actual tree, then correct the corpus file's expected S-expression to match reality. Repeat until `tree-sitter-cli test` reports 100% success including your new test.

- [ ] **Step 6: Commit**

```bash

git add tooling/tree-sitter-plum/grammar.js tooling/tree-sitter-plum/src tooling/tree-sitter-plum/test/corpus/match.txt

git commit -m "feat(grammar): add subject-less guard-clause match arms"

```

---

### Task 2: `plum-core` — AST and parser support for guard arms

**Files:**

- Modify: `plum-core/src/ast.rs`

- Modify: `plum-core/src/parser.rs`

- Modify: `plum-core/tests/parser_test.rs`

**Interfaces:**

- Consumes: the regenerated grammar from Task 1 (node kind `"guard_case"` with fields `"guard"`/`"body"`; a `match` node with zero `"subject"` children and `"guard_case"`-kind case children instead of `"case"`-kind ones).

- Produces: `CasePattern::Guard(ast::Expr)` (new variant); `Match { subjects: vec![], cases }` for a guard-form match, where each `Case.patterns` has exactly one element (`Guard(expr)` or `Wildcard`).

- [ ] **Step 1: Add the `Guard` variant to `CasePattern`**

In `plum-core/src/ast.rs`, find:

```rust

#[derive(Debug, Clone, PartialEq)]

pub enum CasePattern {

    Class { name: String, fields: Vec<CasePattern> },

    String(String),

    Int(i64),

    Float(f64),

    Name(String),

    Wildcard,

}

```

Add a `Guard` variant:

```rust

#[derive(Debug, Clone, PartialEq)]

pub enum CasePattern {

    Class { name: String, fields: Vec<CasePattern> },

    String(String),

    Int(i64),

    Float(f64),

    Name(String),

    Wildcard,

    /// A boolean guard-clause arm in a subject-less `match` (`| x > y => ...`).

    Guard(Expr),

}

```

- [ ] **Step 2: Parse `guard_case` nodes**

In `plum-core/src/parser.rs`, `parse_match` currently reads:

```rust

    fn parse_match(&self, node: Node) -> Match {

        // match: "match" commaSep1(expression) "is" case+

        let mut cursor = node.walk();

        let named: Vec<Node> = node.named_children(&mut cursor).collect();

        let split = named.iter().position(|n| n.kind() == "case").unwrap_or(named.len());

        let subjects = named[..split]

            .iter()

            .map(|n| { let u = self.unwrap_expr_node(*n); self.parse_expression(u) })

            .collect();

        let cases = named[split..]

            .iter()

            .filter(|n| n.kind() == "case")

            .map(|n| self.parse_case(*n))

            .collect();

        Match { subjects, cases }

    }

```

Replace it so it also recognizes `guard_case` children (a guard-form match has NO `"case"`-kind children at all — only `"guard_case"`-kind ones — so `split` naturally lands at `named.len()` for a guard match, giving an empty `subjects` slice, which is exactly the desired `Match.subjects: vec![]`; you just need the `cases` collection to also parse `guard_case` nodes):

```rust

    fn parse_match(&self, node: Node) -> Match {

        // match: "match" commaSep1(expression) case+  |  "match" guard_case+

        let mut cursor = node.walk();

        let named: Vec<Node> = node.named_children(&mut cursor).collect();

        let split = named.iter()

            .position(|n| n.kind() == "case" || n.kind() == "guard_case")

            .unwrap_or(named.len());

        let subjects = named[..split]

            .iter()

            .map(|n| { let u = self.unwrap_expr_node(*n); self.parse_expression(u) })

            .collect();

        let cases = named[split..]

            .iter()

            .map(|n| match n.kind() {

                "case" => self.parse_case(*n),

                "guard_case" => self.parse_guard_case(*n),

                _ => Case { patterns: vec![], body: Block { stmts: vec![] } },

            })

            .collect();

        Match { subjects, cases }

    }

    fn parse_guard_case(&self, node: Node) -> Case {

        // guard_case: "|" field("guard", expression | "_") "=>" field("body", expression | body)

        let guard_node = node.child_by_field_name("guard");

        let pattern = match guard_node {

            Some(n) if self.text(n) == "_" => CasePattern::Wildcard,

            Some(n) => {

                let unwrapped = self.unwrap_expr_node(n);

                CasePattern::Guard(self.parse_expression(unwrapped))

            }

            None => CasePattern::Wildcard,

        };

        let body = node.child_by_field_name("body").map(|n| {

            if n.kind() == "body" {

                self.parse_block(n)

            } else {

                let unwrapped = self.unwrap_expr_node(n);

                Block { stmts: vec![Stmt::Expr(self.parse_expression(unwrapped))] }

            }

        }).unwrap_or(Block { stmts: vec![] });

        Case { patterns: vec![pattern], body }

    }

```

Read the current `parse_match`/`parse_case` in the actual file first — the surrounding code may have shifted slightly since this plan was written; match the existing style (e.g. whether `child_by_field_name` or positional `named_child` indexing is idiomatic here — `parse_case` uses positional filtering because `case`'s patterns and body aren't field-tagged the same way, but `guard_case`'s fields ARE explicitly named in the grammar, so `child_by_field_name` is the more direct and correct choice for it specifically).

- [ ] **Step 3: Add a parser test for guard-clause matches**

In `plum-core/tests/parser_test.rs`, add a test that parses a small guard-match function (e.g. the `compare` example from the spec) and asserts on the resulting `ast::Match`: `subjects` is empty, `cases.len() == 3`, the first two cases' single pattern is `CasePattern::Guard(_)` (match on the variant, don't need to assert the exact `Expr` shape), and the last case's pattern is `CasePattern::Wildcard`. Follow this file's existing test style/helpers (e.g. however it currently parses a source string into an `ast::Source` and drills into a specific `Fn`'s body).

- [ ] **Step 4: Run `plum-core`'s tests**

Run: `cargo test -p plum-core 2>&1 | tail -60`

Expected: PASS, including your new test.

- [ ] **Step 5: Commit**

```bash

git add plum-core/src/ast.rs plum-core/src/parser.rs plum-core/tests/parser_test.rs

git commit -m "feat(plum-core): parse guard-clause match arms into CasePattern::Guard"

```

---

### Task 3: `plum-checker` — type-check guard-clause matches

**Files:**

- Modify: `plum-checker/src/lib.rs`

- Modify: `plum-checker/tests/checker_tests.rs`

**Interfaces:**

- Consumes: `Match.subjects: Vec<Expr>` possibly empty, `CasePattern::Guard(Expr)` from Task 2.

- Produces: a guard's condition must type as `Bool`; a `Wildcard` guard arm needs no check; every arm's body still checks against `declared_ret` exactly as today.

- [ ] **Step 1: Branch `check_match` on empty subjects**

In `plum-checker/src/lib.rs`, `check_match` currently starts:

```rust

fn check_match(m: &ast::Match, env: &TypeEnv, declared_ret: &PlumType, fn_name: &str, ctx: &CheckCtx) -> Vec<CheckError> {

    let mut errors = Vec::new();

    let mut subject_types: Vec<PlumType> = Vec::new();

    for s in &m.subjects {

        match infer_expr(s, env, ctx) {

            Ok(t) => subject_types.push(t),

            Err(msg) => errors.push(CheckError { message: format!("fn '{}': match subject: {}", fn_name, msg) }),

        }

    }

    if subject_types.len() != m.subjects.len() {

        return errors; // a subject failed to type — cases can't be checked meaningfully

    }

    for case in &m.cases {

        // ... existing subject-ful pattern-zip logic ...

    }

    errors

}

```

Add a guard-clause branch at the very top, before any of the existing subject-inference logic:

```rust

fn check_match(m: &ast::Match, env: &TypeEnv, declared_ret: &PlumType, fn_name: &str, ctx: &CheckCtx) -> Vec<CheckError> {

    let mut errors = Vec::new();

    if m.subjects.is_empty() {

        for case in &m.cases {

            let mut case_env = env.clone();

            match case.patterns.first() {

                Some(ast::CasePattern::Guard(e)) => match infer_expr(e, &case_env, ctx) {

                    Ok(ty) => {

                        if let Err(msg) = unify(&ty, &PlumType::TBool) {

                            errors.push(CheckError {

                                message: format!("fn '{}': guard clause must be Bool: {}", fn_name, msg),

                            });

                        }

                    }

                    Err(msg) => errors.push(CheckError {

                        message: format!("fn '{}': guard clause: {}", fn_name, msg),

                    }),

                },

                Some(ast::CasePattern::Wildcard) => {}

                _ => errors.push(CheckError {

                    message: format!(

                        "fn '{}': guard-clause match arm must be a boolean condition or '_'",

                        fn_name

                    ),

                }),

            }

            errors.append(&mut check_block(&case.body, &mut case_env, declared_ret, fn_name, ctx));

        }

        return errors;

    }

    let mut subject_types: Vec<PlumType> = Vec::new();

    for s in &m.subjects {

        match infer_expr(s, env, ctx) {

            Ok(t) => subject_types.push(t),

            Err(msg) => errors.push(CheckError { message: format!("fn '{}': match subject: {}", fn_name, msg) }),

        }

    }

    if subject_types.len() != m.subjects.len() {

        return errors; // a subject failed to type — cases can't be checked meaningfully

    }

    for case in &m.cases {

        // ... existing subject-ful pattern-zip logic, UNCHANGED ...

    }

    errors

}

```

Read the current file first to get the exact unchanged middle section right — copy it verbatim from the current source, don't retype it from this plan's earlier excerpt (this plan's excerpt may be stale relative to the actual file).

- [ ] **Step 2: `check_pattern` also needs a `Guard` arm (for completeness / future callers)**

`check_pattern` is a `match` over `CasePattern` with no `Guard` variant yet — since Rust match exhaustiveness will now fail to compile once `CasePattern::Guard` exists, add an arm (even though `check_match`'s new guard branch above doesn't call `check_pattern` for guard cases — some other code path might, and the compiler needs it regardless):

```rust

        ast::CasePattern::Guard(e) => {

            // Guard clauses are only meaningful inside a subject-less match, which

            // check_match's dedicated branch already type-checks directly against

            // Bool — check_pattern is only reached for subject-ful matches, where a

            // bare Guard pattern shouldn't structurally occur. Treat it permissively

            // (no subject to unify against) rather than panicking.

            let _ = e;

            Ok(())

        }

```

Add this arm to `check_pattern`'s `match pat { ... }` (exact insertion point: wherever the current arms are — read the file first).

- [ ] **Step 3: Add checker tests**

In `plum-checker/tests/checker_tests.rs`, add tests for:

1. A guard match with all-`Bool` guards and a `_` fallback type-checks with no errors (e.g. the `compare` example).

2. A guard match with a non-`Bool` guard (e.g. `| x + 1 => 0`) produces an error.

3. A guard match with arms returning inconsistent types (e.g. one arm returns `Int`, another returns `Str`) produces an error, the same way today's subject-ful match already does for that case — find and mirror whatever existing test covers that for subject-ful match.

Follow this file's existing test conventions (however it currently asserts on `Vec<CheckError>` — count, message substring, etc.).

- [ ] **Step 4: Run `plum-checker`'s tests**

Run: `cargo test -p plum-checker 2>&1 | tail -100`

Expected: PASS, including your new tests.

- [ ] **Step 5: Commit**

```bash

git add plum-checker/src/lib.rs plum-checker/tests/checker_tests.rs

git commit -m "feat(plum-checker): type-check guard-clause match arms"

```

---

### Task 4: `plum-wasm-codegen` — compile guard-clause matches

**Files:**

- Modify: `plum-wasm-codegen/src/lib.rs`

- Modify: `plum-wasm-codegen/tests/codegen_tests.rs`

**Interfaces:**

- Consumes: `Match.subjects.is_empty()` + `CasePattern::Guard(Expr)`/`Wildcard` cases from Task 2/3.

- Produces: a guard match compiles as an if/else-if/else chain (mirroring `compile_if`), trapping (`Unreachable`) if no guard is true and no `Wildcard` arm is present.

- [ ] **Step 1: Add a dedicated `compile_guard_match` function**

In `plum-wasm-codegen/src/lib.rs`, `compile_match` currently starts by looking up a match-scratch slot and evaluating subjects — none of that applies to a guard match. Add a branch at the very top of `compile_match` (read the current function first to get its exact current signature/body verbatim, this plan's earlier excerpt may be stale):

```rust

fn compile_match(

    m: &ast::Match,

    body: &mut Vec<u8>,

    ctx: &LocalCtx,

    state: &mut ModuleState,

    result_vt: Option<ValType>,

) -> Result<(), String> {

    if m.subjects.is_empty() {

        return compile_guard_match(m, result_vt, body, ctx, state);

    }

    // ... existing subject-ful body, UNCHANGED ...

}

```

Add the new function near `compile_if` (they share the same if/else-if/else shape and `compile_case_body` helper):

```rust

/// Compiles a subject-less guard-clause match (`match \n | cond => body ...`) as an

/// if/else-if/else chain — structurally identical to `compile_if`, since a guard

/// arm's condition is an ordinary boolean expression with no subject to evaluate or

/// destructure. A `CasePattern::Wildcard` arm (bare `_`) becomes the chain's

/// trailing `else`; if none is present and every guard is false at runtime, the

/// chain falls through to `Unreachable` — the same "non-exhaustive match traps"

/// behavior today's pattern-match codegen already has for enums, just checked at

/// runtime instead of compile time (guard conditions aren't statically enumerable).

fn compile_guard_match(

    m: &ast::Match,

    result_vt: Option<ValType>,

    body: &mut Vec<u8>,

    ctx: &LocalCtx,

    state: &mut ModuleState,

) -> Result<(), String> {

    let bt = block_type_for(result_vt);

    let mut open_blocks = 0usize;

    let mut wildcard_case: Option<&ast::Case> = None;

    for case in &m.cases {

        match case.patterns.first() {

            Some(ast::CasePattern::Wildcard) => {

                wildcard_case = Some(case);

                break; // any arm after a `_` is unreachable; stop compiling arms here

            }

            Some(ast::CasePattern::Guard(cond)) => {

                compile_expr(cond, body, ctx, state)?;

                Instruction::If(bt).encode(body);

                compile_case_body(&case.body, result_vt, body, ctx, state)?;

                Instruction::Else.encode(body);

                open_blocks += 1;

            }

            _ => return Err("codegen: guard-clause match arm must be a guard or '_'".to_string()),

        }

    }

    match wildcard_case {

        Some(case) => compile_case_body(&case.body, result_vt, body, ctx, state)?,

        None => {

            if result_vt.is_some() {

                Instruction::Unreachable.encode(body);

            }

            // A guard match with no `_` in a non-value (statement) position and no

            // guard true at runtime simply falls through to nothing further to do —

            // still needs the trap so execution doesn't silently continue with a

            // dangling value-stack expectation when result_vt IS Some.

        }

    }

    for _ in 0..open_blocks {

        Instruction::End.encode(body);

    }

    Ok(())

}

```

Read `compile_if`'s exact current body first and cross-check this sketch against it — in particular confirm the exact `Instruction::If`/`Else`/`End` encoding calls and `compile_case_body`'s exact signature match what's actually in the file (this plan's earlier research excerpt of `compile_if` may have drifted).

- [ ] **Step 2: Confirm the Collector pass needs no changes (verification step, not necessarily a code change)**

Read the `Collector` struct's `walk_stmt` handling of `ast::Stmt::Match(m)` (search for `match_scratch.insert` in `plum-wasm-codegen/src/lib.rs`). For a guard match, `m.subjects` is empty, so `subject_types` collects to `vec![]`, and the `case.patterns.iter().zip(subject_types.iter())` loop naturally produces zero iterations for every case (since `subject_types` is empty) — meaning `collect_pattern` is never called for `Guard`/`Wildcard` patterns, which is correct (they need no scratch-slot or env-binding registration). Confirm this by reading the actual code; if the Collector's `walk_stmt`/`walk_expr` for `Match` does anything ELSE that assumes `subjects.len() > 0` (e.g. panics on an empty subject list, or skips walking case bodies for empty-subject matches), that would be a real gap — fix it if found, and note the fix in your report. If it's exactly as described (a no-op for guard cases, but still walks `case.body` for nested match/expression discovery), no code change is needed here, just note that you verified it.

- [ ] **Step 3: Add codegen tests**

In `plum-wasm-codegen/tests/codegen_tests.rs`, add tests:

1. A guard match with a `_` fallback (the `compare` example) compiles and runs correctly for at least 3 different input pairs (one hitting each arm), via `run_main`.

2. A guard match with NO `_` fallback traps at runtime when no guard is true — mirror whatever existing test pattern this file already uses for "non-exhaustive match traps" (search for an existing trap/`Unreachable`-related test, e.g. around `todo_traps_at_runtime` or a non-exhaustive-enum-match test, and follow its assertion style for "the wasm call traps/errors").

- [ ] **Step 4: Run the codegen tests**

Run: `cargo test -p plum-wasm-codegen 2>&1 | tail -100`

Expected: PASS, including your new tests.

- [ ] **Step 5: Run the full workspace suite**

Run: `cargo test --workspace 2>&1 | tail -100`

Expected: all PASS.

- [ ] **Step 6: Commit**

```bash

git add plum-wasm-codegen/src/lib.rs plum-wasm-codegen/tests/codegen_tests.rs

git commit -m "feat(plum-wasm-codegen): compile guard-clause match arms as if/else-if chains"

```

---

### Task 5: Final verification

**Files:** none (verification only).

- [ ] **Step 1: Full workspace test suite**

Run: `cargo test --workspace 2>&1 | tail -100`

Expected: all PASS.

- [ ] **Step 2: Tree-sitter corpus suite**

Run: `cd tooling/tree-sitter-plum && npx --yes tree-sitter-cli test 2>&1 | tail -60`

Expected: all PASS.

- [ ] **Step 3: No commit needed** — verification only.