Document ID: GOS-80-CHAIN-KAFKA-SCHEMAS Version: 0.1.0 Status: DRAFT Owner Role: CHAIN_OFFICER Last Review Date: 2026-03-04 Next Review Date: 2026-04-04

Topics and Schema Files

• milestone.approved -> milestone.approved.schema.json
• mint.requested -> mint.requested.schema.json
• mint.confirmed -> mint.confirmed.schema.json
• anchor.requested -> anchor.requested.schema.json
• anchor.confirmed -> anchor.confirmed.schema.json
• orchestration.dlq -> orchestration.dlq.schema.json
• kes.orchestrator.events -> kes.orchestrator.events.schema.json
• kes.orchestrator.domain-events -> kes.orchestrator.domain-events.schema.json

Envelope Convention

All schemas use:

• schemaVersion
• eventType
• eventVersion
• eventId
• occurredAt
• intentId
• producer
• payload

Partitioning Rule

Partition key must be intentId for all orchestration topics.

Compatibility Rule

Use additive-only evolution for payload objects. Do not remove required envelope fields.

Schema Compatibility Sign-Off

• Sign-Off Date: 2026-03-04
• Scope: milestone.approved, mint.requested, mint.confirmed, anchor.requested, anchor.confirmed, orchestration.dlq
• Decision: APPROVED for v1.0.0 baseline contracts
• Rule Lock:
  • Envelope required fields remain mandatory (schemaVersion, eventId, occurredAt, intentId, producer, payload)
  • Payload evolution is additive-only unless major version bump
  • Partition-key policy remains key = intentId
• Approval Authority: CHAIN_OFFICER
• Next Compatibility Review: 2026-04-04 or before any non-additive schema proposal

TypeScript DTO and Partition Key Helper

• DTOs: ../../packages/financial-layer/chain/orchestration/kafka-dto.ts
• Partition-key enforcement: ../../packages/financial-layer/chain/orchestration/partition-key.ts
• KafkaJS transport adapter: ../../packages/financial-layer/chain/orchestration/kafka-kafkajs.ts

Use buildKafkaRecordInput or resolveIntentPartitionKey so all produced events keep key=intentId.

KES Orchestrator Topic Contract

Topic: kes.orchestrator.events

• Producer path: services/api/src/routes/kes-orchestrator.ts
• Emission mode: optional, enabled by KES_ORCHESTRATOR_KAFKA_ENABLED=true
• Keying rule: intentId resolved from x-intent-id, body.intentId, case/payment id fallback
• Contract file: kes.orchestrator.events.schema.json