chore(DATAGO-126647): Align feature flag schema with Solace release stages

[bwiebe-solace]

What is the purpose of this change?

Cleans up the FeatureDefinition schema to use shorter, more intuitive field names, and aligns the ReleasePhase enum with the official Solace Cloud release stages.

• default_enabled → default
• jira_epic → jira
• ReleasePhase expanded from 4 values (early_access, beta, experimental, ga) to the full Solace Cloud set: experimental, early_access, beta, controlled_availability, general_availability, deprecated

How was this change implemented?

Pure rename/expansion — no behaviour changes. Updated in the following order:

• registry.py — FeatureDefinition dataclass fields renamed; ReleasePhase enum expanded with Solace docs link; _parse_definition required-field list and validation messages updated; module docstring updated
• checker.py — definition.default reference updated
• feature_flags.py / feature_flag_responses.py — defn.default and DTO description string updated
• features.yaml — schema comment block updated; background_tasks example flag updated to new field names and general_availability phase
• All unit and integration tests updated to use new field names, enum members, and phase values

Key Design Decisions

The ga shorthand was replaced by the full general_availability string to match the Solace Cloud terminology exactly. While this is a longer string, it removes ambiguity and makes the phase values self-describing. All existing flags in the community features.yaml used beta or early_access, so no flag entries needed a phase value change — only the background_tasks example flag (which used ga) was updated.

How was this change tested?

• Manual testing: not required — purely mechanical renames with no runtime behaviour change
• Unit tests: all existing unit tests updated and passing (test_feature_registry, test_feature_checker, test_feature_provider, test_feature_flags_router)
• Integration tests: test_feature_flags_router integration test updated and passing against SQLite
• Known limitations: PostgreSQL integration tests not run locally (require testcontainers)

Is there anything the reviewers should focus on/be aware of?

• This PR is intended to land before PR feat(DATAGO-126647): Migrate existing feature flags to OpenFeature SDK #1178 (flag migration). Once this merges, feat(DATAGO-126647): Migrate existing feature flags to OpenFeature SDK #1178 will be updated to use default/jira in its features.yaml entries.
• The enterprise counterpart (same branch name, same change to features.yaml) is a separate PR in SolaceDev/solace-agent-mesh-enterprise.
• Any third-party YAML consuming features.yaml (e.g. enterprise repo, custom deployments) must update to default/jira field names — the parser will raise a ValueError on load if old field names are present.

---

Generated by Claude Code

[github-actions]

⚠️ FOSSA Guard: Licensing (SolaceLabs_solace-agent-mesh) • 3 flagged • 1 issue

Compared against main (1.18.12) • 4 new, 6 total (2 in base)

ℹ️ Privacy mode enabled - detailed violation information hidden.

• Flagged by Policy: 3 issue(s)
• Other: 1 issue(s)

Scan Report | View Details in FOSSA

[github-actions]

⚠️ FOSSA Guard: Vulnerability (SolaceLabs_solace-agent-mesh) • 1 issue

Compared against main (1.18.12) • 1 new, 6 total (5 in base)

ℹ️ Privacy mode enabled - detailed violation information hidden.

• Unknown: 1 issue(s)

Scan Report | View Details in FOSSA

[Copilot]

Pull request overview

This PR updates the feature-flag definition schema to use shorter field names and aligns ReleasePhase with Solace Cloud’s official release stages, then propagates those changes through the registry/parser, checker, API DTOs/router, and tests.

Changes:

• Renamed FeatureDefinition fields (default_enabled → default, jira_epic → jira) and updated all references.
• Expanded ReleasePhase to the full Solace Cloud stage set (including controlled_availability, general_availability, deprecated) and updated serialization expectations.
• Updated the annotated features.yaml schema/example and adjusted unit/integration tests accordingly.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/solace_agent_mesh/common/features/registry.py	Renames schema fields, expands ReleasePhase, updates YAML parsing/validation and docstrings.
src/solace_agent_mesh/common/features/checker.py	Switches evaluation from definition.default_enabled to definition.default.
src/solace_agent_mesh/common/features/features.yaml	Updates schema comments and example flag to new keys + general_availability.
src/solace_agent_mesh/gateway/http_sse/routers/feature_flags.py	Maps registry definitions to DTO using defn.default.
src/solace_agent_mesh/gateway/http_sse/routers/dto/responses/feature_flag_responses.py	Updates release-phase description text to include the expanded enum values.
tests/unit/common/test_feature_registry.py	Updates YAML fixtures/assertions for renamed keys and expanded release phases.
tests/unit/common/test_feature_checker.py	Updates helper flag definitions to use default/jira and new GA enum member.
tests/unit/common/test_feature_provider.py	Updates provider tests/fixtures to new schema field names and phase strings.
tests/unit/gateway/http_sse/routers/test_feature_flags_router.py	Updates DTO mapping tests and adds coverage for all new phase string values.
tests/integration/apis/test_feature_flags_router.py	Updates integration assertion from ga to general_availability.

Comments suppressed due to low confidence (1)

src/solace_agent_mesh/common/features/registry.py:135

• FeatureRegistry no longer accepts the legacy YAML keys (default_enabled, jira_epic). Given this loader is used at startup, any downstream/enterprise/custom features.yaml that hasn’t been migrated will now hard-fail with a ValueError. The codebase already supports deprecated config-key aliases elsewhere (e.g., gateway config), so consider accepting the legacy keys as fallbacks (with a deprecation warning) and preferring the new keys when both are present to avoid startup outages during rollout.

        required = ("key", "name", "release_phase", "default", "jira")
        missing = [f for f in required if f not in raw]
        if missing:
            missing_str = ", ".join(missing)
            raise ValueError(
                f"Feature definition in {source} is missing required "
                f"field(s): {missing_str}. Entry: {raw!r}"
            )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqube-solacecloud]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

[dylanwalsh-solace]

Looks good to me, will you update the doc to align with these definitions too?
https://sol-jira.atlassian.net/wiki/spaces/AIAML/pages/6065815703/SAM+Feature+Flags+Guide#Release-Phases

[bwiebe-solace]

Looks good to me, will you update the doc to align with these definitions too? https://sol-jira.atlassian.net/wiki/spaces/AIAML/pages/6065815703/SAM+Feature+Flags+Guide#Release-Phases

Yes, I am updating it now

[bwiebe-solace]

Need to make some other changes to the framework, so rolling these changes into that PR