Skip to content

CONCEPT Cited by 1 source

contract.yaml as bus surface

Definition

contract.yaml as bus surface is the OmniNode discipline of making each node ship a YAML manifest that owns the node's event-bus surface — the explicit list of topics it consumes and produces. The manifest is the single reviewed location where wire-format topic names appear; the runtime, CI, and provisioning layers all read from it.

event_bus:
  subscribe_topics:
    - "onex.cmd.router.route-request.v1"
    - "onex.evt.router.scoring-decision.v1"
  publish_topics:
    - "onex.evt.router.routing-complete.v1"
    - "onex.evt.router.routing-failed.v1"

"The contract owns the node's bus surface… The contract becomes the only reviewed location where wire-format topic names live. There is no second operator-maintained registry, separate constant list hidden inside the runtime, or manually synchronized provisioning config. If a node wants the system to provision and validate a topic, it must put the topic name in its contract." — Source: sources/2026-06-02-redpanda-how-omninode-uses-redpanda-to-scale-ai-agent-workflows

Why a manifest, not code constants

Before the contract discipline, OmniNode's topic names "lived wherever a developer put them. That included constants near publishers, strings inside consumer configs, and sometimes a shared module if someone remembered." This produced two pathologies:

  1. No single review surface — adding a new topic touched different files in different repos; no PR reviewer saw the union.
  2. Multiple sources of truth — the constant near the publisher and the string in the consumer config could drift independently, producing silent wiring failures.

A YAML manifest moves the topic name into a specific, named, schema-validated location that: - A linter / extractor can parse mechanically. - A PR reviewer knows to look at when reviewing bus-surface changes. - The runtime / CI / provisioner can all read from the same place without duplicating the data.

Properties of the contract

The OmniNode disclosure shows the contract has these load-bearing properties:

  • Per-node — each node ships its own contract; there is no central contract file.
  • Bidirectional — both subscribe_topics (inputs) and publish_topics (outputs) are declared.
  • Wire-format names, not aliases — the strings in the YAML are what go on the wire.
  • Schema-validated — topic names follow onex.{kind}.{producer}.{event}.v{N}, validated by regex; a StrEnum backs the canonical registry to catch syntactically- legal but non-canonical names. See concepts/regex-plus-enum-validation.
  • The reviewed location — "the only reviewed location where wire-format topic names live." No constants near publishers, no consumer-config strings, no provisioner config.
  • Required for provisioning — "if a node wants the system to provision and validate a topic, it must put the topic name in its contract."

What it enables downstream

Because the contract is the single source of truth, a single parser (ContractTopicExtractor) can be used in three places: - CI validates the contract against a real broker before merge. - Runtime boot provisions topics from the contracts only. - Post-boot validation queries the broker, compares against the parsed contracts, re-invokes provisioning on mismatch.

See patterns/single-extractor-multi-call-site for the topology and patterns/contract-driven-topic-provisioning for the pattern.

Sibling framings

  • concepts/runtime-api-vs-gitops-source-of-truth — the Redpanda Connect 2025-12-02 GitOps disclosure of the same shape: declarative manifest in source control is the source of truth, runtime mutations are not. OmniNode's contract.yaml is the agent-bus equivalent.
  • concepts/registry-as-governance-precondition — the MongoDB tool-registry framing: an inventory primitive is upstream of policy enforcement. OmniNode's contract.yaml is per-node manifest in lieu of a central registry — the union of contracts is the registry.

What it doesn't do

The contract discipline catches: - Topic naming drift (silent wiring failure). - Missing topics at provisioning time. - Non-canonical names (StrEnum check).

The contract discipline does not catch: - Partition-count drift — "if a topic was originally created with 6 partitions and the contract later requests 12, the provisioner will not notice." - Replication-factor drift. - Retention-policy drift.

These are the next-gap problems the OmniNode post explicitly acknowledges as unbuilt; the proposed future-work shape is "diff against the contract spec, decide which mismatches are auto- correctable, surface the rest as explicit drift."

Seen in

Last updated · 542 distilled / 1,571 read