Skip to content

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

TypeScript

docs: define semantic API contract gate (#5787)

Cindy Zhangfb400d4b58e3
diff --git a/docs/contributing/api-conventions.md b/docs/contributing/api-conventions.md
index 04d007b392..dadd1a12a8 100644
--- a/docs/contributing/api-conventions.md
+++ b/docs/contributing/api-conventions.md
@@ -22,17 +22,45 @@ new decisions and record final rulings.
3. Current architecture and accepted system decisions own cross-component rules.
Start with the [public component API architecture](../architecture/public-component-api.md),
the [knowledge contract](../architecture/knowledge-contracts.md), and
- [AST-002: public component prop admission](../specs/AST-002/spec.md).
+ [AST-002: public API admission and operation shape](../specs/AST-002/spec.md).
The `owners` field names who can settle a missing decision. Component source and
-its public `index.ts` own the shipped API. The component's `.doc.mjs` explains
-that API to consumers.
+its public `index.ts` own the shipped API. The component's `.doc.mjs` owns exact
+consumer syntax and reference material. The component spec owns local semantic
+API meaning and guarantees, including public hooks or utilities it explicitly
+co-owns.
The wiki gives broader background: [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)
and [API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration).
Do not copy detailed decisions from those pages into a proposal. Link the current
owner instead.
+## Separate semantic contract from syntax reference
+
+Every public-facing API addition or semantic change updates its canonical owning
+component, family, architecture, or system record. Update the component spec only
+when it owns the changed component-local semantics or explicitly co-owns the
+public hook or utility. The owning record describes what callers mean, observe,
+and may rely on; `.doc.mjs` remains the authority for signatures, prop/reference
+tables, and consumer usage. Do not turn the semantic contract into a second
+syntax catalog.
+
+A component spec inherits every applicable rule from its current family
+contracts. Record only component-local concepts, additions, and explicit
+exceptions. Link an exception to its approving decision instead of copying or
+rewriting the family rule.
+
+A component spec may co-own a colocated public hook or utility when that ownership
+is explicit. Its local semantic contract covers:
+
+- inputs and options, including meaning, defaults, invalid values, and unsupported
+ combinations;
+- outputs and operations, including observable results and guarantees; and
+- side effects, identity, lifetime, resource ownership, and cleanup where relevant.
+
+Link a different canonical owner for any public surface the component spec does
+not own.
+
## Name one concept at a time
| Surface | Convention | Example |
@@ -201,19 +229,102 @@ High-level compositions have a higher bar for new props than utility components.
Before adding a prop, check whether a child, slot, theme target, styling escape
hatch, parent layout, or existing context already owns the distinction.
+## API proposal gate
+
+Classify the change before asking for a new API decision. Use the current contract
+review results from the [knowledge contract](../architecture/knowledge-contracts.md#change-coupling):
+`preserves`, `settled`, `novel-human`, or `out-of-scope`.
+
+A defect fix that restores a current contract or standard is `preserves`. Supply
+focused regression evidence for the broken state and representative unchanged
+states. Do not invent a semantic delta or new API decision. Change consumer docs
+only when usage or a documented promise changes, or when the existing docs would
+otherwise become false.
+
+For a claimed API addition or semantic change, review has two stages:
+
+1. **Mechanical pre-review.** Reject the change now when the pull request lacks a
+ readable semantic before → after or does not update or add the canonical
+ owning record. Component-local semantics update the component spec;
+ family-, architecture-, or system-owned semantics update that owner instead.
+ Also reject a public choice the component can derive or a parallel
+ public/package-internal operation for the same semantic action. Within one
+ module, keep one canonical operation name; the package-internal form may accept
+ wider semantic options than the public contract. Another operation requires a
+ genuinely distinct caller-owned intent and contract.
+2. **Owner judgment.** For a surviving `novel-human` change, present the semantic
+ delta to the linked owner. The gate does not choose the API. The owner accepts,
+ rejects, or refines the meaning and the ruling is recorded in the canonical
+ spec.
+
+### Staged contract coverage
+
+Semantic contract coverage is still incomplete, so the review path must not turn
+missing `current` authority on the canonical owner into a dead end:
+
+1. The contributor or maintainer puts the one-sentence semantic delta in the pull
+ request, identifies the canonical owner by scope, and updates or adds that
+ record. Component-local semantics use the component spec; shared family,
+ architecture, or system semantics use that owner. A draft record is valid
+ context and must identify its intended owner.
+2. Review applies only current component, family, architecture, and system rules.
+ A draft cannot clear the gate or be cited as settled policy; it routes the
+ remaining `novel-human` delta to the owner.
+3. The owner decides in the pull request. Exact-head owner approval settles that
+ pull request only. The accepted contract and evidence remain in the canonical
+ owning record; rejected direction is removed unless it protects a durable
+ boundary.
+4. Promote an owning record to `current` only after its local requirements,
+ verification, relationships, approval, and every applicable acceptance
+ prerequisite in current architecture are complete. For component specs, this
+ includes the historical benchmark and pull-request enforcement required by the
+ current knowledge contract. Only then may later reviews reuse it as `settled`
+ policy.
+
+A follow-up gate may mechanically reject missing `current` authority on a
+canonical owning record only after a current policy change explicitly activates
+enforcement for a named scope, that scope has current contract coverage, and the
+historical benchmark has passed. Until then, missing current authority routes to
+the staged owner path; it does not reject the API by itself.
+
+Mechanical enforcement of this gate is follow-up work; this guide defines the
+review contract, not gate implementation.
+
## API proposal checklist
+Every public-facing API pull request has this minimum readable summary:
+
+- **Owner:** link the canonical owning record and state its authority. Use the
+ component spec only for component-local semantics; use the family, architecture,
+ or system record when it owns the changed semantics. If the owner is draft or
+ missing before this pull request, name the intended owner.
+- **Semantic before → after:** state the caller-visible meaning and guarantee in
+ one sentence.
+- **Classification:** name `preserves`, `settled`, `novel-human`, or
+ `out-of-scope`.
+- **Representative syntax:** include it only when public syntax changes; the
+ component `.doc.mjs` remains the complete syntax/reference authority.
+
Before requesting review:
-- **Find the owner.** Link the nearest current component, family, architecture,
- or system record when it is known. If it is not clear, explain the intended
- behavior normally; the reviewer routes the decision.
- **Prove caller ownership.** Show two otherwise identical cases that need
different outcomes, why the caller knows the difference, and why the component
cannot derive it. This is the admission rule in
[AST-002](../specs/AST-002/spec.md#dec-1--public-props-require-a-non-derivable-caller-distinction).
-- **Show the consumer API.** Include the default, configured or controlled,
- composed, edge, and migration cases that apply.
+- **Update the semantic owner.** Update or add the canonical owning record.
+ Component-local concepts belong in the component spec; shared family,
+ architecture, or system concepts belong in that owner. Record inputs, options,
+ defaults, invalid values and unsupported combinations, outputs, operations,
+ guarantees, and relevant lifetime or resource obligations without copying
+ inherited rules.
+- **Prevent broken states.** Make statically knowable invalid combinations
+ unrepresentable when practical. Otherwise document validation or warnings, or
+ a safe fallback; do not silently render a broken state or block legitimate
+ composition.
+- **Check operation uniqueness.** Within one module, use the same canonical name
+ for public and package-internal forms of one semantic action. The internal form
+ may accept wider options; another operation requires distinct caller-owned
+ intent.
- **Check the shared grammar.** Cover names, optionality, callback/Action order,
cancellation, ref target, DOM pass-through, and whether each string axis is
open or closed.
@@ -223,10 +334,6 @@ Before requesting review:
changes, update consumer docs, public exports, focused runtime and type tests,
and representative integration coverage in the same pull request.
-A bug fix that restores an existing current contract or standard is not a new
-API proposal. Add regression evidence. Change consumer docs only when usage or a
-documented promise changes, or when existing docs would otherwise become false.
-
If two or three viable shapes remain after applying current conventions, use the
[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)
process. Compare realistic consumer code across the relevant cases and put the
@@ -236,6 +343,10 @@ out of architecture records.
## Common review smells
+- A public API change has no semantic delta in its canonical owning record, so
+ reviewers must infer meaning from implementation or syntax.
+- One module gives the same semantic action separate public and package-internal
+ operation names because an internal caller needs wider options.
- A prop exposes a value the component can derive from state, content, layout,
context, or the platform.
- A high-level component accumulates tuning props or duplicates a child's state.
diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.md
index f99ccf6a50..b648c406df 100644
--- a/docs/specs/AST-002/spec.md
+++ b/docs/specs/AST-002/spec.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-08-30
+approved_at: 2026-08-31
phase: accepted
owners: [cixzhang, imdreamrunner]
affects_architecture: []
@@ -16,19 +16,19 @@ affects_contributing: [contributing:api-conventions]
affects_consumer_docs: []
---
-# Public component prop admission
+# Public API admission and operation shape
## Intent
-Keep Astryx public APIs intentional. A prop should represent a distinction the
-caller owns, not expose a choice the component can make correctly by itself.
+Keep Astryx public APIs intentional. A public API should represent a distinction
+the caller owns, not expose a choice the component can make correctly by itself.
That need is only the first gate. The proposed API must also have clear meaning,
dependable behavior, and promises the component can keep.
-Every public prop becomes a permanent concept that consumers, documentation,
-tests, themes, migrations, and reviewers must understand. The burden is to show
-why the caller must provide information, not merely that a prop can solve the
-immediate example.
+Every public prop, hook, utility, and operation becomes a permanent concept that
+consumers, documentation, tests, themes, migrations, and reviewers must
+understand. The burden is to show why the caller must provide information, not
+merely that an API can solve the immediate example.
## Non-goals
@@ -36,11 +36,11 @@ immediate example.
- Preventing utility components from exposing the fine-grained controls that are
their purpose.
- Replacing existing styling escape hatches with component-specific layout props.
-- Rejecting a prop only because its implementation is difficult.
+- Rejecting an API only because its implementation is difficult.
## Requirements
-A new prop is admitted only when it passes both gates:
+A public API proposal is admitted only when it passes both gates:
1. **Need:** the caller owns information the component cannot derive.
2. **Contract:** the API clearly describes a dependable result the component can
@@ -82,29 +82,90 @@ A new prop is admitted only when it passes both gates:
behavior, and required visual communication do not become valid only when an
unverified external condition is assumed. Solve the base component problem
before adding API to select between incomplete solutions.
+- **FR11 — One semantic action has one canonical operation.** Within one
+ component module, any public or package-internal operations that implement the
+ same caller-owned action use one canonical operation name. The public contract
+ may expose a narrower option set while the package-internal implementation
+ accepts wider semantic options under that same operation. Add another operation
+ only for genuinely distinct caller-owned intent with a different contract.
+- **FR12 — Mechanical screening does not outrun contract coverage.** Every API
+ addition or semantic change is rejected now when the pull request lacks a
+ readable semantic delta or fails to update or add the canonical owning record.
+ Component-local semantics belong in the component spec; family-, architecture-,
+ or system-owned semantics update that owner instead. A draft record is valid
+ review context but not policy. Mechanical review also rejects derivable choices
+ and duplicate operations now. Only rejection because the canonical owner lacks
+ `current` authority is deferred until a current policy explicitly activates
+ coverage enforcement for the affected scope.
+- **FR13 — Surviving changes make the semantic delta explicit.** Owner review
+ receives a link to the canonical owner, one sentence stating the semantic
+ before → after, the applicable review classification, and representative syntax
+ only when public syntax changes.
+- **FR14 — Contract restorations are preserves.** A fix that restores a current
+ contract or standard is classified `preserves` and supplies regression evidence.
+ It does not create a new API decision or semantic spec delta unless consumer
+ usage or a documented promise also changes.
+- **FR15 — Invalid states are prevented where practical.** Public APIs prevent
+ bad results when doing so does not make the API harder to understand. Make
+ statically knowable invalid combinations unrepresentable where practical;
+ otherwise validate or warn, or choose a safe documented fallback. Do not
+ silently render a broken state or over-constrain legitimate composition.
### Platform support
-- Supported feature/engine floor: the rule applies to every exported component
- API on every supported renderer.
+- Supported feature/engine floor: the rule applies to every exported component,
+ hook, and utility API on every supported renderer.
- Unsupported behavior: a browser or renderer implementation limitation is not
- itself evidence that callers should receive a permanent prop.
+ itself evidence that callers should receive a permanent API.
- Browser evidence: layout-based derivability claims are verified in real
- supported browsers before concluding that a prop is necessary.
+ supported browsers before concluding that public API is necessary.
## Current-state impact
- API review guidance must require both the caller-need argument and the
- dependable-contract argument before new props are accepted.
-- Before this rule is used as an automated or routine blocking gate, a blinded
- historical benchmark must measure both correct pauses and false blocks. A
- pattern of pausing clearly justified APIs means the rule needs refinement.
-- Component-spec public concepts should record caller ownership, why the
- distinction is not derivable, the observable result, and how the component can
- keep the promise.
-- Existing props are not removed automatically. They are evaluated when touched,
- when an adjacent prop is proposed, or when they cause a concrete maintenance or
- consistency problem.
+ dependable-contract argument before new public API is accepted.
+- Before broad rejection for missing `current` authority on a canonical owning
+ record is activated, a blinded historical benchmark must measure both correct
+ pauses and false blocks. A pattern of pausing clearly justified APIs means the
+ gate needs refinement.
+- Component specs own component-local semantic API contracts, including public
+ hooks and utilities they explicitly co-own. Family, architecture, and system
+ records own their respective shared semantics. The component's `.doc.mjs`
+ remains the consumer syntax and reference authority.
+- Component specs inherit current family contracts and record only local public
+ concepts, additions, and explicit exceptions; they do not copy shared rules.
+
+### Staged contract coverage
+
+Semantic contract coverage is incomplete. During the staged rollout:
+
+1. The pull request states the semantic before → after, identifies the canonical
+ owner by scope, and updates or adds that record. Component-local semantics use
+ the component spec; shared family, architecture, or system semantics use that
+ owner. A draft record is acceptable review context and names its intended
+ owner, but it is not policy.
+2. Review applies only current component, family, architecture, and system rules.
+ A draft routes an unresolved `novel-human` delta to the owner; it cannot clear
+ the gate or be cited as `settled`.
+3. The owner decides in the pull request. Exact-head owner approval settles only
+ that change. An accepted contract and its evidence remain in the canonical
+ owning record; rejected direction is removed unless it protects a durable
+ boundary.
+4. An owning record becomes `current` only after its local requirements,
+ verification, relationships, approval, and every applicable acceptance
+ prerequisite in current architecture are complete. For component specs, this
+ includes the historical benchmark and pull-request enforcement required by the
+ current knowledge contract. Only then can later reviews reuse it as policy.
+
+Missing `current` authority on a canonical owning record becomes a mechanical
+rejection only after a current policy change explicitly activates enforcement for
+a named scope, that scope has current contract coverage, and the historical
+benchmark has passed. Until then, missing current authority uses the staged owner
+path rather than rejecting the API.
+
+- Existing props and operations are not removed automatically. They are evaluated
+ when touched, when adjacent API is proposed, or when they cause a concrete
+ maintenance or consistency problem.
- The proposed PowerSearch editor-popover maximum width is the motivating case
for the need gate: its width is an internal resolved design choice rather than
a caller-owned distinction, so a new public tuning prop does not pass.
@@ -112,17 +173,27 @@ A new prop is admitted only when it passes both gates:
or other behavior its mechanism cannot perform. Solve the component behavior
first; consider API only when a clear, enforceable caller-owned distinction
remains.
+- [PR #5373](https://github.com/facebook/astryx/pull/5373) is evidence that
+ parallel public and package-internal operations for one semantic action create
+ avoidable surface area. Its particular operation names and options are not
+ policy.
+- Implementing the mechanical API gate and its benchmark is follow-up work. This
+ policy and template change does not add gate implementation code.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |
-| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |
-| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |
-| FR7, FR8 | Consumer examples and behavior tests | default, each public value, composed use, and unsupported use | Meaning depends on implementation knowledge or tests assert only classes/data attributes |
-| FR9, FR10 | Component ownership and accessibility review | owned content, external sibling content, missing or incorrect context | A state is correct only when the caller fulfills a promise the component cannot verify |
-| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ---------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |
+| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |
+| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |
+| FR7, FR8 | Consumer examples and behavior tests | default, each public value, composed use, and unsupported use | Meaning depends on implementation knowledge or tests assert only classes/data attributes |
+| FR9, FR10 | Component ownership and accessibility review | owned content, external sibling content, missing or incorrect context | A state is correct only when the caller fulfills a promise the component cannot verify |
+| FR11 | Public and package-internal operation inventory; PR #5373 | one component module and one semantic action | One semantic action gains parallel operation names distinguished only by implementation needs |
+| FR12, FR13 | PR delta/canonical-owner update check, staged owner routing, and blinded benchmark | missing delta/update, draft or current authority, and owner-ready delta | Missing delta/owner update passes, missing current authority dead-ends rollout, draft becomes policy, or automation decides semantics |
+| FR14 | Focused regression tests against the current contract or standard | defect state and representative unchanged states | A restoration invents a new decision or lacks evidence that the regression stays fixed |
+| FR15 | Type-level constraints plus runtime validation and behavior tests | invalid values, unsupported combinations, and legitimate composition | The API silently renders a broken state or prevents a valid composition |
+| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |
## Decision log
@@ -154,6 +225,65 @@ association, or validation meaning its mechanism cannot provide. Solve the base
component behavior first; consider public API only when a clear, enforceable
caller-owned distinction remains.
+### DEC-3 — One semantic action uses one canonical operation name
+
+**Reference:** `spec:AST-002/DEC-3`
+**Decider:** `cixzhang`, `2026-08-31`
+
+A component module uses one canonical operation name for one semantic action across
+its public and package-internal forms. The public contract may expose a narrower
+option set while the package-internal implementation accepts wider semantic
+options under that same name. A second operation is admitted only for genuinely
+distinct caller-owned intent and contract.
+
+Rejected: creating a parallel operation because one internal call path needs
+additional control. That choice exposes internal call-path differences and leaves
+maintainers or consumers to distinguish two names for one action.
+
+### DEC-4 — API review separates objective rejection from owner judgment
+
+**Reference:** `spec:AST-002/DEC-4`
+**Decider:** `cixzhang`, `2026-08-31`
+
+The API gate rejects a missing PR-readable semantic delta, a missing canonical-
+owner-record update, a derivable implementation choice, or duplicate operation
+names for one semantic action now. Component-local semantics update the component
+spec; shared semantics update their family, architecture, or system owner. During
+rollout, that canonical record may be draft context routed to its owner; draft
+context never becomes policy. Only rejection because the canonical owner lacks
+`current` authority waits for a later current policy that activates enforcement
+for a covered, benchmarked scope. A surviving proposal is presented as an
+explicit semantic delta for the human owner to accept, reject, or refine.
+Automation does not make that judgment.
+
+Rejected: asking owners to discover both mechanical defects and the intended
+semantic change from implementation code, or rejecting all API work until every
+component contract is current. Either path wastes human judgment or dead-ends the
+coverage rollout.
+
+### DEC-5 — Semantic contracts apply now; broad coverage rejection activates later
+
+**Reference:** `spec:AST-002/DEC-5`
+**Decider:** `cixzhang`, `2026-08-31`
+
+Semantic API contracts apply now at their canonical owner, and the one-canonical-
+operation rule applies now to public and package-internal forms of the same
+semantic action. API changes that lack a PR-readable semantic delta or fail to
+update or add the canonical owning record are rejected now. Component-local
+semantics use the component spec; family-, architecture-, or system-owned
+semantics use that record. The canonical record may remain draft context routed
+to its owner.
+
+Broad mechanical rejection because that canonical owner lacks `current`
+authority is not active. It requires a later current policy decision that names
+the enforced scope after that scope has current contract coverage and the
+historical benchmark shows the gate can block changes without unacceptable false
+rejections.
+
+Rejected: delaying semantic contract ownership until every owning record is
+current, or treating this decision as immediate authorization to reject every API
+change whose canonical owner is draft or missing.
+
## Open questions
None.
diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.md
index c0b37b83c9..94e56c5e9e 100644
--- a/docs/templates/knowledge/component-spec.md
+++ b/docs/templates/knowledge/component-spec.md
@@ -45,7 +45,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-<!-- Concepts, not a prop table. Consumer syntax/defaults remain in <Name>.doc.mjs. -->
+<!--
+Concepts, not a prop table. Consumer syntax/defaults remain in <Name>.doc.mjs.
+Record only component-local semantic concepts, additions, and exceptions; inherit
+current family rules. For an explicitly co-owned public hook or utility, cover
+semantic inputs/outputs and lifetime/resource behavior through concept rows and
+linked local requirements. Follow spec:AST-002 without copying system rules.
+-->
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
| ----------- | ----------------------- | ----------- | ----------------------------------------- | ----------- | ------------------ | -------------------------- | ------------------------------- |