feat(events): add event versioning fixtures, decoder, and dead-letter queue (#246)

[s6pa1rta3n-lab]

Summary

Closes #246.

This PR establishes event versioning fixtures, deterministic schema decoders, a dead-letter quarantine pipeline, and upgrade documentation for PromptHash contract events.

Key Changes

• Canonical Event Versioning & Types: Defined canonical typed representations (CanonicalPublishEvent, CanonicalPurchaseEvent, CanonicalUnlockEvent), DeadLetterRecord, and DecodeResult in server/src/types/eventVersioning.ts.
• Contract Event Support (unlock_prompt): Added unlock_prompt entrypoint and PromptUnlocked event emitter with authorization validation (require_auth()) and access check enforcement in contracts/prompt-hash/src/contract.rs, events.rs, and types.rs.
• Comprehensive Fixture Catalog: Created versioned event fixtures in contracts/fixtures/events/ and server/src/fixtures/events/ covering supported schemas (v1 and v2 for publish, purchase, unlock) and failure cases (unknown_topic, invalid_version, malformed_payload), linked via manifest.json.
• Deterministic Event Decoder (eventDecoder.ts):
  • Automatically identifies schema version from topic tokens (v1, v2, etc.) and payload fields with fallback to baseline version 1.
  • Deterministically transforms raw contract event topics and payloads into strongly-typed canonical events.
  • Converts Stroops to XLM using integer math and validates address/scalar constraints.
• Dead-Letter Queue (DeadLetterQueueService & DeadLetterEvent):
  • Captures failed events safely without throwing exceptions or interrupting the indexing loop.
  • Classifies failures into UNKNOWN_EVENT_TYPE, UNSUPPORTED_VERSION, SCHEMA_VALIDATION_FAILED, and CORRUPT_PAYLOAD.
  • Persists quarantined events in MongoDB with an in-memory ring-buffer fallback.
• Indexer Integration (indexer.ts): Integrated deterministic decoding and quarantine routing into processEvent for PromptCreated, PromptPurchased, and PromptUnlocked.
• Specification and Upgrade Runbook: Authored docs/event-versioning.md detailing event schemas, type mapping, error codes, DLQ querying, and step-by-step instructions for deploying new event versions.
• Test Coverage:
  • All 113 Soroban contract tests pass (cargo test).
  • Added 16 unit and fixture tests across server/src/tests/eventDecoder.test.ts and server/tests/eventDecoder.test.ts.
  • All 23 server test suites (208 tests) pass with zero errors.

Payout Routing

• EVM (Base/Arbitrum/Polygon/ETH): 0xF46C9F6d70C50BF81ef3588AB523a90a594a2F89
• Stellar: GCL6OXAMLD75BMTINA6EMRUDWK5THQUSHMYNLSNBCJAPZJHNYJTUNIBC