inter-hub/docs/functional-modules.md

# IHF Functional Module Maturity Register

**Framework:** GAAF-2026 | **Last reviewed:** 2026-03-31 | **Next review:** 2026-09-30

This document is the authoritative maturity register for all IHF functional modules.
Maturity labels are defined in `contracts/functional/module-maturity-labels.md`.

---

## Module Registry

| Module | Phase | Maturity | Stability Guarantee | Deprecation Policy |
|--------|-------|----------|--------------------|--------------------|
| RequirementCandidate lifecycle | Phase 2 | **Stable** | Schema and controller API frozen | Major version only |
| DecisionRecord + governance ledger | Phase 3 | **Stable** | Schema and controller API frozen | Major version only |
| DeploymentRecord + OutcomeSignal | Phase 4 | **Stable** | Append-only invariant permanent | Major version only |
| AgentProposal + review workflow | Phase 5 | **Beta** | Core fields stable; confidence model may extend | Minor version notice |
| Cross-framework adapter contracts | Phase 6 | **Stable** | EnvelopeEmissionContract v1.0 immutable | Superseding contract version only |
| FrictionScore + BottleneckRecord | Phase 7 | **Beta** | Computation algorithm may improve | Minor version notice |
| HubHealthSnapshot | Phase 7 | **Beta** | Snapshot schema stable; score formula may change | Minor version notice |
| CrossHubPropagation | Phase 7 | **Experimental** | Pattern detection logic actively evolving | No notice required |
| WidgetOwnership + routing | Phase 8 | **Stable** | Ownership audit pattern permanent | Major version only |
| FederatedPolicyOverlay | Phase 8 | **Beta** | Activation immutability permanent; scope model may extend | Minor version notice |
| StewardshipRole | Phase 8 | **Stable** | Point-in-time audit pattern permanent | Major version only |
| ArchiveRecord + lineage inspector | Phase 8 | **Beta** | Soft-delete pattern stable; lineage query may deepen | Minor version notice |
| Type registries (widget, event, category, policy scope) | GAAF WP-0009 | **Beta** | Schema stable; seed vocabulary additive only | Additive additions only; no removal |
| HubCapabilityManifest | GAAF WP-0009 | **Beta** | Activation semantics stable; manifest protocol may version | Minor version notice |

---

## Module Details

### RequirementCandidate Lifecycle
**Phase introduced:** Phase 2
**Tables:** `requirement_candidates`
**Stability:** Stable — schema will not change within major version. Validation logic (status transitions: `open → accepted/rejected`) is frozen.
**Known limitations:** No formal state machine enforcement in the DB; status is TEXT constrained only at the controller layer.
**Not guaranteed:** The `category` field was previously validated against a hardcoded list; as of GAAF WP-0009 it is validated against `annotation_category_registry`. Applications querying directly may see new category values as the registry grows.

### DecisionRecord + Governance Ledger
**Phase introduced:** Phase 3
**Tables:** `decision_records`
**Stability:** Stable — `requirement_id`, `decided_by`, `decided_at`, `outcome`, `rationale` are permanent.
**Not guaranteed:** The `outcome_signals` analysis may add new computed fields in `GAAF` analysis helpers.

### DeploymentRecord + OutcomeSignal
**Phase introduced:** Phase 4
**Tables:** `deployment_records`, `outcome_signals`
**Stability:** Stable — `outcome_signals` is append-only (DB trigger enforced). Signal types are an extensible vocabulary.
**Not guaranteed:** Signal aggregation helpers may change computation logic.

### AgentProposal + Review Workflow
**Phase introduced:** Phase 5
**Tables:** `agent_proposals`, `agent_review_records`
**Stability:** Beta — `proposal_type`, `content`, `model_ref`, `status` are stable. The `confidence` scoring model may be extended with additional fields.
**Not guaranteed:** Model reference format may evolve as new Claude models are released.

### Cross-Framework Adapter Contracts
**Phase introduced:** Phase 6
**Tables:** `envelope_emission_contracts`, `interaction_reporting_contracts`, `widget_adapter_specs`
**Stability:** Stable — `EnvelopeEmissionContract v1.0` is immutable. New versions are additive and published as new rows.
**Not guaranteed:** The `maturity` column was added in GAAF WP-0009; existing tooling may not surface this badge.

### FrictionScore + BottleneckRecord
**Phase introduced:** Phase 7
**Tables:** `friction_scores`, `bottleneck_records`
**Stability:** Beta — schema is stable. The `score` computation algorithm in `Application.Helper.FrictionScore` may be tuned without notice.
**Not guaranteed:** Absolute score values are not stable across algorithm versions; use comparisons within a single version window.

### HubHealthSnapshot
**Phase introduced:** Phase 7
**Tables:** `hub_health_snapshots`
**Stability:** Beta — snapshot schema stable. The composite health score formula may change in Phase 9+ as new signals are added.
**Not guaranteed:** Historical snapshots retain the score at computation time; they will not be recalculated retroactively.

### CrossHubPropagation
**Phase introduced:** Phase 7
**Tables:** `cross_hub_propagations`
**Stability:** Experimental — pattern detection logic is actively being refined. Schema fields may be renamed or retyped.
**Not guaranteed:** Detection heuristics, pattern names, and score thresholds will change without notice.

### WidgetOwnership + Routing
**Phase introduced:** Phase 8
**Tables:** `widget_ownerships`, `hub_routing_rules`
**Stability:** Stable — ownership audit pattern (point-in-time `owned_since`/`owned_until`) is permanent. Routing rule schema is stable.
**Not guaranteed:** As of GAAF WP-0009, `match_category` and `match_widget_type` are now validated against type registries; routing rules using unregistered type names will fail validation.

### FederatedPolicyOverlay
**Phase introduced:** Phase 8
**Tables:** `federated_policy_overlays`
**Stability:** Beta — activation immutability is permanent (activated overlays cannot be edited). The scope model (source/target hub relationships) may extend.
**Not guaranteed:** Policy overlay conflict detection heuristics may change.

### StewardshipRole
**Phase introduced:** Phase 8
**Tables:** `stewardship_roles`
**Stability:** Stable — the point-in-time role audit pattern is permanent. Role type vocabulary is additive.

### ArchiveRecord + Lineage Inspector
**Phase introduced:** Phase 8
**Tables:** `archive_records`
**Stability:** Beta — soft-delete pattern is stable. Lineage query depth and the `lineage` JSONB structure may be extended.
**Not guaranteed:** Deep lineage graph queries may become paginated in Phase 9+.

### Type Registries
**Phase introduced:** GAAF WP-0009
**Tables:** `widget_type_registry`, `event_type_registry`, `annotation_category_registry`, `policy_scope_registry`
**Stability:** Beta — schema stable. Framework seed vocabulary is permanent (names cannot be removed, only deprecated). Domain hub vocabulary grows as manifests are activated.
**Not guaranteed:** Registry UI and bulk import APIs are planned for Phase 10 and will extend the controller surface.

### HubCapabilityManifest
**Phase introduced:** GAAF WP-0009
**Tables:** `hub_capability_manifests`
**Stability:** Beta — activation semantics (draft → active → retired, type auto-registration on activation, read-only after activation) are permanent.
**Not guaranteed:** The manifest protocol version (`manifest_version` field) will be bumped if the activation semantics change. Amendment workflow (currently manual retire + new draft) may be replaced by a `DraftAmendmentAction` in Phase 10.