Event-first capability composition: productize governed events across registry, runtime, and reference apps

[enricopiovesan]

Summary

Treat governed events and observable runtime delivery as a release-blocking product capability. No new capability-generation or reference-app-generation work may proceed until the event-first architecture gate is approved.

Problem

Traverse has event contracts, publish/subscribe enforcement, workflow event edges, and example fixtures, but no published event-driven capability bundle, catalog-level event relationship discovery, or reference-app proof.

Definition of Done

• Approved successor spec and ADR define event-first capability composition across registry, runtime, and apps.
• Published registry index represents event contracts and publisher/subscriber capability edges.
• Runtime conformance proves declared capability events publish, subscribe, and drive approved workflow transitions through the observable boundary.
• One released reference app demonstrates a real event-driven capability flow and observable event evidence.
• Capability pages expose governed Emits and Consumes relationships; catalog graph work is scoped by evidence.
• Child full-DoD tickets cover registry indexing (Implement ECCA registry catalog and capability discovery #896), runtime conformance (Implement ECCA runtime validation, lineage, and conformance #897), reference-app proof (Build ECCA three-capability reference-app conformance journey #898), and UI/catalog discovery (Spec: production SSE reads from EventBroker #964, Migrate production SSE endpoint from AppStateEventRecord to EventBroker #965, ADR + spec: WebSocket and gRPC as the governed runtime event transport #966, Implement WebSocket runtime event transport, retire SSE #967, Implement gRPC runtime event transport #968; deferred follow-up Revisit merging browser_adapter.rs into the production HTTP API #973).
• Existing generation work is explicitly gated on this approved architecture.

Validation

Published-index fixture, runtime/event conformance suite, reference-app end-to-end scenario, and browser/catalog evidence.

Non-goals

Replacing event contracts with an ad hoc message bus, inventing a second event model, or building a speculative graph without published event-driven data.

[enricopiovesan]

ECCA grounding complete — 2026-07-29

The governing premise is revised: this is not a UI-only Emits/Consumes gap, nor a requirement for generic lifecycle telemetry to substitute for domain events. Traverse must treat meaningful asynchronous domain events as first-class event products: versioned payload plus semantic purpose, owning steward, lifecycle, classification/exposure, compatibility policy, producer/consumer relationships, publish-time policy validation, and runtime adherence/lineage feedback. The registry catalog and capability page are the discovery surface; the runtime is the enforcement and observable evidence plane. The implementation must preserve federated domain ownership on shared platform standards and support progressive maturity rather than claiming complete ECCA at once.

Generation gate: no new capability or reference-app generation/publication until this governing decision is approved and its dependent tickets exist.

[enricopiovesan]

Decision 1 approved — mandatory, standardized, validated event products.

For every capability with externally meaningful asynchronous effects, Traverse requires declaration of governed domain-event contracts. Generic runtime lifecycle telemetry remains a distinct observability plane and cannot satisfy this rule.

This is a shared Traverse standard, not producer discretion. The governing specification and ADR must define the required contract fields, semantic naming rules, ownership/stewardship, lifecycle and exposure/classification taxonomy, versioning and compatibility policy, producer/consumer declarations, validation behavior, and acceptance tests. Registry publication and runtime use must reject non-compliant contracts before they become discoverable or executable.

[enricopiovesan]

Decision 2 approved — canonical standard.

Each governed Traverse domain event uses a CloudEvents-compatible envelope for portable transport identity plus a strict Traverse event-governance descriptor. The descriptor is the canonical source for required semantics and governance: event identity/version, payload schema, purpose, owner/steward, domain, lifecycle, exposure/classification, compatibility policy, producer/consumer declarations, and catalog relationships.

Validation occurs at authoring, registry publication, and runtime producer/consumer boundaries. Raw CloudEvents alone and AsyncAPI alone are insufficient; AsyncAPI may be generated as a discovery/export view, not the sole contract authority.

[enricopiovesan]

Decision 3 approved — enforcement rollout.

Effective immediately, publication of every new Traverse event contract is blocked unless its schema and required governance descriptor pass machine validation. Runtime starts in an explicit, instrumented migration mode: it reports declared-vs-observed violations, undeclared event use, consumer relationships, and lineage without yet rejecting legacy gaps. The governing spec must define a measurable migration exit criterion and a documented cutover after which runtime producer/consumer boundaries reject non-compliant events. Warning-only publication is prohibited.

[enricopiovesan]

Decision 4 approved — immutable evolution.

Published event-contract versions are immutable. Backward-compatible schema additions use a new minor version; breaking schema or semantic changes require a new major version. Every deprecated version must declare its replacement and retirement date. The catalog must preserve version lineage, and validation must reject in-place modification, invalid version progression, or a deprecated contract lacking a migration path.

[enricopiovesan]

Decision 5 approved — controlled classification and exposure taxonomy.

Every event descriptor must declare exactly one exposure class: public, partner, internal, or restricted. Every payload field must declare a data class where applicable: none, personal, sensitive, or regulated. Free-form classifications do not satisfy the standard. Publish-time and runtime policy use these values to govern catalog visibility, access, validation/audit scope, telemetry, and external sharing.

[enricopiovesan]

Decision 6 approved — declared relationships plus observed lineage.

The catalog records declared producer and consumer relationships from capability descriptors separately from observed runtime publisher/subscriber lineage. It must render both, identify mismatches, and retain the evidence used for impact analysis. Publish-time validation uses declared intent; migration telemetry detects undocumented producers/consumers and contract drift; the post-migration runtime cutover enforces the defined alignment policy.

[enricopiovesan]

Decision 7 approved — federated stewardship.

Each event product is owned by the domain/team that owns its producing capability. Its descriptor must contain the accountable owner and a stable support/contact route. Traverse platform owns the shared schema, taxonomy, policy engine, registry/catalog, and validation tooling; it does not become the owner of domain-event semantics. Individual developer identity alone is insufficient.

[enricopiovesan]

Decision 8 approved — semantic event naming.

A governed Traverse domain event must use a canonical past-tense domain-fact type in the form domain.entity.occurred (or an approved equivalent fact verb), with a concise purpose statement. Commands, requests, and generic runtime lifecycle telemetry are separate contract kinds and may not be cataloged as domain events. Publish-time validation enforces identifier grammar, required purpose, and contract-kind distinction.

[enricopiovesan]

Decision 9 approved — canonical payload schema.

Every governed Traverse event payload is authored and validated as JSON Schema. Generated language bindings and AsyncAPI artifacts are derived views, not competing sources of truth. The standard must define JSON Schema version/profile, schema identifier/version linkage, field descriptions, and required field-level classification metadata. Publication rejects another payload-schema language as the governing source.