system-prompts-and-models-of-ai-tools/docs/governance/events-and-schema.md

Events, contracts, and schema governance

Canonical: MASTER_OPERATING_PROMPT.md.

Principles

• Do not rely on ad hoc string event names alone without documentation and versioning.
• Prefer CloudEvents-style envelopes for cross-service and async boundaries.
• Validate payloads with JSON Schema at publish and/or consume boundaries where feasible.
• Document channels (queues, HTTP callbacks, WebSockets) with AsyncAPI or equivalent when multiple consumers exist.
• Maintain a single source of truth for schema versions (registry, repo folder, or generated artifacts — pick one path; avoid two overlapping catalogs without justification).

Minimum envelope fields

Every published event should minimally support traceability and policy classification:

• event_id
• event_type
• spec_version
• schema_version
• tenant_id
• entity_id
• correlation_id
• causation_id
• source
• actor_type (see approval-policy.md)
• approval_class, reversibility_class, sensitivity_class (where the event represents or precedes a governed action)
• trace_id
• timestamp (ISO-8601, explicit timezone)

Drift and breaking changes

• No silent schema drift — version bumps must be visible in code, registry, or changelog.
• No silent breaking changes — consumers must be updated or compatibility shims documented.
• Deprecation windows and dual-read/dual-write phases belong in the execution plane plan, not in prompt text.

Dealix alignment

When adding new integration or workflow events, align names and payloads with existing backend patterns and tenant isolation (tenant_id). Prefer explicit correlation IDs through agent and API paths for observability.

See also: connectors-and-data-plane.md, trust-fabric.md.