Create EVENT_SCHEMA.md

[karanjakevin39-collab]

Summary

Adds docs/EVENT_SCHEMA.md, a structured reference documenting every event
emitted by the predictify-hybrid contract: topic (Soroban Symbol key),
full payload schema, and a stability guarantee per event.

Closes #837

What's covered

• 65 events organized into 9 domains: Market Lifecycle, Voting & Betting,
  Oracle, Dispute & Governance, Fees & Treasury, Admin/Config/Access Control,
  Upgrade & Storage, Monitoring/Errors/Diagnostics, and Unstable
  tuple-payload events.
• Every event's on-chain topic tuple and full field-by-field schema
  (field: type, with notes where the meaning isn't obvious from the name).
• A stability legend (🟢 stable struct / 🟡 stable-but-duplicated / 🔴
  unstable tuple payload) so indexers and frontend consumers know what they
  can safely build against.
• The historical/archive query surface (event_archive.rs) — pagination,
  cursors, EventHistoryEntry shape, and the archive size cap — documented
  as the counterpart to the live event stream.
• A stability policy section: stable events are additive-only; breaking
  changes require a documented notice and version bump.

Notable findings (flagged in the doc, not fixed here)

While going through events.rs to build this, I found a few things worth a
maintainer's attention. Left them documented inline as call-outs rather than
changing behavior, since that's out of scope for a docs-only issue:

1. Duplicate untyped emitters. emit_oracle_callback, emit_security_event,
   emit_oracle_degradation, and emit_manual_resolution_required each exist
   as both a typed EventEmitter::emit_* method (struct payload, scoped topic)
   and a free function of the same purpose that publishes a raw tuple under a
   differently-named topic (e.g. "oracle_degradation" vs "ora_deg"). The
   tuple versions have no named schema and are candidates for deprecation.
2. AdminPermissionEvent is dead code. The struct is defined but has no
   corresponding EventEmitter::emit_* method — nothing ever publishes it.
3. CircuitBreakerEvent never gets a scoped topic. Every other event
   publishes under (event_name_symbol, some_scoped_id), but circuit breaker
   events only go out under the flat ("cb_event",) topic via store_event's
   internal publish — consumers filtering by a second topic element will miss
   these entirely.
4. ResolutionTimeoutEvent has no emission timestamp field, unlike every
   other event in the file — timeout_timestamp is the only time reference.

Happy to open follow-up issues for any of these if useful.

Testing

This is a documentation-only change (no contract logic touched). Added
test_event_schema_doc_covers_all_event_structs in
event_creation_tests.rs, a source-scan test that fails CI if a future
pub struct *Event is added to events.rs without a corresponding entry in
EVENT_SCHEMA.md, so the doc can't silently drift out of sync.

• cargo test passes
• cargo clippy clean
• No unwrap() / no state-changing code touched (docs + one test only)

Checklist

• Implementation matches issue description
• Tests added and passing
• Docs added (docs/EVENT_SCHEMA.md)
• Follows repo lint/style conventions

[drips-wave]

@karanjakevin39-collab Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[greatest0fallt1me]

LGTM ✅ nice iteration. Thanks!