[woahwhattheheck]

Summary

Implements the server-side Option B from #28 while the score-registry deployment in #16 is unresolved.

• add a public wallet-tier gate endpoint with an A/B/C minimum tier
• reuse the existing on-chain score read and canonical tier mapping; no duplicate scoring logic
• fail closed for missing, unattested, expired, or malformed on-chain tier data
• preserve valid_until=0 as the score-registry no-expiry sentinel
• add focused tier-gate coverage for allowed, below-threshold, malformed, unattested, expired, and no-expiry records
• exercise the existing withMockContractId resolution path used by the gatekeeper's Soroban reads
• document the protocol integration flow and mock score-registry path

Closes #28

Acceptance traceability

Requirement	Current implementation
Public minimum-tier precheck	`GET /api/user/:wallet/tier?minTier=A
Reuse canonical score authority	readOnChainScore + existing tier-code mapping
Fail closed when score is unavailable	HTTP 503 before tier evaluation
Reject default/unattested score	updatedAt <= 0 fails freshness
Reject expired attestation	nonzero validUntil < now fails freshness
Preserve explicit no-expiry records	validUntil === 0 remains fresh
Mock registry path	focused test drives withMockContractId through getContractConfig
Malformed contract tier	canonical mapping normalizes to REJECTED

Validation boundary

Current exact head: a4a2a11. Current carrier: 5 commits / 6 issue-scoped files / +316 -4 against main@6e5373acd718a1e2af41e60a57742df69dc09a15.

CI run 37430678216: action_required

This description records current GitHub workflow state; it does not claim a local/full-suite pass or a hosted-CI green result. The submitted source and focused tier-gate regression coverage remain available for maintainer review.