12  Principle Two — Contracts Are the Constitution

A pipeline is a society of components. Components are built by different people, at different times, in different languages, with different release cadences. What holds such a society together is not goodwill or a shared code style. It is a constitution: a small set of versioned, public, enforced agreements about what crosses boundaries.

In software the constitution is made of contracts — schemas that define the shape of every payload that passes between components. The rules of a good contract regime are few and strict:

• Versioned immutably. A contract, once published, never changes. Additions within a major version are permitted; anything that could break a consumer requires a new version directory, not an edit.
• Self-declaring. Every payload states its own contract — a name and a version, stamped on the envelope. A component that receives a payload citing an unknown major version must refuse it, loudly.
• Validated at the border. Inside a component, anything goes — any language, any library, any internal refactor. At the border, only contract-conforming payloads pass. The border is where validation lives; everywhere else is freedom.

12.1 Why this is the right shape

The alternative shapes all fail in characteristic ways. Shared libraries create compile-time couplings that make independent deployment impossible. “Documentation” decays the moment a deadline appears. Ad hoc formats mutate quietly until one night an upstream team renames a field and a downstream pipeline confidently produces garbage. Contracts fail none of these ways, because they are executed, not consulted: the rejection of a malformed payload is not a policy, it is a mechanism.

The deeper value is economic. Contracts make components swappable, and swappability is what makes a small team powerful. When the table engine, the ADaM builder, the figure kernel, and the QC comparator all speak through stable contracts, you can replace any one of them — including replacing a homegrown one with an open-source one, or an obsolete one with a better one — without renegotiating the rest of the system. The constitution protects the union, not any citizen.

12.2 Constitutional discipline

Like any constitution, contracts only work if the guardrails are cultural as well as mechanical:

• Contract changes are events, not edits. They deserve a written record — what changed, why, who consumed the old version, and a migration path. In a healthy system this record is an architecture decision entry, reviewed like code.
• The schema is the single source of truth. Any documentation that paraphrases the schema will eventually contradict it; treat paraphrases as commentary, never as law.
• No undocumented exceptions. The moment a component accepts a payload that violates the contract “for compatibility,” the constitution has been suspended by fiat, and every future argument will cite the precedent.

There is a quiet benefit that is easy to miss: contracts convert trust between people into trust between systems. Two teams that barely speak to each other can integrate safely, because neither needs to trust the other’s internals — only the shared, versioned, mechanically enforced border. In organizations, that is not a technical nicety. It is peace.

The test. Take any two components in your pipeline and ask: “What exactly do they promise each other, where is that promise written down, and what physically prevents either from breaking it silently?” If the answer involves a person’s memory, a stale wiki page, or the phrase “it should be fine,” there is no constitution — only diplomacy, and diplomacy fails at deadlines.