Section 9: Match Expressions

Goal: Full pattern matching support

SPEC: spec/15-patterns.md

Proposals:

proposals/approved/match-expression-syntax-proposal.md — Match expression and pattern syntax
proposals/approved/pattern-matching-exhaustiveness-proposal.md — Exhaustiveness checking
proposals/approved/range-patterns-char-byte-proposal.md — Range patterns on char and byte

9.0 Match Expression Syntax

Proposal: proposals/approved/match-expression-syntax-proposal.md

Documents the existing implementation of match expressions. Key specifications:

match expr { pattern -> expression, ... } syntax (comma-separated arms)
Guard syntax if condition
Pattern types: literal, binding, wildcard, variant, struct, tuple, list, range, or-pattern, at-pattern
Top-to-bottom, first-match-wins evaluation
Integer-only literal patterns (no float patterns)

Status: IMPLEMENTED — This proposal formalizes existing behavior.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (9.0) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-9.0 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 9.0: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

9.0.1 Comma-Separated Match Arms

Proposal: proposals/approved/match-arm-comma-separator-proposal.md

Changes match arm separators from newlines to commas (trailing commas optional). Also formally adopts if guard syntax replacing .match(condition). Key changes:

match_arms = [ match_arm { "," match_arm } [ "," ] ] — comma-separated
match_arm = match_pattern [ "if" expression ] "->" expression — if guards
.match() now exclusively means method-style pattern matching
Formatter allows single-line matches for short, simple arms

Status: APPROVED — Parser migration part of block-expression-syntax implementation.

Implementation

Implement: Parser — comma-separated match arms in match expr { } block syntax [done] (verified 2026-03-28)
- Rust Tests: ori_parse/src/tests/ — comma-separated arm parsing
- Ori Tests: tests/spec/patterns/match.ori — uses comma syntax throughout (62 tests) [done] (verified 2026-03-28)
Implement: Parser — if guard syntax replacing .match(condition) [done] (verified 2026-03-28)
- Rust Tests: ori_parse/src/tests/ — if guard parsing
- Ori Tests: tests/spec/patterns/match.ori — migrate guard tests from legacy .match() to if syntax HYGIENE: all spec tests still use legacy .match() syntax; only AOT tests use if (verified 2026-03-29)
Implement: Formatter — emit commas, support single-line short matches [done] (verified 2026-03-28)
- Rust Tests: ori_fmt/src/formatter/ — comma emission tests

9.1 match Expression

9.2 Pattern Types

HYGIENE (verified 2026-03-29): Each pattern type has [ ] LLVM Support + [ ] LLVM Rust Tests items that are redundant with [x] AOT Tests — LLVM codegen works through the ARC IR pipeline, not a separate path. The [ ] items below represent dedicated codegen unit tests, not missing functionality. AOT matrix is incomplete for list, at, struct (direct), variant (direct), and range patterns.

9.3 Pattern Guards

9.4 Exhaustiveness Checking

Proposal: proposals/approved/pattern-matching-exhaustiveness-proposal.md

Pattern matrix decomposition algorithm (Maranget’s algorithm) for exhaustiveness verification.

9.4.1 Core Algorithm

Actual implementation is in compiler/ori_canon/src/exhaustiveness/ (mod.rs, walk.rs, tests.rs) — NOT ori_types/src/check/exhaustiveness/ which does not exist. 45 Rust tests, all pass. (verified 2026-03-29)

