# 0238 — Before 1.0 the shape of the API outranks compatibility

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0238-pre-1-0-api-shape-outranks-compatibility.md

---
# 0238 — Before 1.0 the shape of the API outranks compatibility

**Status:** Accepted
**Date:** 2026-10-05

Builds on ADR 0198 and ADR 0204. Invariants I8 and I14.

## Decision

Before 1.0, a change that makes a public call site clearer, smaller or harder to misuse is made
even when it breaks consumers. It is made as one clean cutover: the old shape is deleted, every
call site in the repository moves in the same change, and no alias, shim or deprecated twin stays
behind.

A break of this kind is never silent. It ships as a minor release with a `### ⚠️ Breaking changes`
entry that starts with the entrypoint, shows a before → after snippet and names who must act, and its
migration is written in `docs/guide/upgrading.md` as steps a consumer or an agent can apply
mechanically. The shape rules that guide such a change are in
[`docs/architecture/api-shape.md`](https://github.com/max-listov/stitchkit/blob/master/docs/architecture/api-shape.md).

Compatibility is not given up for taste. The change must remove a concrete defect of the call site:
a positional parameter list or boolean pair that cannot be read, two names for one concept, a type
that cannot be inferred where it is used, or a refusal whose reason a caller can only recover by
parsing text. A rename with no such defect is not a reason to break anyone.

## Reason and verification

Pre-1.0 consumers have opted into an evolving API and are migrated by explicit versions: the caret
range of a `0.x` release never crosses a breaking minor on a plain install. The cost of a clean
break is one mechanical migration, paid once. The cost of keeping a poor shape is paid at every call
site by every consumer and every agent that copies an example, and it is still there at 1.0.

Verification is the existing release gate: `scripts/release-plan.ts` refuses a breaking section
without its entrypoint prefix, its stable-entrypoint ADR where one applies and its promoted
migration, and refuses a breaking item in a patch version.