Behavioral Contracts Between Teams

The Problem

Multiple teams own different parts of a system. They agree on interfaces — API schemas, message formats, protocol buffers. Tools like OpenAPI and protobuf give them structural contracts: what fields exist, what types they have, what endpoints are available.

But structural contracts say nothing about behavior. They do not specify that a payment must be authorized before it is captured, that a session cannot be resumed after it expires, or that a retry must be idempotent. These behavioral rules live in documentation, Slack threads, and the heads of senior engineers.

When one team changes a behavior that another team depends on, nothing catches it. The schemas still match. The integration tests — if they exist — check happy paths. The failure surfaces in production, weeks later, as a subtle inconsistency.

This is the norm in microservices architectures, platform APIs, and multi-vendor integrations.

The Approach

Write the behavioral contract in Spine. Not the implementation — the contract. What each side must guarantee. What each side may assume.

A Spine behavioral contract specifies preconditions and postconditions for each interaction, temporal constraints on sequencing, and invariants that must hold across the boundary. It compiles to an executable that each team can test against independently.

Team A tests their service against the contract's expectations of the caller. Team B tests their service against the contract's expectations of the provider. Failures are not integration surprises — they are caught locally, against a shared, verified reference.

The Outcome

• Shared behavioral truth — the contract defines not just what the shape of the data is, but what sequences of interactions are valid, what state transitions are allowed, and what invariants must hold.
• Independent verification — each team tests against the contract on their own. No coordinated integration environments required to catch behavioral mismatches.
• Change detection — when the contract is updated, the compiler identifies what changed. Each team re-verifies. Behavioral regressions are caught before deployment.
• Living documentation — the contract is a precise, executable description of the boundary. It replaces the wiki page that nobody updates.

The Workflow

Teams Agree on Boundary → Behavioral Contract in Spine → Compile → Contract Executable

Each team, independently:

Team Service → Test Against Contract Executable → Fix Violations

When the boundary evolves:

Update Contract → Re-verify → Each Team Re-tests

Why This Works

Structural contracts answer "what data flows between us?" Behavioral contracts answer "what may we do with it, and in what order?" The second question is where the bugs live.

Spine's effect system is designed for exactly this. Effects have preconditions and postconditions. Processes have sequencing constraints. The compiler verifies that these constraints are consistent — not just that they parse. A contract that allows contradictory sequences is rejected at compile time.

And because the contract compiles to an executable, it is not just a specification — it is a test oracle. Each team has a concrete artifact to test against, not an abstract document to interpret.