Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): define release compatibility and versioning (#6755)

Cindy Zhange7723cddf1cc
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index 9e27b7d0ff..e9cde6ae09 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -113,8 +113,9 @@ guidance owns the process used to propose and test APIs.
- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a prop
and connects it to the element promised by its contract.
- **INV9 — Released APIs change deliberately.** A released prop, type, export,
- default, or observable behavior is not removed, renamed, or retyped without an
- explicit compatibility decision and migration.
+ default, or observable behavior is not removed, renamed, retyped, deprecated, or
+ corrected incompatibly without the lifecycle, evidence, and migration required by
+ [`spec:AST-017`](../specs/AST-017/spec.md).
- **INV10 — Shared subcontracts are linked, not copied.** Input Actions, layer
behavior, theming, and family-specific rules stay with their owning records.
- **INV11 — Public theme seams pass API admission.** A public semantic CSS custom
diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.md
index 56a4e35ac1..01f352aae5 100644
--- a/docs/specs/AST-002/spec.md
+++ b/docs/specs/AST-002/spec.md
@@ -220,8 +220,10 @@ A public API proposal is admitted only when it passes both gates:
For every public API or public behavior delta, identify the canonical owner and
apply the routing defined by `architecture:knowledge-contracts`. This spec owns
-API admission and semantic-shape requirements; it does not copy review outcomes
-or pull-request disposition.
+API admission and semantic-shape requirements; the
+[Release compatibility and versioning spec](../AST-017/spec.md) owns lifecycle,
+classification, deprecation, correction, and release treatment. Neither record copies
+review outcomes or pull-request disposition.
A draft record may provide context and route the unresolved question, but it
cannot clear current authority. Exact-head owner discussion supplies decision
diff --git a/docs/specs/AST-010/spec.md b/docs/specs/AST-010/spec.md
index 769f92b1d8..d6515d7343 100644
--- a/docs/specs/AST-010/spec.md
+++ b/docs/specs/AST-010/spec.md
@@ -266,8 +266,11 @@ behavior under `minSize` and `maxSize`.
The shipped contract remains distributed across its current owners:
-- `architecture:public-component-api` owns the stable exports, breaking-change
- classification, and migration boundary;
+- `architecture:public-component-api` owns stable export and component contract
+ shape;
+- [`spec:AST-017` — Release Compatibility & Versioning system spec](../AST-017/spec.md)
+ owns classification, deprecation/cleanup state, Changesets, and migration evidence;
+ this spec keeps the exact Resizable mapping and its direct transition requirement;
- `family:layout-regions` delegates resize state and interaction to useResizable
and ResizeHandle while LayoutPanel consumes resolved size;
- `spec:AST-002` governs the caller-owned container basis and predictable state;
diff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.md
index cb14424ac9..5d7e0c2dbd 100644
--- a/docs/specs/AST-013/spec.md
+++ b/docs/specs/AST-013/spec.md
@@ -125,8 +125,9 @@ requirements. Assistive-technology evidence remains separately owned.
- **FR11 — Raising the floor is compatibility work.** Removing a supported browser,
moving it from full behavior to reduced fallback, or removing a documented
- fallback requires owner approval, a Changeset, user-impact and migration notes,
- updated generated rows, actual-browser evidence for the browsers affected by the
+ fallback requires owner approval, the classification and lifecycle required by
+ [`spec:AST-017`](../AST-017/spec.md), user-impact and migration notes, updated
+ generated rows, actual-browser evidence for the browsers affected by the
compatibility claim, and evidence that every remaining full-support and named
explicit support row still receives full required behavior.
- **FR12 — Component specs inherit the baseline.** Component specs link
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 6f2421ce51..f3a61f3047 100644
--- a/docs/specs/AST-017/spec.md
+++ b/docs/specs/AST-017/spec.md
@@ -7,11 +7,15 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-02
+approved_at: 2026-09-29
phase: accepted
owners: [cixzhang, josephfarina]
affects_architecture:
- [architecture:public-component-api, architecture:cli-surface]
+ [
+ architecture:public-component-api,
+ architecture:cli-surface,
+ architecture:theme-tokens,
+ ]
affects_families: []
affects_contributing:
[
@@ -22,7 +26,7 @@ affects_contributing:
affects_consumer_docs: [release-process, templates]
---
-# Published compatibility and breaking-change classification system spec
+# Release Compatibility & Versioning system spec
<!-- review-applicability:v1 -->
@@ -37,6 +41,10 @@ affects_consumer_docs: [release-process, templates]
"DEC-7",
"DEC-8",
"DEC-9",
+ "DEC-10",
+ "DEC-11",
+ "DEC-12",
+ "DEC-13",
"FR3",
"FR4",
"FR5",
@@ -51,7 +59,27 @@ affects_consumer_docs: [release-process, templates]
"FR21",
"FR22",
"FR23",
- "FR24"
+ "FR24",
+ "FR25",
+ "FR26",
+ "FR27",
+ "FR28",
+ "FR29",
+ "FR30",
+ "FR31",
+ "FR32",
+ "FR33",
+ "FR34",
+ "FR35",
+ "FR36",
+ "FR37",
+ "FR38",
+ "FR39",
+ "FR40",
+ "FR41",
+ "FR42",
+ "FR43",
+ "FR44"
]
}
}
@@ -59,13 +87,19 @@ affects_consumer_docs: [release-process, templates]
## Intent
-Give contributors and reviewers one rule for deciding whether a change is
-`[breaking]`: identify an installed consumer whose valid use of the latest stable
-release stops working unchanged.
+Give contributors, reviewers, and release owners one durable contract for evolving
+published Astryx surfaces. Classify every change from the installed consumer it
+affects, isolate experimentation from stable behavior, stage deprecations and
+behavior corrections explicitly, and make a planned minor traceable to one locked
+final-patch baseline.
-The label is a compatibility classification, not a risk or severity score. A
-small, safe rename can be breaking; a large rewrite can be nonbreaking when it
-preserves the released contract.
+A valid consumer of the latest stable release is the compatibility test. The label is
+not a risk or severity score: a small rename can be incompatible, while a large
+rewrite can remain compatible when released usage is preserved. A real bug can also
+be incompatible when consumers validly rely on its released behavior; that case uses
+the distinct corrective path in FR32–FR35. Its primary Changeset tag remains `[fix]`,
+while additive metadata distinguishes it from an ordinary patch-compatible fix and
+from a generic `[breaking]` removal.
For CLI controls, keep every supported behavior discoverable and put each control on
the narrowest surface that owns it. Global controls require evidence that their value
@@ -78,7 +112,9 @@ independent for each invocation.
- Defining component or template naming conventions.
- Treating private packages, canaries, unreleased work, or explicitly marked
experimental surfaces as stable public API.
-- Replacing the release process, Changesets, or migration tooling.
+- Replacing the public Release Process, Changesets, migration tooling, or direct
+ component and feature authorities. This spec owns the lifecycle and evidence those
+ mechanisms implement; it does not duplicate their operational or product rules.
## Requirements
@@ -104,33 +140,50 @@ independent for each invocation.
continues to work with equivalent meaning through a compatibility alias or
adapter. A deprecation may warn and point to the replacement, but removing that
compatibility path is the breaking event.
-- **FR5 — Additive and contract-restoring changes are nonbreaking.** New optional
- capabilities, new components, new commands, broader accepted inputs, and new
- templates are nonbreaking when old usage is unchanged. A fix that restores the
- already-documented contract is nonbreaking even when it changes faulty output.
- A proposal that intentionally replaces the documented contract is not a fix for
- classification purposes.
+- **FR5 — Additive and victim-free contract restorations are nonbreaking.** New
+ optional capabilities, new components, new commands, broader accepted inputs, and
+ new templates are nonbreaking when old usage is unchanged. A fix that restores an
+ already-documented contract is nonbreaking only when no valid consumer of the
+ released faulty behavior must change. When a supported consumer relies on that
+ behavior and the correction breaks the consumer, FR32–FR35 classify it as an
+ incompatible fix even though the implementation violated authority. A proposal
+ that intentionally replaces the documented contract is not a fix.
- **FR6 — Risk does not override compatibility.** Low adoption, low likelihood,
engineering approval, or confidence that affected callers are uncommon does not
make an incompatible released contract nonbreaking. Conversely, implementation
size, visual scope, or review difficulty does not make a compatible change
breaking.
-- **FR7 — The Changeset category follows the classification.** A published
- breaking change uses a `[breaking]` Changeset. While Astryx packages remain on
- `0.x`, that category carries a minor bump; every nonbreaking published category
- carries a patch bump. Documentation-only, test-only, and private-package-only
- changes need no Changeset. `pnpm changeset:new` is the authoring path and
- `pnpm check:changesets` enforces the current category/bump coupling. Classify
- each published package update in multi-package work. A fixed-group version-only
- co-bump needs no Changeset entry by itself, but a generated dependency or peer
- range edit is part of that package's update and must be classified and named in a
- Changeset. When categories differ, use separate Changesets so every package entry
- follows its own classification.
-- **FR8 — Migration evidence matches the affected surface.** Every breaking change
- names the old valid usage, the replacement, and how consumers migrate. Supply an
- `astryx upgrade` codemod when consumer source can be rewritten mechanically.
- When no source rewrite is possible, provide an explicit compatibility alias or
- concrete replacement instructions rather than inventing a vacuous codemod.
+- **FR7 — Changeset tags and lifecycle metadata are orthogonal.** Existing primary
+ tags remain the authoring vocabulary: corrections use `[fix]`, compatible
+ capabilities and replacement-first staging use `[feat]` or the established narrower
+ tag, approved removals use `[breaking]`, and confined experiments use
+ `[experimental]`. New compatibility and lifecycle classification MUST be additive
+ machine-readable metadata, not a replacement tag. A victim-free correction is
+ `[fix]` plus `compatible` or `contract-restoring` metadata and a patch bump. A
+ behavior-correcting incompatibility is `[fix]` plus `incompatible-fix`, `IFIX-*`, and
+ `CLN-*` metadata and uses the incompatible version tier. Replacement-first
+ deprecation is `[feat]` plus `deprecation`, `DEP-*`, and `CLN-*` metadata and remains
+ patch-compatible while old usage works. Approved removal is `[breaking]` plus
+ `planned-removal`, its applicable lifecycle id, and `CLN-*`. While Astryx packages
+ remain on `0.x`, the incompatible tier is minor; compatible work is patch.
+ Documentation-only, test-only, and private-package-only changes need no Changeset.
+ Existing Changesets keep their current tag and validated bump semantics and MUST NOT
+ be mass-migrated; the additive metadata is required only when work enters a lifecycle
+ defined here. `pnpm changeset:new` remains the authoring path, and
+ `pnpm check:changesets` validates tag, metadata, evidence, and bump together once the
+ additive schema is implemented. Classify each published package update in
+ multi-package work. A fixed-group version-only co-bump needs no Changeset entry by
+ itself, but a generated dependency or peer-range edit is part of that package's
+ update and must be classified and named. When primary tags differ, use separate
+ Changesets so each package retains its own author-facing category.
+- **FR8 — Migration evidence matches the affected surface.** Every planned removal
+ and incompatible fix names the old valid usage, the replacement or corrected
+ behavior, and how consumers migrate. Supply an `astryx upgrade` codemod when
+ consumer source, configuration, metadata, or project files can be rewritten
+ mechanically. When no rewrite is possible, preserve an explicit compatibility
+ adapter or provide concrete replacement instructions and record why a codemod would
+ be vacuous. Codemods follow `spec:AST-040` and include positive, negative, and
+ second-run idempotence fixtures plus downstream proof.
- **FR9 — Template slugs are mutable catalog data.** A template slug identifies an
entry in the current template catalog; it is data about that template, not a
contractual CLI API. Renaming a slug is nonbreaking even when
@@ -292,13 +345,173 @@ independent for each invocation.
compares the previous published surface with current declarations and authored
docs, verifies that their experimental markers agree, and rejects an
`[experimental]` Changeset when any incompatible delta reaches a stable surface.
- The integration-theme contribution capability is the one grandfathered surface:
- its introduction in 0.6.3 is treated as experimental even though it predates the
- markers in FR21, and no other released surface may be enrolled retroactively. Its
- contribution metadata, discovery, and authoring contract may evolve in patch
- releases until an explicit promotion removes the marker. The surrounding stable
+ Integration-theme contribution capability remains the one grandfathered surface;
+ no other released surface may be enrolled retroactively. Its contribution
+ metadata, discovery, and authoring contract may evolve in patch releases until an
+ explicit promotion removes the marker. This prohibition does not turn an
+ unpublished field or behavior into stable API merely because an adjacent feature
+ was released. Integration-template replacement-specific fields and behavior—its
+ `replaces` declaration, replacement selection, optional list projection, and
+ expanded conflict fields—remain pre-publication surfaces under FR2 until their first
+ stable release; that classification is not experimental enrollment. Previously
+ released same-id conflict warning behavior remains stable. The surrounding stable
CLI command names, options, exit behavior, and machine-readable envelope remain
protected under FR3 and FR13.
+- **FR25 — Stable Core and every published stable package default to compatibility.**
+ Outside approved cleanup, changes to behavior, types, exports, CSS or tokens,
+ documented markup or selectors, accessibility semantics, persistence, CLI,
+ configuration, schemas, build tooling, docs routes, and package files MUST be
+ additive, implementation-equivalent, or a victim-free contract restoration under
+ FR5. An internal label, low adoption, or lack of a source-level API change does not
+ weaken this rule.
+- **FR26 — Public lifecycle state is explicit.** Each public surface is
+ `experimental`, `stable`, `correction-transition`, `deprecated`,
+ `cleanup-approved`, or `removed`; private and unreleased surfaces remain outside the
+ published lifecycle. Stable cannot become experimental. Deprecated and
+ correction-transition behavior remains supported until its exact cleanup item is
+ approved. A completed correction returns its surviving behavior to stable.
+- **FR27 — Experimental isolation covers every surface kind.** Whole experimental
+ components remain in the private canary-only Lab package governed by the public
+ Component Lifecycle. FR21 continues to govern stable-component props and exports.
+ Experimental CLI controls use a dedicated experimental namespace; configuration
+ uses an experimental object; CSS and tokens use dedicated experimental exports and
+ names; persistence uses a feature- and schema-versioned experimental namespace;
+ build tooling uses experimental exports/configuration; and docs use marked
+ experimental routes. An omitted opt-in MUST leave stable defaults, output, routes,
+ data, and behavior unchanged. Promotion requires owner approval and a `[feat]`
+ Changeset; withdrawal uses `[experimental]` and MUST prove no stable spillover.
+- **FR28 — Deprecation is replacement-first and machine-readable.** A deprecation
+ patch ships the working replacement while old usage remains equivalent. A public
+ record assigns a stable `DEP-*` id and a distinct `CLN-*` cleanup id and names the
+ package, surface kind, old contract, replacement, direct authority, warning,
+ migration, codemod or non-mechanical reason, downstream proof, state, and target
+ plan. Prose alone does not create removal eligibility.
+- **FR29 — Warnings fit the surface without changing success.** Declarations use
+ `@deprecated`; CLI aliases expose the deprecation id and replacement in their
+ machine result and emit at most one human-readable stderr warning per invocation;
+ runtime and build APIs use deduplicated development warnings; CSS and tokens use
+ static diagnostics. Warnings MUST NOT change production behavior, successful exit
+ status, canonical output, or machine-readable stdout.
+- **FR30 — Deprecation minima come only from direct authority.** This global spec
+ imposes no elapsed-time or release-count minimum. The structural minimum is that the
+ final patch preserves old and new behavior together. A direct current spec MAY
+ require a duration or number of stable releases for its own surface; the `DEP-*`
+ record cites that exact requirement and CI enforces it. Release cadence MUST NOT be
+ interpreted as a deprecation clock or eligibility gate.
+- **FR31 — Cleanup is one-to-one with approved ids.** A removal or default switch is
+ allowed only when its applicable lifecycle record id (`DEP-*` for deprecation or
+ `IFIX-*` for correction) and distinct `CLN-*` id appear in the frozen minor
+ manifest. Each incompatible delta maps to exactly one applicable lifecycle record
+ and one cleanup id, and each cleanup id maps to the old contract, replacement,
+ migration, proof, and rollback. Newly introduced incompatibility cannot be legalized
+ by adding it directly to a plan.
+- **FR32 — Behavior-correcting incompatibility is a distinct classification.** An
+ `incompatible-fix` exists when pre-existing current authority proves released
+ behavior wrong, unsafe, or nonconforming AND a valid latest-stable consumer relies
+ on that behavior such that the correction breaks code, interaction, persisted data,
+ output, or a supported workflow. Its primary Changeset tag remains `[fix]`, with
+ additive `incompatible-fix` classification metadata, an `IFIX-*` id, and a distinct
+ `CLN-*` cleanup id. It is not an ordinary patch-eligible fix and MUST NOT be recast as
+ a generic `[breaking]` removal. A visible correction with no valid released victim
+ remains `[fix]` with `compatible` or `contract-restoring` metadata under FR5.
+- **FR33 — Incompatible-fix evidence and approval are complete.** Before approval,
+ the `IFIX-*` record names the pre-existing expected authority, a latest-stable
+ reproducer for actual behavior, affected users and supported callsites or inputs,
+ an old/new compatibility matrix, coexistence analysis, migration, codemod or exact
+ non-mechanical reason, downstream proof, rollback, and harm from both delaying and
+ applying the correction. Without pre-existing authority, the proposal is a new
+ contract decision. The direct contract owner approves the expected behavior and
+ classification; the release owner approves the `IFIX-*`/`CLN-*` pair in the plan.
+- **FR34 — Incompatible fixes use a corrective lifecycle.** FR26 governs the state of
+ each public surface; the `IFIX-*` record tracks `proposed`, `approved`,
+ `transition-shipped`, `cleanup-approved`, `corrected`, `monitoring`, and `closed`.
+ `proposed` or `approved` leaves the released surface `stable`.
+ `transition-shipped` maps the coexisting old and corrected paths to
+ `correction-transition`. `cleanup-approved` maps the old path to
+ `cleanup-approved` while the corrected path remains `correction-transition`.
+ `corrected`, `monitoring`, or `closed` maps the surviving corrected contract to
+ `stable` and the eliminated old path to `removed`. When safe, a patch preserves the
+ old default while shipping the corrected opt-in or adapter, warning, migration, and
+ codemod. The paired minor changes the default or removes the old behavior only
+ through the approved `CLN-*`. An incompatible fix cannot enter the minor as an
+ incidental compatible fix or unrelated cleanup.
+- **FR35 — Emergency correction is narrow and never relabeled as a patch.** Only
+ urgent security, privacy, severe accessibility, or comparable critical ongoing
+ harm MAY bypass replacement-first coexistence or ordinary scheduling. Waiting must
+ materially extend the harm; no additive mitigation, containment, adapter, or safe
+ rollout may be available; the contract owner and relevant incident owner must
+ approve a dedicated record; public-safe incident evidence and restricted
+ attestation must justify urgency; exact-main quality and migration gates still run;
+ and the release contains no unrelated feature, cleanup, or incompatible fix.
+ Migration ships with the release; an incomplete emergency codemod records an owner,
+ bounded follow-up, fixtures, and delivery target. Rollback never restores known
+ harmful behavior: use containment or safe-forward correction.
+- **FR36 — Minor frequency is planning guidance, not eligibility.** Plan minors
+ generally no more often than once every fourteen calendar days. The plan records
+ the interval from the prior minor for owner review. CI reports the interval but
+ MUST NOT derive deprecation eligibility, a final-patch-to-minor wait, or an
+ exception requirement from it.
+- **FR37 — Every minor has an owner-approved public plan and freeze.** Before freeze,
+ the plan names the target, final-patch baseline procedure, exact `CLN-*` items,
+ migrations, codemods, downstream proof, allowed compatible fixes, exact-main gates,
+ release notes, rollback, and recovery. Changing cleanup items after freeze
+ invalidates the plan. Operational runbooks may add execution detail but cannot
+ authorize or widen cleanup.
+- **FR38 — The final patch is the paired minor's locked baseline.** Publish the final
+ patch with deprecated and correction-transition behavior still working, record its
+ exact source and package/docsite/visual/contract receipts, then lock that baseline.
+ The paired minor MAY follow sequentially and immediately when ready and explicitly
+ authorized; no wait exists unless a direct authority requires one.
+- **FR39 — Every final-patch-to-minor delta has exactly one class.** The diff MUST
+ partition into: (a) approved `CLN-*` cleanup removals or corrections; (b) a closed
+ list of version, changelog, lockfile-integrity, tag, provenance, digest,
+ build-timestamp, and source-map metadata; or (c) independently patch-compatible
+ fixes under FR40. Strict equivalence is the target. Unrelated features, additive
+ product capabilities, incompatible fixes outside approved corrective cleanup,
+ refactors with public deltas, and unclassified changes are prohibited.
+- **FR40 — Compatible fixes may be disclosed separately in the minor.** Each has its
+ own `[fix]` Changeset, current authority or standard, latest-stable regression test,
+ representative unchanged paths, downstream proof, and a manifest entry separate
+ from cleanup ids. If the fix lands before final-patch lock, include it in both
+ releases. If it lands after publication or lock, it MAY enter the minor as a
+ disclosed compatible delta; do not recut the final patch solely for bookkeeping.
+ CI MUST independently prove patch eligibility. Release notes separate cleanup from
+ compatible fixes.
+- **FR41 — Records use closed schemas.** The declaration schema preserves the existing
+ primary Changeset tag and adds separate compatibility classification and lifecycle
+ fields. Deprecations require `DEP-*` and `CLN-*`; incompatible fixes require
+ `IFIX-*` and `CLN-*`; the minor plan carries baseline receipts, cleanup items,
+ compatible fixes, release-metadata deltas, owner approval, exact-main gates, and
+ rollback; and the equivalence receipt carries final and candidate digests plus
+ `unclassifiedDeltas`. Unknown fields, duplicate ids, reused cleanup ids, missing
+ evidence, tag/classification contradictions, and one delta mapped more or less than
+ once fail.
+- **FR42 — Contributors declare compatibility intent once.** Every pull request and its
+ Changesets share one machine-readable declaration with the existing primary tag,
+ classification, authority, affected surface kinds, experimental ids, deprecation
+ ids, correction ids, cleanup ids, and minor plan. Closed classifications are
+ `not-published`, `compatible`, `contract-restoring`, `experimental`, `deprecation`,
+ `planned-removal`, and `incompatible-fix`. Classification is orthogonal to the
+ established tag and MUST NOT introduce `[deprecation]` or `[incompatible-fix]` as
+ authoring categories. Existing Changesets need no backfill. Contributors state
+ intent; maintainers resolve missing authority. External contributors are not
+ required to invent policy.
+- **FR43 — CI validates semantics, not labels.** Pull-request CI compares latest
+ stable to head to establish released victims and base to head to attribute deltas.
+ Release CI compares final patch to paired minor and assigns every delta exactly once
+ to cleanup, release metadata, or compatible fix. It checks exports/types, runtime,
+ CSS/tokens, DOM/accessibility/visual/RTL, CLI/help/routes/schema, persistence, docs,
+ package files, supported package combinations, old-client/new-metadata behavior,
+ fixed-group membership, required evidence, and tag/classification/bump coupling.
+ Plain failures name the victim, missing evidence, and exact repair path.
+- **FR44 — Exact-main release gates and rollback preserve one identity.** The final
+ patch and paired minor each use one immutable source identity for build, package
+ artifacts, gate receipts, tag, publish, and release record. Missing authority,
+ manifest coverage, required migration, exact-main evidence, or any unclassified
+ delta aborts the cut. Partial publishing resumes the same bytes. A bad release rolls
+ forward with a compatible patch that restores aliases or the prior safe
+ compatibility mode; critical-harm recovery follows FR35 and never restores the
+ harmful behavior.
### Platform support
@@ -310,80 +523,100 @@ independent for each invocation.
- Browser evidence: not applicable to the classification itself; a browser-owned
compatibility claim still follows the governing component or platform spec.
+## Authority relationships
+
+This spec owns compatibility classification, lifecycle state, release-pair delta
+classes, and the evidence that admits them. It delegates narrower questions rather
+than restating them:
+
+- [`spec:AST-002` — Public API admission and operation shape](../AST-002/spec.md)
+ owns whether a public API concept should exist and its semantic shape.
+- [`architecture:public-component-api` — Public component API](../../architecture/public-component-api.md)
+ owns the stable component contract; this spec owns how it evolves.
+- [`architecture:cli-surface` — CLI surface architecture](../../architecture/cli-surface.md)
+ and [`spec:AST-042` — CLI command admission and programmatic parity system spec](../AST-042-cli-command-admission/spec.md)
+ own CLI structure, admission, and parity; this spec owns compatibility and
+ release transition.
+- [`architecture:theme-tokens` — Theme token architecture](../../architecture/theme-tokens.md)
+ owns token semantics; this spec owns compatibility and experimental isolation.
+- [`spec:AST-013` — Browser and platform support system spec](../AST-013/spec.md)
+ owns support floors and fallbacks; this spec owns release treatment of a support
+ reduction.
+- [`spec:AST-035` — Integration template replacement system spec](../AST-035/spec.md)
+ owns template-replacement semantics. This spec classifies each field and behavior
+ against the latest stable release: unpublished replacement-specific surfaces follow
+ FR2, while previously released same-id conflict warning behavior remains stable.
+- [`spec:AST-040` — Evidence-based consumer file modification system spec](../AST-040-consumer-file-modification/spec.md)
+ owns what a codemod may edit and the evidence it requires; this spec owns when a
+ migration must supply one.
+- [`spec:AST-010` — Structured percentage useResizable configuration system spec](../AST-010/spec.md)
+ and [`spec:AST-043` — Date and time input presentation system spec](../AST-043-input-presentation/spec.md)
+ own their concrete mappings and any surface-specific deprecation minimums.
+- [`spec:AST-030` — Positive CI surface routing system spec](../AST-030/spec.md)
+ owns pull-request lane routing; this spec owns the compatibility checks each
+ affected surface must receive and the exact-main release gate.
+- [`spec:AST-039` — Integration contribution descriptor system spec](../AST-039/spec.md)
+ is a related draft, not authority. If promoted, it links its compatibility readers
+ and removals to this lifecycle.
+- The public [Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)
+ owns whole-component Lab-to-Core readiness. Lab remains the private canary-only
+ incubation boundary; this spec owns the compatibility effect of promotion.
+- The public [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions),
+ [Distribution](https://github.com/facebook/astryx/wiki/Distribution), and
+ [Release Process](https://github.com/facebook/astryx/wiki/Release-Process) pages
+ are operational projections. When they discuss compatibility lifecycle, they MUST
+ link here and cannot create competing rules.
+- [`.changeset/config.json`](../../../.changeset/config.json),
+ [`scripts/check-changesets.mjs`](../../../scripts/check-changesets.mjs), and
+ [`.github/workflows/ci.yml`](../../../.github/workflows/ci.yml) implement fixed
+ grouping, declaration validation, and checks. Their current behavior is not policy
+ when it differs from this spec.
+
+The direct current owner decides the intended product contract. This spec decides how
+that contract may change in a stable release. The public Release Process decides how
+an eligible release is operated. A direct spec cannot waive compatibility silently;
+it names the applicable `DEP-*`, `IFIX-*`, and `CLN-*` records when its transition is
+incompatible.
+
## Current-state impact
-The release tooling already enforces `[breaking]` to minor and every other
-category to patch while packages are on `0.x`. The Release Process already limits
-migration obligations to released surfaces. The template contribution guide notes
-that template resolution is exact-match, but that lookup mechanic does not turn a
-slug value into a contractual API.
-
-The repository already isolates whole experimental components in the canary-only
-Lab package, but it has no equivalent boundary for a new prop, callback, hook, or
-type on an existing stable component. This amendment adds that per-surface boundary
-without weakening the component around it. The release tooling and public Release
-Process do not yet support the `[experimental]` category or verify declaration/doc
-markers. Before another surface uses the contract, follow-up implementation must add
-the category to Changeset authoring, CI validation, changelog grouping, and the
-Release Process, with tests that prove even an incompatible experimental-only change
-stays patch-level. Integration-theme contributions are the sole grandfathered
-enrollment and may use existing patch categories until the dedicated category ships.
-Open PR #6615 removes the released `layout` command, which was experimental only in
-practice and carried no contract marker; it remains breaking and is not enrolled by
-this amendment.
-
-This spec supplies the missing classification rule shared by those documents. In
-particular, both CLI-template cases discussed during review are nonbreaking catalog
-updates:
-
-- renaming a template slug changes data about the current template and may make the
- previous value stop resolving; and
-- changing or completely rebuilding the template's emitted starter page updates
- content for future generations without modifying projects that already copied it.
-
-The stable compatibility boundary remains the CLI operation and complete response
-schema, not the individual entries currently present in the template catalog.
-Nested entry fields are public schema even when optional; their type, tests, text
-projection where present, and consumer schema documentation move together.
-
-The CLI already generates command help, README tables, and a machine-readable
-manifest. This amendment extends that discoverability standard to every supported
-behavior, including automatic behavior and controls outside command syntax. Existing
-Astryx-owned environment controls are non-conforming and must move to documented
-commands, options, configuration, or programmatic APIs; this record does not choose
-their individual migrations. Removing an existing variable still follows FR3–FR8:
-a breaking removal needs concrete migration guidance, and silently ignoring the old
-input is not a migration. This record does not authorize any specific global control.
-A future proposal must prove meaningful behavior across every command under FR15 or place the control on the narrower command and API surfaces that own the
-behavior. These decisions change policy only, so they do not change runtime output or
-a published package and require no Changeset.
-
-The existing `debug` setting is the reference behavior for FR20: the app handler
-and every integration handler run, the app first; a throwing handler is skipped
-without affecting the others or the command; `inheritDebug: false` in the
-package's `astryx` field refuses inherited handlers; and a repeated project load
-delivers each event once. Its configuration schema entry states that rule, and
-the `cli/integrations` guide documents the `debug` named export. Draft
-AST-031 details the same model for runtime handler features. No command yet
-reports an effective contributed value with its sources, so existing contributed
-settings do not meet FR20's inspection requirement; this record does not choose
-that command. FR19 applies to new configuration; this amendment does not
-reclassify existing keys.
+Existing classification remains in force. This amendment adds the missing durable
+lifecycle around it:
+
+- stable changes default to compatible patch treatment;
+- experimental containment extends to every public surface kind;
+- deprecations and behavior corrections become machine-readable and cleanup-owned;
+- planned minors use a locked final-patch baseline while admitting only approved
+ cleanup, closed release metadata, and independently patch-compatible fixes;
+- minor frequency remains planning guidance and creates no deprecation or pair wait;
+- contributor declarations preserve established Changeset tags while adding semantic
+ lifecycle metadata and require no migration of existing Changesets; and
+- exact-main release comparison rejects unclassified deltas.
+
+These are specification changes only. They do not alter a published package and need
+no Changeset. Authoring helpers, validators, manifests, compatibility snapshots,
+release workflows, and contributor documentation are follow-up implementation. Until
+they land, maintainers apply these requirements in review and release approval.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |
-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |
-| FR7–FR8 | `pnpm check:changesets` plus migration review | breaking and patch Changesets; codemoddable and non-codemoddable migration | Category and bump diverge, or a breaking release gives no usable migration path |
-| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |
-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |
-| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |
-| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |
-| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |
-| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |
-| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, stable-surface spillover, integration theme | A prose-only marker excludes a stable API, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |
+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |
+| FR7–FR8 | `pnpm check:changesets` plus migration review | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |
+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |
+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |
+| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |
+| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |
+| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |
+| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |
+| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |
+| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |
+| FR28–FR31 | Closed-schema deprecation and cleanup records plus old/new compatibility fixtures | replacement first, warning projections, explicit direct-spec minimum, one-to-one cleanup | Prose creates eligibility, cadence invents a wait, old behavior degrades early, or a cleanup id covers more than one incompatible delta |
+| FR32–FR35 | Latest-stable victim fixture, pre-existing authority, owner reviews, correction record, record-to-surface state mapping, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |
+| FR36–FR40 | Minor plan, locked final-patch receipt, three-way delta classification, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |
+| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |
## Decision log
@@ -561,14 +794,79 @@ Allow those marked surfaces to evolve through `[experimental]` patch releases.
Promotion is a separate `[feat]` decision that moves the settled API onto its stable
surface; after that release the ordinary compatibility rules apply. Never use an
experimental marker to demote an already stable contract. Integration-theme
-contributions are the single grandfathered exception because they shipped before
-this declaration mechanism while still being introduced for early iteration.
+contributions remain the single explicitly recorded grandfathered surface because
+they shipped before this declaration mechanism while still being introduced for early
+iteration.
+
+That retroactive-marker prohibition does not make unpublished additions stable by
+association. Integration-template replacement-specific declarations, selection,
+optional projection, and expanded conflict fields remain pre-publication under FR2;
+their classification is not an experimental enrollment. The already released same-id
+conflict warning behavior remains stable.
Rejected: moving a stable component into Lab to test one new API, scattering
`unstableFoo` names through its ordinary prop namespace, relying on prose warnings
that tooling cannot verify, treating every recently added API as implicitly
experimental, and retroactively marking another released stable surface unstable.
+### DEC-10 — Replacement-first records own deprecation and cleanup
+
+**Reference:** `spec:AST-017/DEC-10`
+**Decider:** `cixzhang`, `2026-09-29`
+
+Keep old and replacement behavior together in the final patch, identify each
+transition with `DEP-*` and `CLN-*`, and permit removal only through the frozen minor
+manifest. Direct authorities may impose a longer transition for their own surfaces;
+release cadence never invents one.
+
+Rejected: prose-only deprecation, silent removal, a global wait inferred from cadence,
+and one cleanup id covering unrelated deltas.
+
+### DEC-11 — Behavior-correcting incompatibility is not an ordinary fix
+
+**Reference:** `spec:AST-017/DEC-11`
+**Decider:** `cixzhang`, `2026-09-29`
+
+A correction with a valid released victim keeps the `[fix]` Changeset tag and adds
+`incompatible-fix` classification, an `IFIX-*` record, and an approved `CLN-*` item.
+Pre-existing authority proves the expected behavior; latest-stable evidence proves the
+victim. A victim-free restoration also uses `[fix]`, with `compatible` or
+`contract-restoring` metadata and patch treatment. FR26 governs the public surface
+while FR34 maps the `IFIX-*` record lifecycle to that surface state.
+
+Rejected: treating every visible correction as breaking, using bare `[fix]` without
+`incompatible-fix` metadata to hide a released victim, inventing an
+`[incompatible-fix]` Changeset tag, or using generic `[breaking]` to avoid correction
+evidence and rollback.
+
+### DEC-12 — The paired minor admits only three delta classes
+
+**Reference:** `spec:AST-017/DEC-12`
+**Decider:** `cixzhang`, `2026-09-29`
+
+Lock the final-patch baseline and classify every paired-minor delta as approved
+cleanup, closed release metadata, or an independently patch-compatible fix. A fix
+that lands after baseline lock may be disclosed in the minor without recutting the
+patch solely for bookkeeping. Keep cleanup and compatible fixes separate in both the
+manifest and release notes.
+
+Rejected: unrelated features, unclassified deltas, an incompatible fix in the
+compatible-fix lane, and strict byte identity that forces a needless replacement
+final patch for an independently valid patch fix.
+
+### DEC-13 — Cadence guides planning; readiness and authority gate the cut
+
+**Reference:** `spec:AST-017/DEC-13`
+**Decider:** `cixzhang`, `2026-09-29`
+
+Plan minor releases generally no more often than once every fourteen calendar days,
+but do not turn that interval into deprecation eligibility or a required wait between
+the final patch and paired minor. A ready, authorized pair may publish sequentially.
+
+Rejected: an inferred elapsed-time gate, a special exception merely to publish a
+ready pair, and using cadence to waive replacement, migration, cleanup, or exact-main
+evidence.
+
## Open questions
None.
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index f2a0c05b9d..81b194620a 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -54,6 +54,9 @@ they are separately named.
- Add a test-specific or build-specific lane for work already owned by an
existing surface.
- Apply changed-surface routing to post-merge `main` CI.
+- Define compatibility semantics or release-pair delta classes. Those belong to
+ [`spec:AST-017`](../AST-017/spec.md); this record routes their checks and owns the
+ exact-main release-check execution boundary.
- Remove required check names, branch protection, merge-queue coverage, or
exact-head owner approval.
- Infer safety from file extensions, directory names, or the absence of a known
diff --git a/docs/specs/AST-040-consumer-file-modification/spec.md b/docs/specs/AST-040-consumer-file-modification/spec.md
index d437298fb7..31979304f3 100644
--- a/docs/specs/AST-040-consumer-file-modification/spec.md
+++ b/docs/specs/AST-040-consumer-file-modification/spec.md
@@ -36,7 +36,10 @@ project, including core, integration, and configuration codemods.
- Creating new files, such as template copies or scaffolding. Their write
confinement stays with `architecture:cli-surface`, and template copy behavior
stays with `spec:AST-028`.
-- Defining individual migrations or their mappings.
+- Defining individual migrations or their mappings. The
+ [Release compatibility and versioning spec](../AST-017/spec.md) owns when a
+ deprecation, planned cleanup, or incompatible fix requires migration evidence;
+ this record owns how a consumer-file transform edits safely.
- Choosing a command for inspecting effective settings; `spec:AST-017` FR20
requires one.
- Equivalent internal implementations remain valid when they satisfy this contract.
diff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.md
index a56329efb0..87372e3724 100644
--- a/docs/specs/AST-042-cli-command-admission/spec.md
+++ b/docs/specs/AST-042-cli-command-admission/spec.md
@@ -38,8 +38,8 @@ function, and the vocabulary that human-readable output may use.
structure.
- Discoverability, environment variables, global options, and configuration.
`spec:AST-017` FR14–FR20 own those rules.
-- Classifying a removal, rename, or behavior change. `spec:AST-017` FR1–FR8 own
- compatibility.
+- Classifying a removal, rename, behavior change, deprecation, or incompatible fix.
+ [`spec:AST-017`](../AST-017/spec.md) owns compatibility and release lifecycle.
- The JSON envelope, error codes, and generated help. `architecture:cli-surface`
INV2, INV3, and INV7 own them.
- Equivalent internal implementations remain valid when they satisfy this contract.
diff --git a/docs/specs/AST-043-input-presentation/spec.md b/docs/specs/AST-043-input-presentation/spec.md
index 092bb1e68b..4f8bf4d05d 100644
--- a/docs/specs/AST-043-input-presentation/spec.md
+++ b/docs/specs/AST-043-input-presentation/spec.md
@@ -43,8 +43,10 @@ contracts, `architecture:public-component-api`, `family:input-fields`,
each component, except the new surfaces DEC-3 approves. Eligibility/fallback
behavior changes only as FR2 states (for `native`).
- Renaming menu/selector `presentation` or their `adaptive` (OQ1).
-- Removing `nativePicker` — breaking under `spec:AST-017`, needs its own
- record. Migration tooling follows `spec:AST-017` FR8 using the FR3 mapping.
+- Removing `nativePicker` — its concrete mapping remains owned here, while the
+ deprecation record, cleanup id, Changeset, paired-minor treatment, and migration
+ evidence follow [`spec:AST-017` FR28–FR44](../AST-017/spec.md) and the codemod
+ follows `spec:AST-040`.
## Requirements