Give the financial-year boundary one home in translator.helpers

[nick-gorman]

Follow-up to #139, stacked on translate-custom-constraints — retarget to main once that merges.

#139's review noted that _investment_period_start_dates in translator/constraints.py re-encodes the financial-year boundary — "FY 2030 starts on 1 July 2029" — that _get_iteration_start_and_end_time in translator/helpers.py already owns for the snapshots. Going looking, there is a third copy: snapshots._add_investment_periods encodes the same boundary in reverse (month >= 7 → year + 1). Three independent encodings of one convention means a change to any of them would silently leave the custom-constraint date_from resolution and the snapshots disagreeing about where a period begins, with nothing failing.

This change gives the convention one home. helpers.py gains two small primitives — _period_start(year_type, year) for the forward mapping and _period_of(year_type, timestamps) for the inverse — and the three existing sites derive from them.

src/ispypsa/translator/
├── helpers.py       ← _period_start / _period_of added; _get_iteration_start_and_end_time is now an adapter over _period_start
├── snapshots.py     ← _add_investment_periods uses _period_of in place of its own month >= 7 branch
└── constraints.py   ← _investment_period_start_dates becomes a one-liner over _period_start
tests/test_translator/
└── test_translator_helpers.py   ← direct fy/calendar cases for both primitives; the triple pinned for parity

A few choices worth flagging:

• The triple stays. _get_iteration_start_and_end_time keeps its (start_year, end_year, month) shape so snapshots.py and temporal_filters.py don't change; it now computes its two boundaries via _period_start, with the exclusive end being the start of the year after end_year (which is where its calendar branch's end_year + 1 came from). A new test pins the triple for both year types, so parity with the old branches is checked rather than assumed. Retiring the triple in favour of the callers using _period_start directly would be the natural next step, but it's a larger diff and is left out here.
• Label parsing is out of scope. The other two year_type == "fy" branches in the translator (helpers._get_financial_year_int_from_string and the cost-column parsing in links.py) turn "2025_26" strings into ints — a different concern from the period boundary, and both are old-format code.
• _investment_period_start_dates keeps its name in constraints.py, since it reads well in the orchestrator; only its body changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XRWFpjCqEbjKuYNv7mVsUk

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/ispypsa/translator/constraints.py	95.45% <100.00%> (+1.10%)	⬆️
src/ispypsa/translator/helpers.py	100.00% <100.00%> (ø)
src/ispypsa/translator/network.py	100.00% <100.00%> (ø)
src/ispypsa/translator/snapshots.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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