Replace panic! strings with a #[contracterror] StreamError enum for stable client handling

[greatest0fallt1me]

Description

Every failure path in the contract is a bare panic! with a string literal — "rate and balance must be positive" (src/lib.rs:114/:247), "stream already active" (src/lib.rs:279), "stream not active" (src/lib.rs:304), "batch too large" (src/lib.rs:352), "rate increase exceeds 10% limit" (src/lib.rs:586), "stream not found" (src/stream.rs:62), and more. docs/error-codes.md catalogues these strings and explicitly notes that a v1.0 plan in docs/audit-readiness.md proposes migrating to #[contracterror] enums. This issue performs that migration so off-chain clients can match on stable numeric codes instead of brittle strings.

Requirements and context

Functional

• Define #[contracterror] #[derive(Copy, Clone, ...)] #[repr(u32)] pub enum StreamError { ... } with one variant per documented failure in docs/error-codes.md (e.g. NotFound = 1, IdOverflow = 2, NonPositiveRateOrBalance = 3, AlreadyActive = 4, NotActive = 5, BatchTooLarge = 6, RateIncreaseTooLarge = 7, Unsettled = 8, Unclaimed = 9, MemoTooLong = 10).
• Convert entry points to return Result<T, StreamError> (or panic_with_error!) instead of panic!, preserving the existing trigger conditions exactly so semantics are unchanged.
• Keep the numeric codes stable and documented; the enum discriminants become the contract’s public error ABI.

Non-functional / repo conventions

• Update the inline #[should_panic(expected = "...")] tests (e.g. test_stop_stream_inactive_panics at src/lib.rs:793, test_update_rate_large_increase_panics at src/lib.rs:1391) to assert on the error variant via the generated try_* client methods rather than panic strings.
• Stay within the WASM size budget (scripts/check-wasm-size.sh); a small enum is cheaper than many distinct string literals.

Acceptance criteria

• StreamError enum defined with stable discriminants covering every row of docs/error-codes.md.
• All panic!("...") call sites in src/lib.rs and src/stream.rs replaced with the enum.
• Existing failure tests rewritten to assert error variants (no reliance on string matching).
• docs/error-codes.md updated to map each panic string to its new numeric code.
• cargo test and cargo clippy ... -D warnings pass.

Suggested execution

1. Fork the repo and create a branch — git checkout -b improvement/contracterror-enum.

2. Implement changes — add StreamError (new src/error.rs re-exported from lib.rs, or inline), convert entry points and src/stream.rs:62.

3. Write/extend tests — convert #[should_panic] tests to try_*-based assertions on Err(StreamError::...).

4. Test and commit

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --features testutils
./scripts/check-wasm-size.sh

Example commit message

refactor(errors): migrate panic strings to #[contracterror] StreamError enum

Guidelines

• Target 95% line coverage (docs/coverage.sh).
• Add /// doc-comments per variant and rewrite docs/error-codes.md (string → code table); cross-link docs/audit-readiness.md.
• Timeframe: 96 hours.