Implement: Pattern matrix decomposition — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Algorithm [done] (verified 2026-03-29: implemented in ori_canon/src/exhaustiveness/ using DecisionTree walker)
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — 45 tests covering bool, int, str, list, option, result, user enum, Never, nested, redundant (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/exhaustiveness.ori — 12 tests + exhaustiveness_fail.ori — 10 compile_fail tests (verified 2026-03-29)
Implement: Constructor enumeration for types — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Algorithm [done] (verified 2026-03-29: handles Bool, Option, Result, user Enum, List, Ordering, Never)
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — type constructor tests (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/exhaustiveness.ori (verified 2026-03-29)

9.4.2 Exhaustiveness Errors

Implement: Match expressions must be exhaustive (E0123) — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Error Policy [done] (verified 2026-03-29: 8 compile_fail(“non-exhaustive”) tests + 12 positive tests)
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — exhaustiveness checking (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/exhaustiveness_fail.ori — 8 non-exhaustive compile_fail tests (verified 2026-03-29)
Implement: Let binding refutability check — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Refutability Requirements
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — refutability errors NEEDS TESTS (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/match_exhaustive.ori
Implement: Function clause exhaustiveness — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Error Policy
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — clause exhaustiveness NEEDS TESTS (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/function_clauses_exhaustive.ori

9.4.3 Guard Handling

Implement: Guards not considered for exhaustiveness — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Guards [done] (verified 2026-03-29: guard_requires_catchall test in match_patterns.ori passes)
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — guard handling (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/match_patterns.ori — guard_requires_catchall (verified 2026-03-29)
Implement: Guards require catch-all pattern (E0124) — proposals/approved/pattern-matching-exhaustiveness-proposal.md § Guards [done] (verified 2026-03-29)
- Rust Tests: ori_canon/src/exhaustiveness/tests.rs — guard catch-all requirement (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/match_patterns.ori — guard_requires_catchall (verified 2026-03-29)

9.4.4 Pattern Coverage

9.4.5 Unreachable Pattern Detection

9.5 Named Variant Pattern Fields (Argument Punning)

Proposal: proposals/approved/argument-punning-proposal.md

Allow named field syntax in variant patterns, with punning when the binding variable matches the field name: Circle(radius:) for Circle(radius: radius).

type Shape = Circle(radius: float) | Rectangle(width: float, height: float)

// Before (positional only):
match shape {
    Circle(r) -> r * r * 3.14
    Rectangle(w, h) -> w * h
}

// After (named + punned):
match shape {
    Circle(radius:) -> radius * radius * 3.14
    Rectangle(width:, height:) -> width * height
}

Parser

Implement: Support name: and name: pattern in variant pattern fields [done] (verified 2026-03-29)
- Rust Tests: ori_parse/src/grammar/pattern/tests.rs — named variant field parsing NEEDS TESTS (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/variant_punning.ori — single/multi-field punning, Option, Result [done] (verified 2026-03-29)
Implement: Mixed named and positional fields in same variant pattern [done] (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/variant_punning_mixed.ori NEEDS TESTS (verified 2026-03-29)
Implement: Positional variant patterns unchanged (no regression) [done] (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/variant_positional_regression.ori NEEDS TESTS (verified 2026-03-29)

IR

Implement: Extend variant pattern representation to support named fields [done] (verified 2026-03-29)
- Rust Tests: ori_ir/src/ast/pattern/tests.rs — named variant field IR NEEDS TESTS (verified 2026-03-29)

Type Checker

Implement: Validate named fields match variant definition [done] (verified 2026-03-29)
- Rust Tests: ori_types/src/check/ — variant field name validation NEEDS TESTS (verified 2026-03-29)
- Ori Tests: tests/compile-fail/variant_punning_unknown_field.ori NEEDS TESTS (verified 2026-03-29)
Implement: Named fields can appear in any order [done] (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/variant_punning_reorder.ori NEEDS TESTS (verified 2026-03-29)

Evaluator

Implement: Match named variant fields by name (reorder to definition order) [done] (verified 2026-03-29)
- Rust Tests: ori_eval/src/interpreter/ — named variant field matching NEEDS TESTS (verified 2026-03-29)
- Ori Tests: tests/spec/patterns/variant_punning.ori [done] (verified 2026-03-29)

LLVM

Implement: LLVM codegen for named variant field patterns (REDUNDANT — likely works via ARC IR)
- LLVM Rust Tests: ori_llvm/tests/aot/patterns.rs — named variant field codegen
- AOT Tests: No AOT coverage yet INCOMPLETE MATRIX (verified 2026-03-29)

Formatter

Implement: Detect name: name in variant patterns and emit name: form
- Rust Tests: ori_fmt/src/formatter/ — variant pattern punning canonicalization

Documentation

Implement: Update spec 10-patterns.md with named variant field patterns
Implement: Update grammar.ebnf with variant_field production
Implement: Update .claude/rules/ori-syntax.md with pattern punning syntax [partial] (verified 2026-03-29: .claude/rules/ori-syntax.md mentions punning syntax)
/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (9.5) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-9.5 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 9.5: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

9.6 Section Completion Checklist

Verification 2026-03-29: 6 implemented items were marked [ ] (now fixed to [x]). 17 stale path references fixed. 11 test gaps identified. 3 hygiene violations noted. Full test suite passes (4181 passed, 0 failed, 42 skipped). No bugs found.

All items above have all three checkboxes marked [ ] (verified 2026-03-29: NOT MET — many items still need tests)
Spec updated: spec/15-patterns.md reflects implementation (verified 2026-03-29: PARTIAL — covers patterns but not variant punning)
CLAUDE.md updated if syntax/behavior changed
80+% test coverage (verified 2026-03-29: PARTIAL — good interpreter coverage, weak AOT for struct/list/at-pattern)
Run full test suite: ./test-all.sh (verified 2026-03-29: 4181 passed, 0 failed, 42 skipped)
/tpr-review passed — independent Codex review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — implementation hygiene review clean (phase boundaries, SSOT, algorithmic DRY, naming). MUST run AFTER /tpr-review is clean.
/improve-tooling retrospective completed — MANDATORY at section close, after both reviews are clean. Reflect on the section’s debugging journey (which diagnostics/ scripts you ran, which command sequences you repeated, where you added ad-hoc dbg!/tracing calls, where output was hard to interpret) and identify any tool/log/diagnostic improvement that would have made this section materially easier OR that would help the next section touching this area. Implement every accepted improvement NOW (zero deferral) and commit each via SEPARATE /commit-push. The retrospective is mandatory even when nothing felt painful — that is exactly when blind spots accumulate. See .claude/skills/improve-tooling/SKILL.md “Retrospective Mode” for the full protocol.

Test Gaps (verified 2026-03-29)

Hygiene Violations (verified 2026-03-29)

STALE PATH (17 occurrences, FIXED): Roadmap referenced non-existent ori_types/src/check/exhaustiveness/tests.rs. Actual module at ori_canon/src/exhaustiveness/.
REDUNDANT TRACKING: Each [x] pattern has [ ] LLVM Support + [ ] LLVM Rust Tests AND [x] AOT Tests pointing at same functionality. LLVM codegen works via ARC IR pipeline, not separate path.
LEGACY SYNTAX IN SPEC TESTS: All guard tests in Ori spec files use .match(condition) syntax; approved if syntax only tested in AOT Rust tests.

Incomplete AOT Matrix (verified 2026-03-29)

Feature	Interpreter	AOT	Gap
List patterns	5+ tests	None	AOT gap
At-patterns	2 tests	None	AOT gap
Struct patterns	5+ tests	Indirect only	AOT gap
Variant patterns (direct)	5+ tests	Indirect only (tag check)	AOT gap
Range patterns (int)	2 tests	None	AOT gap
Named variant fields	5 tests	None	AOT gap

Exit Criteria: Match expressions work like spec

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (9.6) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-9.6 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 9.6: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

Verification Notes

6 items marked [ ] were actually implemented (exhaustiveness) — fixed to [x].
CRITICAL: 17 stale path references fixed (ori_types/src/check/exhaustiveness/ -> ori_canon/src/exhaustiveness/).
Redundant LLVM Support/LLVM Rust Tests items noted (work via ARC IR pipeline, covered by AOT Tests).
11 test gaps identified. Incomplete AOT matrix for list/struct/at/variant/range/named-field patterns.
3 hygiene violations: stale paths (fixed), redundant LLVM items (noted), legacy guard syntax in spec tests.
Verified by: Claude Opus 4.6 (1M context)