[DemchaAV]

Why

The API reference reads stability from the annotation: a member without @Beta is listed as Stable, whatever docs/api-stability.md says. Seven elements that 2.5 added to render-docx and the semantic export SPI had no marker:

Element	Before	Now
DocxBackendProvider	unmarked; not named in api-stability.md	@Beta; named under semantic backend discovery
DocxSemanticBackend(Consumer<DocxExportReport>)	unmarked, though api-stability.md already called it Experimental	@Beta
DocxExportReport.Note, DocxExportReport.Severity	unmarked. The pack generator resolves a nested type's stability on its own, so it listed both as Stable under a @Beta record	@Beta
DocxSemanticBackend.requiresResolvedLayout, .exportSections	unmarked overrides of @Beta methods. Java does not carry a method's annotation to its override	@Beta
SemanticExportContext's six-argument canonical constructor	unmarked, though it takes the @Beta layoutGraph and layoutFailure components	@Beta

All seven are new in 2.5 (absent from the 2.4.1 knowledge pack), so nothing that was Stable in a release changes tier.

The rest of what 2.5 added there already matched the page:

• DocxExportReport;
• DocxSemanticBackend.builder() and Builder;
• the layoutGraph / layoutFailure components and requireLayoutGraph;
• SemanticBackendProvider(s), SemanticSection, and SemanticBackend.exportSections / requiresResolvedLayout;
• toDocxBytes / writeDocx / buildDocx on DocumentSession and MultiSectionDocument;
• PageContext.unpaginated(boolean, boolean).

What changed

• Annotations: @Beta on the seven elements, each with the Experimental line in its Javadoc that other @Beta elements carry. The two overrides inherit it through {@inheritDoc}.
• Javadoc: some members were already @Beta but had no Experimental line. They gain it: SemanticBackend.requiresResolvedLayout, SemanticBackend.exportSections, SemanticExportContext.requireLayoutGraph, the record's components, DocxSemanticBackend.builder() and Builder.
• docs/api-stability.md:
  • the semantic SPI paragraph names the canonical constructor and the DOCX override;
  • the discovery paragraph names DocxBackendProvider;
  • the report paragraph names Note and Severity;
  • the section-export paragraph names the exportSections override.
• Other docs:
  • CHANGELOG (2.5.0): the existing discovery, report and resolved-layout entries name the provider, Note / Severity and the constructor. The migration note lists the provider among the @Beta additions.
  • The capability matrix's discovery row and the render-docx README name the provider as Experimental, and the DOCX recipe's report section says the report is.
• Knowledge pack: regenerated. Only backends.json / backends.md change, by the [beta] markers above.
• Tests:
  • DocxBetaSurfaceTest (render-docx) pins the marker on each DOCX element. It also pins that the Stable path stays unmarked: the DocxSemanticBackend class, its no-argument constructor, name() and export(graph, context).
  • SemanticExportContextTest (core) pins the marker on the six-argument constructor and its absence on the four- and three-argument ones.

The Stable path is unchanged. Adding an annotation breaks neither binary nor source compatibility.

Scope: render-docx and the semantic export SPI. ShapeNode.divider, an authoring-side component also new in 2.5, is not changed here.

Verification

• Tests: ./mvnw -B -ntp clean install -pl :graph-compose-render-docx -am and ./mvnw -B -ntp test -f qa/pom.xml: core 842, render-pdf 339, render-docx 2545 and qa 1910 tests, 0 failures.
• Sabotage: each of the seven markers was removed once, and a marker was added once each to the Stable no-argument backend constructor and to the four-argument context constructor. All nine were caught, each by the test written for that element, and the files came back byte-identical.
• Knowledge pack:
  • node knowledge/tools/api-surface/extract-api.mjs --from-reactor --check: current.
  • check-stability-doc.mjs: every originating @Beta is named (2 packages, 10 types, 26 members).
• japicmp: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl :graph-compose-core,:graph-compose-templates ends in BUILD SUCCESS, and all three executions ran. The core report lists the six-argument constructor as NEW CONSTRUCTOR with NEW ANNOTATION: …Beta, and reports no break.
• Full gate on the final tree (b2fd72ac9): clean verify of the 12-module reactor, as CI runs it; the four knowledge checks of CI's JDK 17 job (API surfaces, stability doc, claims, routes); core javadoc (0 warnings); then install and the examples tests (93). It ends in GATE PASS.

Lane: canonical surface (public API markers and docs). No layout or render code changes, so the DOCX corpus is untouched.