Skip to content
PLUMEGOstdlib-shaped Go services with explicit wiring.
EN

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 maturity
stability_tiers:            # optional per-subpackage breakdown
  stable:
    - provider
    - session
  experimental:
    - orchestration
    - semanticcache

Most 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”
Terminal window
grep -E "^status:|stability_tiers:" x/<module>/module.yaml

For x/ai with its subpackage breakdown:

Terminal window
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:

  1. The public API has been used in multiple services without requiring breaking changes.
  2. The interface contracts are documented in module.yaml.
  3. 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.

Section titled “Read next”