Extension Maturity
Extension Maturity
Section titled “Extension Maturity”Every x/* package declares its maturity in module.yaml. This page explains what those declarations mean for teams choosing whether to take a dependency on an extension.
The two fields to read
Section titled “The two fields to read”Open any x/*/module.yaml and look for two fields:
status: experimental # top-level module maturitystability_tiers: # optional per-subpackage breakdown stable: - provider - session experimental: - orchestration - semanticcacheMost extensions carry only status: experimental with no stability_tiers block. A few (x/ai) publish a finer breakdown because their subpackages mature at different rates.
What each status means
Section titled “What each status means”| Status | Semver guarantee | API change policy | Production guidance |
|---|---|---|---|
| beta | API frozen between minor release refs | Breaking changes require a major version bump; deprecation notice before removal | Safe for production with minor-version pinning; review changelogs before upgrading |
| beta surface | Covered for the named subpackage only | Same as beta; parent family may still be experimental | Adopt the specific subpackage; isolate behind app-local adapters and check module.yaml |
| experimental | Not yet covered | API may change without a deprecation period | Evaluate per use case; pin an exact version and review changelogs on upgrade |
Current beta families
Section titled “Current beta families”These extension families are at beta status. Their APIs are frozen between minor release refs and are backed by two consecutive release refs, exported API snapshots, and owner sign-off.
| Family | Promoted | Evidence |
|---|---|---|
x/gateway | v0.2.0 | beta evidence |
x/observability | v0.2.0 | beta evidence |
x/rest | v0.2.0 | beta evidence |
x/websocket | v0.2.0 | beta evidence |
x/tenant | v1.1.0 | beta evidence |
x/frontend | v1.1.0 | beta evidence |
x/messaging | v1.1.0 (app-facing service) | beta evidence |
Selected beta surfaces
Section titled “Selected beta surfaces”Some families are experimental at the root level but contain specific subpackages that have accumulated their own release evidence and beta sign-off. The parent family can still change shape, but the named subpackage surface is stable.
| Surface | Parent family | Promoted | What is covered |
|---|---|---|---|
x/ai/provider | x/ai (experimental) | v1.1.0 | Provider interface and concrete constructors |
x/ai/session | x/ai (experimental) | v1.1.0 | Session lifecycle and state management |
x/ai/streaming | x/ai (experimental) | v1.1.0 | Streaming response coordination |
x/ai/tool | x/ai (experimental) | v1.1.0 | Tool registration and invocation |
x/data/file | x/data (experimental) | v1.1.0 | File helper and metadata contracts |
x/data/idempotency | x/data (experimental) | v1.1.0 | Idempotency key store contracts |
For these surfaces, check module.yaml stability_tiers before relying on a specific subpackage. Subpackages listed under stable: are covered; those listed under experimental: are not.
How to check before depending on an extension
Section titled “How to check before depending on an extension”grep -E "^status:|stability_tiers:" x/<module>/module.yamlFor x/ai with its subpackage breakdown:
cat x/ai/module.yaml | grep -A 12 "stability_tiers:"What experimental means in practice
Section titled “What experimental means in practice”Experimental status means:
- The constructor signatures, interface methods, or configuration field names may change between minor releases.
- A subpackage may be split, merged, or removed before reaching stable tier.
- The team is actively using it in production services, so regressions are caught quickly — but the API shape is still being refined.
Experimental does not mean:
- The code is untested or broken
- It is unsafe to run in production
- It will be removed imminently
The promotion path
Section titled “The promotion path”A subpackage moves from experimental to stable when:
- The public API has been used in multiple services without requiring breaking changes.
- The interface contracts are documented in
module.yaml. - A review confirms no planned breaking changes in the current roadmap.
Until promotion, treat the module.yaml as the authoritative record. If module.yaml lists a subpackage under stable:, you can rely on its API as you would a stable root. If it is absent from stability_tiers or listed under experimental:, pin and review on upgrade.
Stable roots are different
Section titled “Stable roots are different”The nine stable root packages — core, router, contract, middleware, security, store, health, log, metrics — are covered by semver at the module level. They have no x/* dependencies and their APIs will not change without a major version bump. Use them freely without pinning patch versions.