Skip to content

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.md
index 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 active
draft/current records without making draft behavior authoritative. Other draft
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 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, or
more 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 beco
1. The record names the code surface that can affect it and the checks that
verify 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 a
relevant 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 final
operation 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 than
creating 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.md
index 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 compatibility
contract; 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 stable
public 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, or
when the existing docs would otherwise become false. Fixing an implementation
defect 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 prefixed
props 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.md
index 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 in
one 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; the
component `.doc.mjs` remains the complete syntax/reference authority.
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.md
index 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 the
focused 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 clear
controls out of flow without reserving their rendered width, so narrow input
content 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 provided
options available while input `isLoading` is true, but current empty/no-result
presentation 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 Field
consumes the family sentinel. Follow-up work must make attached capability and
the 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, and
individual state behavior, but do not yet provide the complete real-browser
inline-size/end-overlap matrix below. This current record names those
diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.md
index 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 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,
- 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 prevent
bad results when doing so does not make the API harder to understand. Make
statically 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 CLI
conventions; 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 public
hooks and utilities they explicitly co-own. Family, architecture, and system
records 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 and
migration 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 evaluated
when 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 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
+### 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 separately
public 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 questions
None.