Engineering Intelligence. Read the book.
module-32/contract-forge.mdDELIVERY STANDARD

The Contract Forge

The spec is the source of truth. Everything else is generated from it — or it doesn't ship.

Frontend and backend each 'remembered' the API slightly differently — integration week was archaeology, and mobile shipped against an endpoint that had quietly changed.
Contract-first development: the OpenAPI spec is the source of truth, clients and validation derive from it, and if it isn't in the contract, it doesn't deploy.

The incident

The backend team 'improved' a response shape on a Tuesday. The web team found out Thursday, from a bug report. The mobile team found out three weeks later, from the App Store reviews — because their release cycle meant the broken version was already on phones. Three teams, one API, zero shared definition of it.

Why the obvious approach fails

When the API's real definition lives in the implementation, every consumer is guessing — and every consumer guesses slightly differently. Documentation drifts because it's written after the fact; integration testing becomes archaeology; and the consumers with the slowest release cycles (always mobile) pay the highest price for every quiet change. Contract-first inverts the authority: the OpenAPI spec is written first, reviewed as the design artifact it is, and everything downstream — server validation, client SDKs, mock servers, tests — is generated from it. A change to the API is a change to the contract, visible to every consumer in review, before any code moves.

The standard

  • The OpenAPI spec precedes implementation; it's the reviewed design artifact, and code derives from it — never the reverse.
  • Server-side request/response validation is generated from the contract: an undocumented field or shape is rejected, not tolerated.
  • Client SDKs and mocks generate from the same spec, so frontend and mobile build against the contract before the backend exists.
  • Breaking changes are mechanically detected in CI by diffing contract versions — a break requires a version bump and a migration note, not an apology.
  • If it's not in the contract, it doesn't deploy.

How Cortex validates it

At plan time

API Missions produce the contract as a plan-stage deliverable, approved before implementation begins.

At validation

assert: responses ≡ contract (undeclared fields == 0)assert: contract_diff.breaking → version_bump requiredassert: client_sdks.generated_from == current_contract

Assertion syntax is illustrative.

At review

the approver sees the contract diff itself as the review artifact — what changed in the API's promise, before what changed in its code.

Composes with

The Webhook NotaryThe N+1 SentinelThe Anti-Corruption Layer

See where your codebase stands against this standard.

Get an Agent Readiness AssessmentBack to the library