0010: v1 is frozen by a test, not a promise in prose
Context
Section titled “Context”“We won’t break the API” is a sentence. Breaks happen through small edits nobody flags: a field made optional, a max length lowered, an enum value dropped.
Decision
Section titled “Decision”The surface is kept as data in the source repository
(contract/): the
OpenAPI paths and every MCP tool’s input schema at the moment they were
frozen. A test compares the current surface with it by the rules in
Stability: inputs may only accept more, outputs may
only promise more. The test suite checks the branch’s own copy; CI checks the
base branch’s, so re-freezing in the same change can’t hide a break.
Consequences
Section titled “Consequences”- Additions have to be frozen too (a script in the repository,
pnpm contract:freeze), so what ships in 1.1 is as fixed as what shipped in 1.0. - The comparison is structural. A change of meaning with the same shape is still caught only in review.