docs: retire the API freeze, keep the removal check#1083
Merged
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
API surface delta (frozen public contract — see Added (allowed in a patch):
Removed / renamed (BREAKING — needs a 0.MINOR bump + CHANGELOG migration note):
|
The surface was described as frozen for 0.x. That list has been edited 40 times. A stability promise revised whenever it becomes inconvenient is not a promise — it is a claim that quietly stops being true, and it forced an is-this-breaking debate on changes that were plainly improvements. The check is kept, because it does something narrower and worth having: it fails when a listed symbol stops being exported, stops being declared, or stops registering. It has never failed on an addition and cannot. The point was never to prevent removals, only to make them deliberate — a removed export should be a decision with a migration note, not something a consumer finds before CI does. FROZEN_* → PROTECTED_* across the data, the type gate, the runtime check, the parity generator and four site pages. Failure messages now name what happened and what to do about it: drop the entry in the same change and add a CHANGELOG note. Verified the check can still fail: injecting a phantom protected symbol exits 1 with the new message. A gate that cannot fail is not a gate. Two inaccuracies fixed in passing. The docs page claimed the entries 'fail the build if they change' — only removal fails. The canonical doc cited 'the frozen 17' where the check reports 20. typecheck clean; full suite passes; check:api, check:docs, check:links green; site builds and the published page now reads '20 entries that fail the build if they disappear'.
zachshallbetter
force-pushed
the
docs/api-surface-honesty
branch
from
July 20, 2026 19:41
8cc2da8 to
2fc81af
Compare
RELEASING.md, PUBLISHING.md, docs/canonical/README.md, agent-consumption-model.md and agent-safety-model.md still described a freeze. substrate-api.md cited 'the frozen 17' twice where the check reports 20 — a stale count, not just stale wording. Deliberately untouched, because the word means something else in each: Object.freeze'd policy clones in agent-safety-model.md, 'frozen design history' for the planning archive, 'freeze the sim' for reduced motion, and 'frozen particles' in the poster render mode. A pattern-matched sweep would have damaged all four. Freeze wording survives in prose across several other canonical docs. That is stale phrasing rather than a wrong claim about the gate, and chasing it through fifteen files belongs in its own change rather than blocking a release.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
The surface was described as frozen for
0.x. That list has been edited 40 times.A stability promise that gets revised whenever it becomes inconvenient is not a promise — it is a claim that quietly stops being true. It also forced an "is this breaking?" debate on changes that were plainly improvements.
What is kept, and why
The check does something narrower than the promise claimed, and that narrow thing is worth having.
It only fails when something disappears. Every failure condition is a listed symbol that stopped being exported, stopped being declared, or stopped registering. It has never failed on an addition and cannot — new exports land freely.
The point was never to prevent removals. It is to make them deliberate: a removed export should be a decision with a migration note, not something a consumer discovers before CI does.
Changes
FROZEN_*→PROTECTED_*across the data, type gate, runtime check, parity generator and four site pages (I initially renamed a hand-listed set and broke the site build by missing two importers — found by building, then fixed by searching).api-stability.mdand/docs/api/stabilityrewritten to describe removal protection rather than a freeze.Verified the gate can still fail
Injecting a phantom protected symbol exits 1 with the new message. A gate that cannot fail is not a gate.
Two inaccuracies fixed in passing
Gates
typecheck · full suite ·
check:api·check:docs·check:links· site build — all green. Published page now reads "20 entries that fail the build if they disappear."