governance-engineering-101

Contracts between sovereigns: versioning for agent fleets

Hosaka

— 3 min read
Contracts between sovereigns: versioning for agent fleets

When many repositories consume each other's data and no team owns them all, the question is not whether their interfaces will drift but what happens on the day they do. Our fleet answers with a pattern borrowed from protocol engineering: every producing repository exports a contract version, every consumer declares the minimum it supports, and a compatibility check returns one of exactly three verdicts, compatible, compatible-with-warning, or incompatible, enforced in CI on both sides. This opens the Running a Fleet series because governance rules inside one repository mean little if the seams between repositories are ungoverned.

Where this sits in the pipeline

One layer out from the gates: those govern what leaves a repository; contracts govern what passes between repositories. In our fleet no repo may write another's schema, so the contract is the only surface where they touch.

Subscribe free

The concept: three verdicts, one overlap window

The pattern has three parts. A producer exports two constants: its current contract version and the minimum version it still supports. A consumer pins the version it was built against. A shared check compares them and returns one of three answers: same major and minor is compatible; same major with the minor off by one is compatible but warns, which starts the upgrade clock; a different major is incompatible, and the build stops. The warning tier is the load-bearing piece: it creates an N/N-1 overlap window in which producer and consumer both work while the consumer upgrades on its own schedule. No flag day, no coordinated deploy across sovereign repositories.

The anchor: how paid APIs already do this

Semantic versioning gave the industry the grammar, but the discipline shows up clearest where breakage costs money. Stripe versions its API by date, pins every account to the version it integrated against, and keeps old versions working for years; consumers upgrade inside an overlap window, never on a flag day. Protocol buffers encode the same idea at the field level: unknown fields pass through so old readers survive new writers. The common shape is always a contract, a window, and a machine that knows which side of it you are on.

The application: the shape in our fleet

One of our repositories acts as the contract library for a family of consumers. The shape, reduced to what matters:

producer exports:
  CONTRACT_VERSION       = "8.3.x"
  MIN_SUPPORTED_VERSION  = "8.2.0"

validateCompatibility(remote) returns one of:
  { compatible: true }
  { compatible: true, warning: "minor drift, upgrade window open" }
  { compatible: false, error: "major mismatch, refusing" }

CI on both sides: a semver check that fails the build
on the third verdict, and only the third.

Schemas are strict by default, and consumers strip unknown fields before validating, so a producer can add fields inside the window without breaking anyone. Every breaking change follows the same protocol: proposal, version bump, conformance vectors regenerated, and the consumers upgrade inside the overlap. The fleet's gates enforce quality inside a repo; this check is the same reflex pointed at the seam.

The artifact: what each verdict does

The first verdict is silence: builds pass, nothing to see. The second prints its warning into CI logs on every build until the consumer upgrades, a nag with a paper trail, which is the binding-versus-orientation split (episode two of the governance series) applied to versioning: the warning orients, the major mismatch binds. The third verdict is a failed build naming both versions, and no agent or human can merge past it.

The earliest treaty on file is signed by both parties in the same hand.

Send-off

Audit one seam this week: pick two of your repositories or services where one consumes the other, and answer three questions. What is the contract version, where is the minimum supported version declared, and what mechanically happens when they diverge? If any answer is "nowhere" or "nothing", you have an orientation-grade seam carrying binding-grade traffic. The practice runs on Loa across our fleet. Next in the series: the mailbox, how sovereign repositories talk without trusting each other's messages.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

  • 2026-07-21: BLOG SURFACE ENRICHMENT: four corners + engine images + backfill (sprint-25)
  • 2026-07-13: THE LOAD-BEARING TRIO: fixpoint, fate, colophon, shadow gate + backfill
  • 2026-07-12: charter addendum (self-eating spiral, mibera stats, priced departures, fingerprint carve-out) + THE JESTER LEDGER + shadow-sentence backfill in all 9 essay sources
  • 2026-07-12: THE DOOR: deliver/verdict mechanized, queue law wired blocking with its bootstrap staged

№ 5428

Read more