[ranjeet150]

Summary of Changes

Events are a public interface. Once an indexer, export pipeline, or partner consumes them, altering a topic or reordering a data payload silently breaks downstream consumers without compile-time warnings.

This PR implements event schema versioning, documents the complete catalogue, establishes evolution and compatibility policies, and adds exact shape assertion regression tests.

Key Changes

1. Schema Versioning Across All Events:

   • Defined pub const EVENT_SCHEMA_VERSION: u32 = 1; in audit-registry, payment-router, and usage-meter.
   • Added #[topic] pub version: u32 as the leading topic across every event topic tuple:
     • audit-registry: CallerAllowed, CallerRevoked, AttestationRecorded, AttestationSuperseded
     • payment-router: EscrowOpened, PartialReleased, Claimed, Disputed, DisputeResolved, EscrowClosed, SettlementFailed, SettlementRecovered, DeadLettered
     • usage-meter: RegistrySet, PolicySet, UsageRecorded
   • Updated all event emission sites to supply version: EVENT_SCHEMA_VERSION.

2. Event Catalogue & Compatibility Specification:

   • Created docs/event-catalogue.md containing the complete catalogue: event name, emitting entrypoint, topic tuple, and detailed data payload layout with types and field descriptions.
   • Documented the schema evolution and compatibility policy: additive changes only within a version, version increment on breaking changes, dual-emission during migration windows, and test shape enforcement.
   • Linked catalogue documentation in README.md.

3. Automated Generator Script:

   • Added scripts/generate_event_catalogue.py to parse #[contractevent] definitions from Rust code and verify or regenerate documentation with --check flag for CI integration.

4. Exact Shape Assertion Regression Tests:

   • Added dedicated test_event_shapes_and_versioning suites in each crate (audit-registry/src/test.rs, payment-router/src/test.rs, usage-meter/src/test.rs).
   • Asserts exact event XDR shape, contract address, topics layout, and payload fields across all 16 contract events.

Closes #78