Contract Compatibility Gates for Agent API Changes: Blocking Hidden Breakage for Consumers

When an agent is asked to "add a field to the response," it often also renames old fields, tightens enums, adjusts null handling, or regenerates the client. Server-side unit tests may all pass, the new service can handle new requests, but the old mobile clients, partner scripts, and async consumers have already been broken. Compatibility gates must judge changes from the consumer-observable contract, not from whether the provider builds successfully.

The rules for REST, GraphQL, events, and Protobuf are not identical, but the chain of evidence is similar: freeze a baseline contract, identify structural and semantic differences, run real consumer contracts, cross-validate with old and new versions, then decide on compatible release, migration window, or rejection. For protocol selection background, see REST, GraphQL, and gRPC API Design; this article focuses on who breaks after the change.

The contract baseline must come from published facts

The baseline is not a file the agent generates on the side when starting work; it is the OpenAPI, GraphQL schema, Protobuf descriptor, event schema, and their digests from the current production version. CI retrieves them from the artifact repository by BASE_RELEASE, then builds the candidate contract from HEAD, recording the generator version, source file hashes, and command. The two api:* names below are script contracts the repository must implement in package.json, not built-in pnpm commands; the pre-check fails immediately when a script is missing.

node --version
pnpm --version
pnpm install --frozen-lockfile
mkdir -p .artifacts
node -e 'const p=require("./package.json"); for (const n of ["api:schema:build","api:contract:diff"]) if (!p.scripts?.[n]) throw new Error(`missing package script: ${n}`)'
pnpm run api:schema:build
sha256sum .artifacts/openapi-base.json .artifacts/openapi-head.json
pnpm run api:contract:diff -- \
  .artifacts/openapi-base.json .artifacts/openapi-head.json

The example environment is pinned to Node 22.18.0 and pnpm 10.14.0; both the diff and code generation tools use the exact versions from the lockfile. The report binds the base release digest, head SHA, specification version, and generation command. If the specification is generated by runtime code, CI must also start the service in a clean container and deterministically compare the exported results, so uncommitted state does not affect the contract.

The OpenAPI diff first blocks clear breakage: removing paths, methods, response fields, or enum values; changing optional to required; tightening length and numeric ranges; changing status codes, content types, authentication requirements, or field types. Adding a response field is usually compatible, but if known consumers use strict deserialization, it can also break, so automatic rules cannot replace consumer evidence. API versioning and deprecation windows can be designed together with REST API Versioning.

Let consumers declare real expectations

Each active consumer publishes a versioned contract containing the requests it will send, the fields it depends on, the allowed enums, and the error behavior. Provider CI uses the candidate service to validate both the latest stable version and old versions still within the support window. Contract artifacts must be signed or carry a digest, with source, consumer commit, environment, and generation time traceable; contracts older than 30 days cannot be assumed compatible and can only trigger owner confirmation.

Contract cases should verify semantics, not just the schema. For example, an old client still gets the original default behavior when it does not send a new field; a duplicate idempotency key does not produce a second side effect; unknown response fields are ignored; error codes and retry hints stay consistent. Event consumers must also verify that an old consumer can read a new producer's messages, that a new consumer can read old messages within the publishing window, and that out-of-order, duplicate, and missing optional fields are handled.

Evolution like Protobuf must follow rules such as not reusing field numbers, reserving numbers for deleted fields, and not changing an existing field from repeated to singular. Even if the wire format is parseable, changing units from milliseconds to seconds, changing time zone semantics, or changing default values is still a semantic breakage that must be blocked by scenario tests.

Build a cross-version compatibility matrix

The merge gate runs four directions: old consumer against candidate provider, new consumer against baseline provider, candidate producer to old event consumer, and old producer data to candidate consumer. Each records the image digest, seed data, request and response digests, and exit code. When an SDK is involved, at least the current stable SDK and the oldest SDK still in support are built; you cannot just regenerate the HEAD SDK and self-test.

Pass conditions are: the static diff has no unapproved breaking change; all active consumer contracts pass; the compatibility matrix has no failures; deprecated fields are still within the promised window; migration documentation and monitoring are ready. High-risk interfaces also require manual confirmation. For the code review loop, see PR Review Loop for Coding Agents, but what the reviewer sees should be specific consumers and versions, not a single "API tests passed".

Failures cannot disappear by updating the consumer contract

After a contract failure, the agent first restores backward compatibility, for example by keeping the old field and adding a new one, accepting the old enum, or introducing new semantics through version negotiation. It is forbidden to change consumer expectations to the provider's current output in the same patch and then claim it passes; contract updates require an independent commit in the consumer repository and owner approval.

If a breaking change is genuinely needed by the business, the state is not to continue auto-merging, but to enter a migration process: assign a new version or negotiation mechanism, list consumer owners, provide dual-write or an adapter layer, and define a last-use date, a zero-traffic threshold, and a rollback path. During deployment, monitor old field usage, deserialization errors, unknown enums, 4xx/5xx, and retry storms; the old contract can only be removed after the threshold is met.

Tool timeouts, missing baseline artifacts, consumer contracts that cannot be downloaded, or test environment startup failures all count as missing evidence and block by default. When a manual exemption is allowed, record the scope, reason, owner, and latest expiration time, and it cannot cover payment, authentication, or data deletion interfaces. Verification of other layers of the patch still follows Change Validation Gates for Coding Agents.

Before going live, calibrate with fault samples: removing an optional field, tightening an enum, changing the default time zone, reusing a message field number, and changing a 404 to a 200 empty object, to confirm that at least one gate fails. The goal of compatibility gates is not to make the specification files tidier, but to ensure that every time the agent changes an interface, it answers clearly: which real consumers and which still-supported versions have been proven by re-runnable evidence not to be silently broken by this change.