Allow payload-sensitive helper match dispatch

[beardedeagle]

Summary

• Allow source helper whole-body matches and helper return-match expressions to split one top-level enum constructor when nested typed enum payload predicates are provably disjoint.
• Resolve helper match candidates by checking concrete source payloads against typed guards before binding nested values.
• Preserve wildcard fallback behavior and fail closed for duplicate, overlapping, not-provably-disjoint, and uncovered payload shapes.
• Keep same-message step signature and process match-msg payload splitting rejected.
• Document the helper-only semantics and diagnostics.

Boundary

• This is a Strata checker/source-helper change.
• Mantle artifact schema, lowering, loaded runtime IDs, and runtime transition lookup are unchanged.
• Nested predicate comparison uses checked type and variant identity; source names remain diagnostic and documentation text only.
• No executable source-string selector lowering is added.
• Strata source values remain immutable whole values resolved before lowering.

Tests

• cargo +stable fmt --all --check
• cargo +stable test -p strata nested_pattern_destructuring --lib
• cargo +stable clippy --workspace --all-targets -- -D warnings
• just quality
• just performance-smoke
• just docs
• git diff --check
• pre-commit hook: clippy and fmt-check
• pre-push hook: ci-native

[Copilot]

Pull request overview

This PR extends Strata’s source helper match dispatch to allow repeating the same top-level enum constructor when the nested typed-enum payload predicates are provably disjoint, enabling payload-sensitive helper dispatch at checker/expansion time (without changing lowering or the Mantle artifact/runtime behavior).

Changes:

• Add payload-sensitive match-arm validation that permits same-constructor repeats only when nested typed-enum guards are disjoint, and rejects overlaps/duplicates.
• Update helper expansion (match + return match) to select arms by testing the concrete nested payload against typed guards before binding nested values; improve “no matching pattern” diagnostics.
• Document the helper-only semantics and add tests covering accepted splits and rejected overlaps/uncovered shapes (while ensuring process step/message dispatch behavior is unchanged).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Documents helper-only constructor splitting based on provably-disjoint nested predicates.
docs/src/syntax-reference.md	Notes helper match/return-match support for splitting by disjoint nested enum predicates.
docs/src/language-reference.md	Adds a worked example and clarifies the allowed/rejected cases for helper-only splitting.
docs/src/diagnostics.md	Adds diagnostics entries for overlap rejection and expansion-time “no matching pattern” failures.
crates/strata/src/language/tests/nested_pattern_destructuring.rs	Adds coverage for accepted helper dispatch splitting and expected rejection/diagnostics for overlaps and uncovered payload shapes.
crates/strata/src/language/checker/source_functions/values/return_matches.rs	Uses payload-sensitive arm checking for helper return-match validation.
crates/strata/src/language/checker/source_functions/value_resolution/return_matches.rs	Updates expansion-time return-match arm selection to filter by payload guard prior to binding; improves diagnostics.
crates/strata/src/language/checker/source_functions/value_resolution/body_matches.rs	Updates expansion-time whole-body helper match arm selection similarly (guard check before binding) and improves diagnostics.
crates/strata/src/language/checker/source_functions/match_bodies.rs	Uses payload-sensitive arm checking for helper whole-body match validation.
crates/strata/src/language/checker.rs	Introduces payload-sensitive typed arm validation, disjointness checking for nested guards, and source-payload guard matching helper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.