Event Contracts

Versioned event contracts live in contracts/events/. They define cross-service handoffs; services must not read another service database.

Authoritative files:

• contracts/events/README.md
• contracts/events/envelope.schema.json
• contracts/events/search.projection.changed.v1.schema.json

Core Rules

• Every event uses the shared envelope schema.
• Consumers persist source event identity so replay is idempotent.
• Payment, billing, wallet, and usage remain separate owners: payment-service emits payment outcomes, billing-service owns subscriptions and entitlements, wallet-service owns AZ Credit ledger mutations, and usage-service materializes quota/feature-gate snapshots.
• IAM owns permission-bearing organization membership events; organization services keep read models only.
• search.projection.changed.v1 carries copied-index updates only. Its owner sourceVersion prevents out-of-order events from overwriting a newer index row or resurrecting a delete tombstone; it does not transfer canonical data ownership to search-service. Question Bank has an opt-in JetStream publisher and Search has a matching opt-in subscriber on SEARCH_PROJECTIONS / search.projection.changed.v1; both are disabled by default. Course, exam, and document still use pull rebuilds until their owner outbox and replay proof are added.

Monetization Chain

The current monetization handoff is:

1. payment.order.paid.v1 from payment-service.
2. billing.subscription.activated.v1 from billing-service.
3. billing.entitlements.updated.v1 from billing-service.
4. Wallet consumes top-up and subscription-credit events.
5. Usage consumes entitlement snapshots.

Broker mode uses NATS JetStream stream MONETIZATION with subjects monetization.payment.order.paid.v1, monetization.billing.entitlements.updated.v1, and monetization.billing.subscription.activated.v1. Payment and billing publishers are opt-in; HTTP event endpoints remain fallback until wallet/usage subscribers and route rollback evidence exist.

Verification:

make test-monetization-event-chain
make test-monetization-routes

Public wallet, payment hook, subscription, and quota routes stay legacy until a route rehearsal, browser/runtime proof, and rollback notes exist.