# Module Maturity Labels

**Name:** module-maturity-labels
**Version:** 1.0
**Date:** 2026-03-31
**Status:** Active
**Layer:** Functional

---

## Purpose

Defines the four maturity states used to label IHF functional modules and
contract tables. These labels communicate to domain hub developers which
surfaces are safe to depend on long-term.

---

## Labels

### Stable

The public interface **will not change** within the current major version.

- Removing a field, renaming a table, or changing a column type is a **breaking
  change** and requires a major version bump (e.g. IHF v1.0 → v2.0).
- Adding a nullable or defaulted column is **not** breaking and may occur
  without a version bump, but is documented in the changelog.
- Suitable for all production use, including domain hub compilation dependencies.

### Beta

The interface is **finalised for typical use** but edge-case fields may change
with a minor-version notice (e.g. IHF v0.2 → v0.3).

- Core workflow fields are stable; metadata, computed, or supplementary fields
  may be refined.
- Suitable for production use with awareness: monitor the changelog before
  upgrading.
- A Beta module will be promoted to Stable once it has been used in at least
  two deployed domain hubs without reported breaking-change issues.

### Experimental

The interface **may change without notice** between patch releases.

- Use only for internal prototyping, spike implementations, or with explicit
  opt-in acknowledgement.
- Not suitable for domain hub production code.
- A module remains Experimental until its design is confirmed by real usage.

### Deprecated

The module or field **will be removed** in the next major version.

- A replacement is documented in the contract or in the schema comment.
- The deprecated item remains functional until the major version boundary.
- Domain hubs must migrate before upgrading to the next major version.

---

## Where Labels Are Used

| Surface | How the label is expressed |
|---|---|
| Functional modules | `docs/functional-modules.md` maturity column |
| `envelope_emission_contracts` table | `maturity` column (added in IHUB-WP-0009) |
| `interaction_reporting_contracts` table | `maturity` column |
| `widget_adapter_specs` table | `maturity` column |
| Type registry entries | `status` column (`active` / `deprecated`) |
| Contract files in `/contracts/` | `Maturity:` header field |

---

## Promotion Path

```
Experimental → Beta → Stable
                 ↓
            Deprecated → (removed at next major version)
```

Promotions are recorded in the module's entry in `docs/functional-modules.md`
and the corresponding `maturity` column in the DB is updated.