Define and enforce Zn symmetry input-validation semantics

[yingjerkao]

The current Zn symmetry API has mixed semantics around valid quantum numbers.

Current behavior

• check_qnum and check_qnums define valid Zn qnums as canonical values in [0, n)
• Bond construction enforces that same canonical range
• but the public arithmetic API (combine_rule / reverse_rule) historically accepts wider integer inputs instead of rejecting out-of-range values first

This means the API currently mixes two models:

1. Zn qnums are canonical representatives in [0, n)
2. Zn qnums are arbitrary integers modulo n

PR #768 fixes the narrower correctness bug that public arithmetic should return canonical outputs in [0, n), but it does not change the broader input policy.

Follow-up question

Decide whether the public Zn arithmetic API should:

• continue accepting wider integer inputs and normalize internally, or
• reject out-of-range Zn inputs as invalid API usage

Why this needs a separate issue

• changing input rejection would be a behavior change, not just a bug fix
• it may affect existing call sites that currently rely on modulo-style inputs
• the decision should be applied consistently across check_qnum, combine_rule, reverse_rule, and Bond-facing APIs

Likely work if rejection is chosen

• audit current call sites for out-of-range Zn inputs
• decide whether scalar and vector overloads should both reject
• add explicit tests for accepted vs rejected Zn inputs
• document the intended Zn API contract clearly

[yingjerkao]

I inspected the current ZnSymmetry implementation, the Bond validation path, and PR #768.

The inconsistency described here is real:

• Bond construction already rejects non-canonical Zn qnums via check_qnum
• but the public Zn arithmetic API (combine_rule / reverse_rule) still accepts out-of-range inputs and normalizes them internally

My recommendation is to make Zn consistently canonical everywhere and reject invalid public inputs rather than normalizing them silently.

Why this direction makes sense:

• it matches the existing check_qnum and Bond contract instead of preserving two different semantics for the same qnum type
• it makes invalid caller behavior fail at the API boundary instead of being hidden by modulo arithmetic
• it avoids subtle bugs where user code passes -1 or n + 1 and gets a valid-looking result that could never have existed in a Bond

Concretely, I would propose:

• add input validation at the start of both ZnSymmetry::combine_rule_ overloads and ZnSymmetry::reverse_rule_
• reject any scalar input not satisfying check_qnum
• reject any vector input where either side contains a non-canonical qnum
• keep PR Normalize ZnSymmetry outputs into valid qnums #768’s canonical output normalization logic, but make it apply only after valid inputs are confirmed
• add tests covering accepted canonical inputs and rejected out-of-range scalar/vector inputs

The tradeoff is compatibility: this would be a behavior change for any caller currently relying on modulo-style inputs. But from an API design perspective, I think the stricter contract is the cleaner and more defensible choice because it aligns public arithmetic with the existing Bond-facing semantics instead of keeping the ambiguity alive.