Contract matchmaking-queue: add queue health snapshot and estimated wait-band accessor

[CMI-James]

Background

Game matchmaking surfaces need a simple way to show current queue health and rough wait expectations without replaying queue events off-chain.

Feature Focus

Add queue health and wait-band accessors to the matchmaking queue contract.

Where to Implement (Exact Targets)

• contracts/matchmaking-queue/src/lib.rs
• contracts/matchmaking-queue/src/storage.rs
• contracts/matchmaking-queue/src/types.rs
• contracts/matchmaking-queue/src/test.rs

What to Implement

• Add a health snapshot accessor that returns queue size, active buckets, and recent match throughput indicators.
• Add an estimated wait-band accessor that maps current queue conditions to coarse wait ranges.
• Make outputs stable and conservative so clients are not promising exact matchmaking times.
• Preserve current queue mutation paths and storage invariants.

Interface / Endpoint / Method Details

• Return structured status payloads with explicit fields for queue counts and wait bands.
• Reuse available queue metadata and derive only lightweight aggregates inside the read path.
• Document fallback output when there is not enough history to estimate waits.

Acceptance Criteria

• Frontend can show queue status and a safe wait estimate without off-chain aggregation.
• Missing or low-signal conditions return predictable fallback values.
• Accessors remain read-only and backward compatible.

Required Tests

• Unit tests for empty queue, active queue, and insufficient-history estimate scenarios.
• Assertions for throughput bucket handling and wait-band selection.

Definition of Done

• Queue health accessors are implemented and tested.
• Contract docs and public interface output are updated.

[Ogstevyn]

@Ogstevyn has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

i would love to resolve this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ogstevyn to this issue.