refactor(models): reusable latest-execution ranking with pre/post-rank success filters

[lewisjared]

Description

Extracts the latest-execution-per-group ranking into a reusable row_number() primitive parameterised by an optional pre-rank population filter (among_executions), so callers can choose which execution population "latest" is computed over rather than only filtering the winner after the fact.

Adds a latest_successful knob to get_execution_group_and_latest_filtered (pre-rank: "each group's latest successful run") alongside the existing successful knob (post-rank: "is the latest run successful?"). The two answer different questions and are documented as such: successful=True drops a group whose newest run failed, whereas latest_successful=True changes which run is chosen as newest so an earlier success is still surfaced.

Also fixes a latent tie-break bug: the previous max(created_at) equijoin duplicated a group row when two executions shared a created_at. The row_number() window (ordered created_at DESC, id DESC) guarantees exactly one winner per group.

This is a foundation-only change. The new latest_successful parameter has no callers yet; switching reingest to the pre-rank filter is a behaviour change tracked in #782.

Checklist

Please confirm that this pull request has done the following:

• Tests added
• Documentation added (where applicable)
• Changelog item added to changelog/

Summary by CodeRabbit

• New Features
  • Added a new option to control how “latest” is selected—either from successful executions or from the newest execution overall.
  • Enabled additional custom eligibility for which executions can be considered when determining the latest run.
• Bug Fixes
  • Fixed an issue where execution listings could duplicate groups when two executions shared the same timestamp; each group now resolves to a single deterministic latest execution.
• Tests
  • Added unit tests covering deterministic tie-breaking and the difference between pre- and post-filtering behaviour.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 289a0fc5-ac55-4ec7-81d5-43eaa3ff9221

📥 Commits

Reviewing files that changed from the base of the PR and between d8a923e and 4871e97.

📒 Files selected for processing (1)

• changelog/786.fix.md

✅ Files skipped from review due to trivial changes (1)

• changelog/786.fix.md

---

📝 Walkthrough

Walkthrough

Refactors latest-execution-per-group selection in execution.py to use deterministic window ranking with optional pre-rank filtering, adds latest_successful selection control, and adds tests for tie-breaking and success-filter behaviour.

Changes

Latest execution ranking refactor

Layer / File(s)	Summary
Window-ranking helper and outer-join query packages/climate-ref/src/climate_ref/models/execution.py	Adds _latest_execution_ids and _successful_predicate, and updates get_execution_group_and_latest to use the ranking subquery with optional among_executions filtering.
Filtered query with pre/post-rank success options packages/climate-ref/src/climate_ref/models/execution.py	Adds latest_successful and updates get_execution_group_and_latest_filtered to derive among_executions from it and reuse _successful_predicate for post-rank filtering.
Unit tests for ranking and filtering semantics packages/climate-ref/tests/unit/test_execution_latest_ranking.py, changelog/786.fix.md	Adds helpers and tests for deterministic winner selection and pre-rank vs post-rank success behaviour, plus a changelog note describing the duplicate-group fix.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: reusable latest-execution ranking with pre/post-rank success filtering.
Description check	✅ Passed	The description covers the change, rationale, and checklist, but the changelog checkbox is left unchecked despite a changelog file being added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/latest-successful-ranking

---

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

[coderabbitai]

🧹 Nitpick comments (1)

packages/climate-ref/src/climate_ref/models/execution.py (1)

440-461: 🚀 Performance & Scalability | 🔵 Trivial

Ranking primitive looks correct; consider a supporting composite index.

The two-level subquery (window rank inner, rn == 1 outer) is the right pattern since window functions can't be filtered in WHERE, and created_at DESC, id DESC gives a deterministic single winner per group.

For larger execution tables, a composite index on (execution_group_id, created_at, id) would let the partitioned row_number() sort resolve from the index rather than a per-partition sort. The existing standalone execution_group_id/created_at indexes only partially cover this.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d688014-8486-411d-972a-61098ab7ea95

📥 Commits

Reviewing files that changed from the base of the PR and between d7f63bd and d8a923e.

📒 Files selected for processing (2)

• packages/climate-ref/src/climate_ref/models/execution.py
• packages/climate-ref/tests/unit/test_execution_latest_ranking.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
core	92.34% <100.00%> (-0.01%)	⬇️
providers	86.56% <ø> (+0.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...es/climate-ref/src/climate_ref/models/execution.py	98.72% <100.00%> (+0.07%)	⬆️

... and 9 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.