Extension Stability Policy

Extension Stability Policy

This document defines the criteria for advancing an x/* extension module from experimental to beta (stable-candidate), and from beta to ga.

It does not override the stable-root compatibility promise defined in Deprecation Policy. Stable roots follow a separate, stronger policy.

Status ladder

The status field in each module’s module.yaml tracks position on this ladder:

Status	Meaning
experimental	API shape may change; no compatibility expectation
beta	API shape is stable within the current major version; breaking changes require deprecation notice
ga	Full v1 compatibility promise; follows Deprecation Policy

All x/* modules start as experimental. Promotion is explicit and requires meeting the criteria below.

Promotion evidence is tracked in specs/extension-beta-evidence.yaml. A module remains experimental until both the evidence file and the module manifest are updated in a promotion card.

Criteria for experimental → beta

An extension may be proposed as beta when all of the following are true:

1. Stable public API surface. No exported symbol changes have been needed for at least two consecutive minor releases. All public types use constructor injection rather than mutable fields or global registration.

2. Boundary compliance. The module passes go run ./internal/checks/dependency-rules with no violations. It does not import stable roots in ways that would force stable-root changes to accommodate it.

3. Test coverage. The module has unit tests for every documented public behavior path, including negative paths (errors, empty inputs, context cancellation). The test suite runs cleanly with go test -race ./....

4. Module manifest. The module.yaml is complete and schema-valid (go run ./internal/checks/module-manifests). responsibilities, non_goals, review_checklist, and agent_hints accurately describe the current implementation.

5. Module primer. The primer under docs/modules/ documents all public entrypoints, boundary rules, and a validation command. It is consistent with the current API surface (not aspirational).

6. No known regressions. No open regression reports against the module’s documented behavior.

7. Owner sign-off. The module owner listed in module.yaml confirms the criteria are met.

Criteria for beta → ga

In addition to maintaining all beta criteria, a beta module must:

1. Production usage evidence. At least one production deployment (internal or external) is documented or known to the owner.

2. Two-release stability. The beta status has been held for at least two consecutive minor releases with no breaking changes.

3. Deprecation pathway. Any symbols previously deprecated while in experimental or beta have been removed or have a documented removal timeline.

4. GA compatibility claim reviewed. The module owner and a stable-root reviewer have confirmed the public surface is ready for the full Deprecation Policy promise.

Promotion process

1. Open a task card in tasks/cards/active/ referencing this policy.
2. Update specs/extension-beta-evidence.yaml with required release refs, exported API snapshot refs, blocker state, and owner sign-off.
3. Generate or compare exported API snapshots with go run ./internal/checks/extension-api-snapshot.
4. For release-to-release evidence, compare selected refs with go run ./internal/checks/extension-release-evidence.
5. Validate the evidence ledger and blocker state with go run ./internal/checks/extension-beta-evidence.
6. Update the status field in the module’s module.yaml.
7. Update the module’s primer under docs/modules/ to reflect the new status.
8. Update docs/release/roadmap.md to record the promotion.
9. The CI-equivalent release gate must pass before merging: make gates.

Current evaluation

Already promoted to beta

Seven families reached beta between v1.0.0 and v1.1.0. All are frozen between minor release refs; breaking changes require a new tagged ref and a snapshot diff.

Module	Promoted at	Notes
x/gateway	v1.0.0	Edge proxy, load balancing, and route rewriting
x/observability	v1.0.0	Prometheus metrics and OpenTelemetry tracing
x/rest	v1.0.0	CRUD resource controllers
x/websocket	v1.0.0	Real-time transport
x/tenant	v1.1.0	Per-tenant routing, quota, and policy
x/frontend	v1.1.0	Static and embedded SPA serving
x/messaging	v1.1.0	Async publish/subscribe wiring (parent family)

Selected beta surfaces within experimental families

The parent family remains experimental, but the surfaces below have their exported API frozen between release refs:

Surface	Promoted at	Family status
x/ai/provider	v1.1.0	x/ai remains experimental
x/ai/session	v1.1.0	x/ai remains experimental
x/ai/streaming	v1.1.0	x/ai remains experimental
x/ai/tool	v1.1.0	x/ai remains experimental
x/data/file	v1.1.0	x/data remains experimental
x/data/idempotency	v1.1.0	x/data remains experimental

Next candidates (Phase 16 evaluation)

Module	Candidate for	Status / remaining action
x/tenant	ga	Waiting on v1.2.0 release evidence (task card 1500)
x/ai stable-tier subpackages	Additional beta surfaces	Per-subpackage evaluation after release evidence (task card 1501)
x/openapi	beta	module.yaml cleanup and beta evaluation once release evidence is available (task card 1502)

Still experimental with no evaluation scheduled: x/fileapi, x/resilience, x/rpc, x/validate, remaining x/ai and x/data surfaces, x/messaging/mq, x/messaging/pubsub, x/messaging/scheduler, x/messaging/webhook, x/gateway/discovery, x/gateway/ipc, x/observability/devtools, x/observability/ops.

Non-goals

• Do not promote x/* packages to ga without this process.
• Do not weaken the stable-root promise to accommodate extension promotion.
• Do not let beta status become a permanent holding pattern; set a target release for ga at promotion time or record the blocker explicitly.

Read next

• Deprecation Policy — full v1 compatibility policy for stable roots
• Extension Maturity — current dashboard of all x/* families
• x/* Family — how optional capabilities are organized
• Release Posture — support matrix and adoption guidance