Skip to content

Commit 5262124

Browse files
os-steveclaude
andauthored
feat(docs-gate): close the runtime-services stability label vocabulary (#9751) (#10008)
`stable` / `experimental` was the whole vocabulary, written out by hand in two places that nothing compared -- the "Stability Legend" table in `runtime-services/index.mdx` and the "Stability Labels" bullets in `versioning.mdx` -- with no enum in code behind either. Measured on this tree before this change: `audit-service.mdx` declaring `- **Stability:** `beta``, with the Current Matrix row and the kernel/index.mdx row faithfully repeating `beta`, was green while neither legend defined `beta` anywhere; a `beta` row added to one legend alone was green too. The vocabulary now has ONE definition, `STABILITY_VOCABULARY` in the existing gate. Both legends are held to it by exact ordered EQUALITY -- not membership, which passes one legend dropping a row the other keeps -- and every page's label is drawn from it. The two tables are deliberately left to check 7, which already holds them to the page, so an out-of-vocabulary label reports once, against the file where the label was chosen. No new gate: this is checks 9-10 of `check-runtime-services-index.mjs`, per the ruling that a second recognizer on one surface is how two recognizers end up disagreeing. Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja Co-authored-by: Claude <noreply@anthropic.com>
1 parent e61ee68 commit 5262124

3 files changed

Lines changed: 297 additions & 21 deletions

File tree

‎content/docs/kernel/runtime-services/index.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,13 @@ This chapter documents the runtime `services.*` APIs used in hook/action/flow/pl
4141
| `stable` | Backward-compatible within a major version |
4242
| `experimental` | API is available but may change in minor releases |
4343

44+
These two labels are the whole vocabulary. The same list is written out again as
45+
[Stability Labels](/docs/kernel/runtime-services/versioning), and
46+
`scripts/check-runtime-services-index.mjs` holds both legends — and every page's
47+
**Stability** bullet — to one definition, so a page cannot publish a label neither legend
48+
defines. Adding a label means extending that definition in the same change that says what
49+
it promises, in both places.
50+
4451
## Source of Truth
4552

4653
Each page links the canonical TypeScript source used to derive signatures.

‎content/docs/kernel/runtime-services/versioning.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,12 @@ description: Stability labels and how to track runtime service API breaking chan
1010
- `stable`: backward-compatible within the current major version.
1111
- `experimental`: can change in minor versions; verify release notes before upgrades.
1212

13+
These two labels are the whole vocabulary. The same list is written out again as the chapter's
14+
[Stability Legend](/docs/kernel/runtime-services), and
15+
`scripts/check-runtime-services-index.mjs` holds both legends — and every page's **Stability**
16+
bullet — to one definition, so the two lists cannot drift apart. Adding a label means extending
17+
that definition in the same change that says what it promises, in both places.
18+
1319
## Breaking-Change Tracking
1420

1521
When a runtime service API changes in a breaking way:

0 commit comments

Comments
 (0)