API contracts and versioning

The concern: version one is deployed, other systems integrate with its APIs, and the platform later changes the application. Can behaviour change without breaking the API contract? Can the platform be told "maintain the version-one contract, no breaking schema or endpoint changes" and be held to it?

The short answer

Yes, as requirement-linked tests that gate every promotion: a contract is written down as a requirement of kind constraint, its tests call the API and assert status, shape and values, every suite runs every fifteen minutes, after every deploy and before a project copy is pushed to another environment, and a red suite refuses the push. What is not built is a schema-level gate: a diff of the API description, semantic API versioning, or automatic generation of contract tests from a schema. Partial

What is in place

Mechanism	What it does	Standing
A contract as a requirement	"Maintain the version-one contract; do not introduce breaking schema or endpoint changes" is a requirement of kind constraint, cited to the document that asked for it. Constraints are pinned; a review never regenerates them, and the fleet sees them on every card for the project.	In place
Contract tests	Tests of the HTTP and endpoint kinds linked to that requirement: call the API on a named target, assert on the status, on paths in the body, on counts and types. A test names a target, never a host, so the same test runs on the platform, in the customer archive and in the customer's environment.	In place
The watchdog	Every project's suite runs every fifteen minutes, once after boot and after every deploy; a transition (green to red, a different failing set) files an alert and posts to the alerts channel.	In place
The promotion gate	A project copy moving between environments ends with the test gate; a red suite refuses the push.	In place
Change on a branch	Every branch of a project's configuration has its own engine fork. A change is made on a branch, the structure check and the tests run there, and the branch is merged when green.	In place
Version history and rollback	Every endpoint save is a version with diff and restore; every export is a commit; the runbook's rollback section has two layers, the previous image tag and per-consumer flags in the project's data.	In place
The fleet's own verification	A card is not complete until the tests of the requirements it touched pass; the fleet authors tests for the requirements it made true and runs the whole suite before it hands back.	In place

Holding the platform to a contract, in practice

The integration guide for the API is uploaded as a requirement source. The rows it yields include the contract as a constraint.
The contract's tests are written once, against version one as deployed: one HTTP test per operation with the response shape asserted.
A change request arrives. The fleet builds it on a branch. Its self-check runs every test of the project; a contract test that turns red is a failed card, visible on the Board with the failing assertion.
A change that cannot be made without breaking the contract is filed back as a decision for a person: add a new major version, or renegotiate. The fleet does not decide that.

What a contract test asserts

A test names the target service and a path, and lists assertions: the response status, the type of each field the consumers rely on (an identifier is a string, an amount is a number), the presence of a list and its minimum length. The test is stored with the requirement and travels with every export, so the same assertions run wherever the service is deployed.

Still to do

Gap	Today	Next step
A schema-level breaking-change gate	To do Contracts are enforced by tests a person or the fleet writes.	A test kind for contracts: the test names an API description document committed with the service, and the runner fails on a breaking diff against the last published version (removed path, removed or retyped field, narrowed enumeration). The runner already ships with every archive, so the gate travels with the delivery.
Semantic API versioning	To do Versioning is the application's own convention.	Record the API version on the service's declaration row and have the contract test kind refuse a breaking diff unless the major version was bumped.
Contract tests generated from a schema	To do Tests are authored per operation.	Generate the per-operation HTTP tests from the API description on the "Write tests" action, so version one gets its contract pack in one step.
An API description for generated services	Partial The platform's own API has an interactive reference; a generated application service documents its API only if a requirement asks.	Make an API description part of the enterprise security profile (see Security and identity), so every generated API ships with one.