fix(api): honor feature_frame_version >= 3 in ops + registry

[w7-mgfcode]

Root cause

Two feature-frame-version read helpers clamped any V outside {1, 2} down to 1, so a run with feature_frame_version >= 3 was mis-classified as V=1:

• app/features/ops/service.py — _run_feature_frame_version
• app/features/registry/service.py — _extract_feature_frame_version

Both did if isinstance(value, int) and value in (1, 2): return value then return 1. Their docstrings ("Returns the int when the key is present, else V=1") and the registry SQL sibling _feature_frame_version_filter (which honors any int) were inconsistent with this clamp.

Symptom (showcase_rich, fresh DB)

The stale_alias_trigger step registers a run with feature_frame_version: 3 and asserts the demo-production alias becomes stale_reason=feature_frame_version_mismatch. The clamp made the ops layer read the V=3 latest run as V=1, so _alias_staleness saw alias_v(1) == latest_v(1) and returned newer_success_run → the decision-phase step failed and the run finished red.

Fix

In both helpers, replace value in (1, 2) with isinstance(value, int) and not isinstance(value, bool) and value >= 1 — honor any positive int (matches the docstrings, the SQL filter, and the "opaque incrementing integer" model in docs/_base/DOMAIN_MODEL.md). bool is explicitly excluded (it subclasses int); non-int / zero / negative still resolve to V=1 (legacy back-compat).

Tests

Updated the two tests that encoded the old clamp, and added regressions:

• ops test_run_feature_frame_version_honors_any_positive_int — V=3 → 3; "2" / 0 / -1 / True → 1.
• ops test_alias_staleness_v1_alias_v3_latest_reports_mismatch — V1 alias + newer V3 latest → feature_frame_version_mismatch (the showcase scenario).
• registry test_extract_feature_frame_version_honors_any_positive_int — V=3 → 3, V=7 → 7; "2" / 0 / True → 1.

(The *_rejects_unsupported_value tests previously asserted V=3 → 1 — they encoded the buggy clamp and are now corrected to the intended contract.)

Validation

• ruff check ✅ · ruff format --check ✅
• mypy app/ ✅ — only pre-existing xgboost optional-dep import errors in untouched files
• pyright app/features/ops app/features/registry ✅ — only pre-existing lightgbm/xgboost optional-dep import errors
• pytest -m "not integration" ✅ 1651 passed, 12 skipped

Impact note

Beyond unblocking a green showcase_rich run, this corrects ops staleness verdicts and registry comparability/duplicate detection for any V≥3 run.

Closes #338

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 46282617-a9bd-4240-8e0b-8e3dbfaddb2b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/feature-frame-version-clamp

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}