typed error taxonomy with exhaustive negative-path tests for settlement

[mikewheeleer]

Summary

settlement returns generic or panicking failures, so callers can't distinguish causes and some rejections are untested. Introduce a typed error enum and cover every negative path.

Why this matters

Untyped failures and untested rejections hide bugs and confuse integrators. A typed taxonomy + negative tests is correctness insurance.

Requirements

• Define/extend a typed error enum covering each settlement failure with a stable code.
• Replace generic failures/panics with the typed errors.
• Add tests asserting each guarded entrypoint returns the right error.
• Document the codes and when they fire.

Technical guidance

• Give each variant a unique, stable discriminant.
• Assert the exact error in tests, not just failure.

Edge cases — each must have a test

• each guard -> its specific typed error
• invalid input -> correct code
• unauthorized -> correct code
• no path panics
• codes are stable and documented

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Error message localization
• Off-chain error mapping

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.