An open source design system that's fully customizable and agent ready
TypeScript
docs: require authority for every public delta (#6094)
Cindy Zhangac0c06e6958a
diff --git a/docs/README.md b/docs/README.mdindex fb1bff49cf..00b36731ea 100644--- a/docs/README.md+++ b/docs/README.md@@ -53,6 +53,10 @@ Every knowledge record declares `authority: draft | current | archived`.through GitHub review. When an approver is also the PR author, they comment`/approve-spec <full-head-sha>`. Any new commit invalidates that approval.- Only `current` documents guide implementation and review.+- A specification describes durable ideal behavior independently of any one pull+ request. Pull requests and issues may appear only as clearly non-authoritative+ examples, historical evidence, or references. A specification never exists to+ approve, reject, classify, designate, or authorize a particular pull request.- Current records rely only on other current records. `modules` and`parent_component` are structural ownership links, so they may connect activedraft/current records without making draft behavior authoritative. Other draftdiff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 7f053aae67..8d4c632ca4 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -111,6 +111,19 @@ Every record is either:private release or automation systems.- **INV9 — Current records have no implicit precedence.** A newer, narrower, ormore local current record does not silently override another current record.+- **INV10 — Records describe ideal behavior, not pull-request verdicts.** A current+ record states durable requirements, prohibitions, compatibility, ownership, and+ evidence independently of any one implementation change. It never exists to+ approve a pull request and never approves, rejects, classifies, designates, or+ authorizes a specific one. Pull requests and issues may appear only as clearly+ non-authoritative examples, historical evidence, or references; the rule must+ remain complete without them. The reviewer owns each change's disposition+ against current authority.+- **INV11 — Every public delta has an authority result.** Every public API update+ and every public behavior change is matched to current committed authority+ before acceptance. Package-export shape is not the only trigger: reachable+ supporting types, context members, hook returns, defaults, and observable+ behavior participate too.## Writing specifications and contracts@@ -200,15 +213,25 @@ Before any component, module, family, design, theme, or architecture record beco1. The record names the code surface that can affect it and the checks thatverify it.2. A pull request touching that surface triggers a focused contract review.-3. The review records one of four results:- - `preserves`: the change still satisfies the current contract;- - `settled`: an existing human decision applies and is cited;- - `novel-human`: the contract needs a new human decision;+3. The review records one of five results:+ - `preserves`: the exact delta restores or retains current authority without+ adding public API or behavior beyond it;+ - `settled`: an existing current human decision covers the exact delta and is+ cited;+ - `violates`: the exact delta contradicts current authority;+ - `novel-human`: no current authority settles the exact public API, behavior,+ ownership, compatibility, or design delta; or- `out-of-scope`: another component, module, family, system, or product owns it.-4. `preserves` and `settled` proceed without asking the human again.-5. `novel-human` remains blocked until the owning record contains the new- decision and receives approval.-6. Audit freshness is computed from the same code and test relationship, so a+4. `preserves` and `settled` enter normal correctness review. They are eligible+ for approval only when the implementation and evidence also pass.+5. `violates` receives request-changes. The implementation conforms to current+ authority, or an owner-approved current spec update lands before acceptance.+6. `novel-human` enters a private human hold. No contributor-facing verdict or+ approval is published until the owning record contains the exact decision and+ becomes current.+7. A bug fix is `preserves` only when it restores existing current authority+ without changing public API or public behavior beyond that contract.+8. Audit freshness is computed from the same code and test relationship, so arelevant code change cannot leave an audit looking current.### Recording a new human decision@@ -256,12 +279,15 @@ Examples:- NumberInput changes its stepping math. Its current contract says the finaloperation clamps to `min`/`max`, and the mapped tests still pass. Result:- `preserves`; no human question and no spec edit.+ `preserves`; continue to normal correctness review with no human question.- A new NumberInput path uses the same previously approved transformation order.- Result: `settled`; cite that `DEC` and continue without asking again.+ Result: `settled`; cite that `DEC` and continue to normal correctness review.+- A package-exported context changes a required function parameter while its+ current contract preserves the earlier operation shape. Result: `violates`;+ request changes or land an owner-approved compatibility decision first.- Selector removes empty indicator space, but no current decision says whether- option labels must stay aligned. Result: `novel-human`; the reviewer asks the- alignment question and records the answer in Selector's contract.+ option labels must stay aligned. Result: `novel-human`; hold privately while the+ owner decides and records the alignment contract.- A product requests a one-off width prop for a family-owned input layout rule.Result: `out-of-scope`; route the change to the family contract rather thancreating a component-specific API.@@ -336,4 +362,5 @@ work.| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes || INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only || Approval follows the current head | `.github/scripts/spec-owner-decision.test.mjs` | An approval for another commit clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current theme record |-| INV3, INV4 | Blinded historical review benchmark | Reviewer re-asks a settled decision or invents a new one |+| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |+| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 28e925c732..72a132710e 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -94,17 +94,33 @@ guidance owns the process used to propose and test APIs.CSS property set cannot express. Its theming record owns the exact purpose,stable default/fallback, scope, documentation, evidence, and compatibilitycontract; an internal styling gap alone does not justify public API.+- **INV12 — Reachability outranks internal labels.** A type, context member, hook+ return, utility signature, default, or operation reachable from a supported+ package path is public even when its source comment, filename, or current use+ calls it internal. Privacy requires removing the export or moving the capability+ behind a non-exported boundary.+- **INV13 — Public deltas route to their authority owner.** Every public API update+ and every public behavior change follows the result and disposition defined by+ `architecture:knowledge-contracts`. Tests, a Changeset, or a generated manifest+ are evidence; none can settle an absent or contradictory contract.This record applies to stable public packages. Lab components are not stablepublic promises until promotion.## Change coupling-- Adding or changing an exported prop, type, default, package entry point, ref- target, or intentional observable contract triggers public-API review.-- A bug fix that restores an existing current contract or standard is- `preserves`. It requires regression evidence, but it does not create a new API- decision.+- Adding or changing an exported prop, supporting type, context member, hook+ return, operation signature, default, package entry point, ref target, or+ intentional observable contract triggers public-API review. A top-level export+ need not change for a reachable supporting contract to change.+- Each review compares declarations and reachable exports from merge-base to head+ and from current main to the synthetic merge. The generated surface manifest+ inventories evidence and maps each row to its canonical component, family,+ architecture, or system owner; it does not decide acceptance.+- After the generated surface inventory identifies the exact API and behavior+ delta and its canonical owner, route it under+ `architecture:knowledge-contracts`. This record does not redefine review results+ or PR disposition.- Consumer docs change when consumer usage or a documented promise changes, orwhen the existing docs would otherwise become false. Fixing an implementationdefect does not by itself require consumer-doc changes.@@ -143,20 +159,25 @@ copy the component matrix.## Verification-| Invariant | Evidence | Failure signal |-| ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |-| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element |-| INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API |-| INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice |-| INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose |-| INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |-| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail |-| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |+| Invariant | Evidence | Failure signal |+| ----------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |+| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element |+| INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API |+| INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice |+| INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose |+| INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |+| INV12, INV13 | Generated declaration/export/behavior inventory plus canonical-owner mapping | A reachable supporting type or behavior is called internal, or mechanical evidence is treated as permission to accept it |+| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail |+| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |Known verification gaps:- The passthrough lint is warning-only while known violations remain.- The current source-to-doc completeness matcher still looks for old prefixedprops interfaces, so it does not yet prove full prop coverage.+- No checked-in generated manifest currently proves the complete reachable public+ delta across supporting types, context members, hook returns, utility signatures,+ defaults, CLI schemas, and observable behavior for both the branch and synthetic+ merge. Reviews must build that inventory explicitly until enforcement exists.These gaps are named here rather than treating partial checks as complete proof.diff --git a/docs/contributing/api-conventions.md b/docs/contributing/api-conventions.mdindex 028f5cded7..33e32de602 100644--- a/docs/contributing/api-conventions.md+++ b/docs/contributing/api-conventions.md@@ -309,73 +309,44 @@ 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, a public input whose- controlled axis changes by value or input shape, hidden conditional precedence- between parallel inputs, or a parallel public/package-internal operation for- the same semantic action. A cohesive semantic status or variant may derive- several visual details; it is rejected only when its public meaning is unstable- or undisclosed. 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. These current AST-002 rules apply even when the canonical owner- is draft or missing; only rejection because that owner lacks `current`- authority remains deferred under staged coverage.-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. This staged-exception applies only to authority coverage; it does not defer rejection under-current cross-component rules, including the overloaded-input and hidden--precedence rule above:--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.+Classify the change after identifying current authority. The+[knowledge contract](../architecture/knowledge-contracts.md#change-coupling) owns+the five results and their disposition: `preserves`, `settled`, `violates`,+`novel-human`, and `out-of-scope`. This guide applies those results; it does not+redefine them.++A defect fix is `preserves` only when it restores a current contract or standard+without adding public API or public behavior beyond that authority. Supply focused+regression evidence for the broken state and representative unchanged states. Any+additional public delta is classified independently through the knowledge+contract: existing current authority may settle it, and only absent authority uses+the unsettled owner path. The bug-fix label never bypasses API design.++For a claimed API addition or semantic behavior change, review has four stages:++1. **Inventory the public delta.** State the exact semantic before → after,+ identify the canonical owner by scope, and include supporting declarations,+ types, context fields, hook returns, defaults, and observable behavior reachable+ from supported package paths.+2. **Apply API admission.** Reject a public choice the component can derive, a+ public input whose controlled axis changes by value or input shape, hidden+ conditional precedence between parallel inputs, or a parallel public/package-+ internal operation for the same semantic action. A cohesive semantic status or+ variant may derive several visual details when its public meaning stays stable+ and disclosed. Within one module, keep one canonical operation name; another+ requires genuinely distinct caller-owned intent and contract.+3. **Apply current authority.** Follow the result and disposition owned by the+ knowledge contract. A draft is useful review context but is not policy and+ cannot clear the gate. Exact-head owner discussion or approval is decision+ evidence; an accepted decision must be committed in the canonical record as+ `current` before implementation acceptance.+4. **Review implementation correctness.** Once current authority settles the+ public contract, verify the exact implementation head, regression evidence,+ compatibility, migration, docs, and representative unchanged states.++Mechanical manifests and receipts may inventory the delta and prove which+current record was read. They are evidence only; they do not choose semantics or+assign pull-request disposition.## API proposal checklist@@ -387,8 +358,8 @@ Every public-facing API pull request has this minimum readable summary:missing before this pull request, name the intended owner.- **Semantic before → after:** state the caller-visible meaning and guarantee inone sentence.-- **Classification:** name `preserves`, `settled`, `novel-human`, or- `out-of-scope`.+- **Classification:** name `preserves`, `settled`, `violates`, `novel-human`, or+ `out-of-scope` as defined by the knowledge contract.- **Representative syntax:** include it only when public syntax changes; thecomponent `.doc.mjs` remains the complete syntax/reference authority.diff --git a/docs/families/input-fields.md b/docs/families/input-fields.mdindex 0d61d32ee4..514d8aefdc 100644--- a/docs/families/input-fields.md+++ b/docs/families/input-fields.md@@ -235,16 +235,17 @@ another implementation helper.`aria-busy`; selected, source-busy, and grouped combinations do not have thefocused geometry coverage required by FR1–FR3 and FR7. PRs[#5555](https://github.com/facebook/astryx/pull/5555) and- [#5682](https://github.com/facebook/astryx/pull/5682) are implementation- candidates, not authority. Their in-flow Typeahead approach is compatible with- this contract; the specific DOM/CSS mechanism remains component-owned.+ [#5682](https://github.com/facebook/astryx/pull/5682) document attempted+ implementations and are non-authoritative evidence. Any implementation keeps its+ DOM/CSS mechanism component-owned and must be reviewed against this contract at+ its exact head.- **Tokenizer state geometry:** current main positions `endContent` and clearcontrols out of flow without reserving their rendered width, so narrow inputcontent can pass underneath them. Token count can also change intrinsic- inline size. PR #5555 proposes a component-local reserve. Tokenizer is not an- InputGroup-compatible child on current main; [#4405](https://github.com/facebook/astryx/pull/4405)- is a separate adoption proposal and its single-row overflow treatment is not- approved by this family.+ inline size. PR #5555 is non-authoritative evidence of an attempted component-+ local reserve. Tokenizer is not an InputGroup-compatible child on current main;+ [#4405](https://github.com/facebook/astryx/pull/4405) is separate historical+ evidence. This family contract does not assign either pull request a verdict.- **Selector source-state semantics:** Selector and MultiSelector keep providedoptions available while input `isLoading` is true, but current empty/no-resultpresentation still treats that flag as option-source pending and neither@@ -262,13 +263,14 @@ another implementation helper.omit tooltip or the whole status-placement projection even though Fieldconsumes the family sentinel. Follow-up work must make attached capability andthe three input-level choices accurate in each member's API and docs.-- **Attached FieldStatus overlap:** PR- [#5769](https://github.com/facebook/astryx/pull/5769) expands overlap from a- descendant `data-size`, which does not establish that the direct control is- eligible or that its owning root reliably reflects the resolved size. The- implementation must preserve attached for eligible members while unsupported- wrapped, custom, tall, and translucent surfaces retain component-owned- placement, normally detached.+- **Attached FieldStatus overlap:** attached placement is limited to eligible+ members whose direct control and owning root reliably expose resolved size.+ Eligible members preserve attached placement; unsupported wrapped, custom, tall,+ and translucent surfaces retain component-owned placement, normally detached.+ [PR #5769](https://github.com/facebook/astryx/pull/5769) is non-authoritative+ evidence of an attempted implementation that derives overlap from a descendant+ `data-size`; that mechanism does not by itself establish eligibility or root-size+ ownership.- **Verification coverage:** current unit tests prove composition, semantics, andindividual state behavior, but do not yet provide the complete real-browserinline-size/end-overlap matrix below. This current record names thosediff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.mdindex b698f1cd9e..0b84a6d12f 100644--- a/docs/specs/AST-002/spec.md+++ b/docs/specs/AST-002/spec.md@@ -88,24 +88,23 @@ A public API proposal is admitted only when it passes both gates:may expose a narrower option set while the package-internal implementationaccepts wider semantic options under that same operation. Add another operationonly 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,- overloaded inputs, hidden conditional precedence, 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.+- **FR12 — Mechanical screening does not outrun contract coverage.** Every public+ API addition or semantic behavior change identifies its exact before → after,+ canonical owner, and applicable current record before acceptance. 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 and cannot clear the authority gate. Mechanical review also rejects+ derivable choices, overloaded inputs, hidden conditional precedence, and+ duplicate operations.- **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.+ receives a link to the canonical current owner, one sentence stating the semantic+ before → after, the applicable authority result from+ `architecture:knowledge-contracts`, and representative syntax only when public+ syntax changes.+- **FR14 — Contract restorations are preserves.** A fix is `preserves` only when it+ restores a current contract or standard and adds no public API or public behavior+ beyond that authority. It supplies regression evidence. Any additional public+ delta independently follows FR12 even when delivered in a bug-fix pull request.- **FR15 — Invalid states are prevented where practical.** Public APIs preventbad results when doing so does not make the API harder to understand. Makestatically knowable invalid combinations unrepresentable where practical;@@ -141,6 +140,21 @@ A public API proposal is admitted only when it passes both gates:command verbs and their programmatic command twins belong to the[CLI surface architecture](../../architecture/cli-surface.md) and CLIconventions; this requirement does not define their command semantics.+- **FR18 — Public primitives support composition intentionally.** Astryx prefers+ public contracts for stable behavior that product builders must compose,+ coordinate, or build on across callsites. That preference does not promote raw+ implementation machinery. A proposed primitive API names semantic caller intent,+ defines accepted and rejected operations and outcomes, and receives an owning+ current contract before acceptance. Internal focus targets, gesture memory, DOM+ slots, timers, and equivalent mechanisms stay private unless independently+ admitted as durable caller-owned concepts.+- **FR19 — Bug fixes do not smuggle API design.** A bug fix that can restore current+ behavior without changing public API or behavior beyond current authority MUST do+ so. Any additional public delta follows `architecture:knowledge-contracts`+ independently: existing current authority may already settle it, and only absent+ authority requires a new owner decision. Implementation convenience, removal of+ an internal wrapper, or exposure of existing internal fields is not evidence that+ an API should exist.### Platform support@@ -153,16 +167,14 @@ A public API proposal is admitted only when it passes both gates:## Current-state impact-- API review guidance must require both the caller-need argument and the- dependable-contract argument before new public API is accepted.-- Public API additions and semantic changes that overload an input or create- hidden conditional precedence are rejected now under FR16, even when the- canonical owner is draft or missing. Missing `current` authority alone remains- staged and non-blocking.-- 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.+- API review guidance requires both the caller-need argument and the dependable+ current-contract argument before new public API is accepted.+- Every public API addition and public behavior change identifies current committed+ authority, then follows the result and disposition owned by+ `architecture:knowledge-contracts`. This spec does not redefine those outcomes.+- Exact-head owner discussion or approval may supply the decision evidence, but it+ does not become reusable or acceptance-clearing authority until the canonical+ owning record commits that decision as `current`.- Component specs own component-local semantic API contracts, including publichooks and utilities they explicitly co-own. Family, architecture, and systemrecords own their respective shared semantics. The component's `.doc.mjs`@@ -175,37 +187,21 @@ A public API proposal is admitted only when it passes both gates:Existing released mismatches remain compatible while an explicit deprecation andmigration is designed; this rule does not silently rename or change them.-### 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.--That deferral applies only to authority coverage. It does not defer current-cross-component rules: an API addition or semantic change that violates FR16 is-rejected now even when its canonical component owner is draft or missing.+### Current authority dependency++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.++A draft record may provide context and route the unresolved question, but it+cannot clear current authority. Exact-head owner discussion supplies decision+evidence; the canonical record must commit an accepted decision as `current`+before implementation acceptance.++This authority dependency does not make public API undesirable. Once current+authority settles the semantic contract, ordinary correctness and evidence review+still determine whether the implementation satisfies it.- Existing props and operations are not removed automatically. They are evaluatedwhen touched, when adjacent API is proposed, or when they cause a concrete@@ -240,11 +236,13 @@ rejected now even when its canonical component owner is draft or missing.| 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 |+| FR12, FR13 | Public-delta/canonical-owner check and exact authority routing | missing delta/update; matching, contradictory, draft-only, or absent authority | Missing delta/owner update passes, contradiction is accepted, draft becomes policy, or automation decides semantics |+| FR14 | Focused regression tests against the current contract or standard | defect state, representative unchanged states, and any adjacent public delta | A restoration invents a new decision, lacks regression evidence, or hides an additional public change under a bug-fix label || 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 || FR16 | Full value-domain, input-shape, and parallel-combination contract review | semantic variants, raw or palette values, explicit overrides, and defaults | One value or shape switches the controlled axis, or a parallel input silently changes precedence || FR17 | Public module/utility export inventory plus implementation, test, consumer, and release-history review | construction, inspection, lookup, conversion, registration, hooks, and released compatibility | A verb hides the returned value or side effect, two public roles are fused, a non-hook utility uses `use*`, or a released mismatch is silently renamed |+| FR18 | Multi-caller composition scenarios plus owning-contract review | shared semantic operation, internal-only mechanism, and two representative consumers | Product builders cannot compose stable behavior, or implementation fields are exposed without caller-owned semantics |+| FR19 | Bug-fix before/after authority diff plus public-surface and behavior inventory | pure restoration, restoration plus novel API, and internal-wrapper removal | A bug-fix label bypasses human hold, or internal mechanics become public because exposure is convenient || 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@@ -292,49 +290,44 @@ Rejected: creating a parallel operation because one internal call path needsadditional control. That choice exposes internal call-path differences and leavesmaintainers or consumers to distinguish two names for one action.-### DEC-4 — API review separates objective rejection from owner judgment+### DEC-4 — API review separates mechanical evidence from owner judgment**Reference:** `spec:AST-002/DEC-4`-**Decider:** `cixzhang`, `2026-08-31`+**Decider:** `cixzhang`, `2026-09-06`++Mechanical review inventories the exact public API and behavior delta, identifies+the canonical owner, and rejects objective API-shape violations such as derivable+choices, overloaded inputs, hidden conditional precedence, or duplicate operation+names for one semantic action. It does not decide unsettled semantics.-The API gate rejects a missing PR-readable semantic delta, a missing canonical--owner-record update, a derivable implementation choice, an overloaded input,-hidden conditional precedence, 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.+When current authority does not settle a surviving proposal, route it privately to+the human owner. The owner accepts, rejects, or refines the semantic contract; the+accepted decision becomes review authority only after it is committed in the+canonical record as `current`.-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.+Rejected: asking owners to discover mechanical defects from implementation code,+treating generated evidence as a semantic decision, or publishing a contributor-+facing verdict before the owner settles an absent contract.-### DEC-5 — Semantic contracts apply now; broad coverage rejection activates later+### DEC-5 — Public changes require committed current authority**Reference:** `spec:AST-002/DEC-5`-**Decider:** `cixzhang`, `2026-08-31`+**Decider:** `cixzhang`, `2026-09-06`-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.+Every public API addition and public behavior change identifies applicable current+committed authority before implementation acceptance. Draft records provide+context and route questions, but they are not policy and cannot clear the gate.+Exact-head owner discussion or approval is decision evidence, not a substitute for+recording the accepted contract as current.-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.+Missing authority creates the private unsettled path owned by+`architecture:knowledge-contracts`; it is not permission to accept the change and+not an automatic contributor-facing rejection. After the canonical decision is+current, review the implementation's exact head against it.-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.+Rejected: the former staged exception that let one pull request proceed on owner+approval while leaving its reusable contract draft or missing. That path made the+same public behavior acceptable in one review and undiscoverable in the next.### DEC-6 — Public inputs keep one semantic responsibility@@ -388,6 +381,27 @@ Rejected: treating a function that only validates and returns its input as a`check*` function, using `use*` for a non-hook utility, or hiding separatelypublic registration inside a constructor without a compatibility plan.+### DEC-8 — Public primitives are intentional semantic contracts++**Reference:** `spec:AST-002/DEC-8`+**Decider:** `cixzhang`, `2026-09-06`++Prefer a public primitive when product builders need to compose stable behavior+across callsites and the contract can name caller intent, operations, outcomes,+and failure behavior without exposing implementation machinery. Record that+contract as current before accepting the public surface.++A bug fix does not create an exception. When it restores current authority, keep+its API and behavior within that contract. Any additional public primitive or+observable behavior follows `architecture:knowledge-contracts`: reuse an existing+current decision when one settles the delta, and ask the owner only when authority+is absent.++Rejected: promoting internal focus targets, gesture memory, DOM slots, timers, or+other existing fields merely because removing an internal wrapper or fixing one+path becomes easier. Existing implementation is evidence of mechanics, not intent+for permanent public API.+## Open questionsNone.