docs: structured events index across contracts

[obswrld]

Summary

Closes #487

Defines a stable topic structure for events across settlement, revenue_pool, and vault, documents every emitted event, adds a CI gate enforcing event-shape discipline, and defines a backwards-compatibility ladder for migrating events toward the target shape over time.

Changes

docs/EVENTS_INDEX.md (new)

• Defines the target topic structure: Topic1=contract, Topic2=action, Topic3=subject
• Documents the current state (every event today uses a 2-topic shape: action + subject) and explains why a wholesale rewrite of all 39 publish call sites isn't done in this PR
• Defines a 3-stage backwards-compat ladder: Stage 0 (current) → Stage 1 (dual-publish, opt-in per event) → Stage 2 (cutover, breaking change called out explicitly)
• Lists every event across all three contracts in per-contract tables (action, constructor, subject, data payload)
• Includes a checklist for adding new events going forward

scripts/check-event-shape.sh (new)

• CI grep gate that fails if any events().publish() call site uses a raw inline Symbol::new(...) topic literal instead of a centralized events::event_*() constructor
• Verified to pass cleanly (0 violations) after fixes below
• Manually verified it correctly fails when a violation is reintroduced (tested and reverted)

Drift fixes found and fixed via the new gate

While building the gate, it surfaced two real violations already in the codebase:

• contracts/settlement: force_credit_developer and upgrade used inline Symbol::new(&env, "developer_force_credited") / "upgraded" instead of centralized constructors. Added event_developer_force_credited() and event_upgraded() to events.rs with matching byte-identity snapshot tests; updated call sites.
• contracts/vault: prune_request_ids used an inline Symbol::new(&env, "request_id_pruned"). Added event_request_id_pruned() to events.rs with a matching snapshot test; updated call site.

Pre-existing build issue (out of scope)

contracts/settlement and contracts/vault have pre-existing compile errors on main, unrelated to this change:

• Missing Severity/String/AdminBroadcast types referenced by an admin broadcast function
• Argument mismatches in unrelated withdraw_developer_balance test calls
• Missing Box imports in test_invariant.rs

Verified via git stash comparison that these exist on main independently of this branch. Not fixed here as out of scope for this issue — flagging for maintainer awareness since they block cargo test for the whole crate.

Acceptance Criteria

• Doc shipped (docs/EVENTS_INDEX.md)
• CI gate works (scripts/check-event-shape.sh, tested pass + fail cases)
• Shape enforced (centralized event_*() constructors required, no inline literals)
• Ladder defined (Stage 0 → 1 → 2 backwards-compat migration path)