fix(meta_ads): no silent fallback to last_7d for unknown period values (#134)

[hyoshi]

Closes #134.

Problem

The Meta Ads MCP tools' period argument advertised last_14d, last_90d, and explicit YYYY-MM-DD..YYYY-MM-DD ranges, but the implementation accepted only six hard-coded preset names and silently returned last_7d data for anything else. Period-over-period analyses (meta_ads_analysis_performance, meta_ads_analysis_cost) doubled the bug: the "previous" window was likewise mapped via a tiny dict that, for last_7d, returned last_30d — a superset that overlaps the current window, making every delta meaningless.

Severity: silent data corruption. Operators acting on the returned numbers (budget reallocations, pause/enable decisions, A/B winner picks) were acting on the wrong window with no exception, log line, or warning string in the response.

Fix

Tool / function	Before	After
meta_ads_insights_report / meta_ads_insights_breakdown	Unknown period → silent last_7d	Unknown period → ValueError surfaced at MCP boundary. YYYY-MM-DD..YYYY-MM-DD → forwarded as time_range. last_14d / last_90d → forwarded as date_preset.
meta_ads_analysis_cost (investigate_cost)	prev_map.get(period, "last_30d") → previous overlapped current	previous_period(period) → same-length window immediately before current
meta_ads_analysis_performance (analyze_performance)	4-key prev_period_map with same superset bug	Same previous_period(period) helper
Tool description _PERIOD_PARAM	Listed last_14d / last_90d / custom range without this_month / last_month	Lists every preset the resolver accepts

Public behaviour

• period accepts today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month, or YYYY-MM-DD..YYYY-MM-DD (both endpoints inclusive).
• Anything else raises ValueError (no silent fallback).
• The previous-period for any current period is the same-length window immediately before it.

Implementation

• New mureo/meta_ads/_period.py — ResolvedPeriod dataclass + resolve_period() parser + previous_period() builder. The dataclass owns .to_api_params() so the date_preset | time_range narrowing lives next to the invariant.
• _insights.py — get_performance_report, get_breakdown_report, and analyze_performance funnel through the resolver. _PERIOD_TO_DATE_PRESET deleted.
• _analysis.py — investigate_cost uses previous_period(period).
• _tools_meta_ads_insights.py — _PERIOD_PARAM description aligned with the resolver's accepted surface.

Test plan

• Targeted unit tests pass: 107 / 107 across tests/test_meta_ads_period.py (38 new) + tests/test_meta_ads_operations.py (+4 new in TestInsightsMixin / TestAnalysisMixin).
• Coverage includes: every preset round-trip, custom-range round-trip, single-day range, twelve bad-input rejection cases (trailing/leading .., slash-style, since > until, whitespace, non-string, etc.), .days inclusive arithmetic, all previous_period branches, the no-overlap invariant.
• Regression: meta_ads test suite as a whole shows 407 passed on this branch vs 364 on main (+43 expected — entirely from new tests). 67 pre-existing failures in test_meta_ads_leads.py / test_meta_ads_media.py are unchanged and unrelated (handler-mock setup issues; same count and same names on main). Zero new regressions.
• Lint: ruff check and black --check clean on every file this PR touches.
• mureo/mcp/_helpers.py api_error_handler re-raises ValueError unchanged, so the new error surfaces to the operator with the full message (preset list included).
• CI green (3.10 / 3.11 / 3.12 / Windows, Analyze, CodeQL).

Backwards compatibility

• Callers relying on the silent last_7d fallback now see a ValueError. This is the bug being fixed — they were always getting the wrong window.
• BYOD (mureo/byod/clients.py) uses its own _period_to_range (LAST_30_DAYS shape) — unaffected.
• Google Ads has its own comparison logic — unaffected.
• Every previously-working preset (today / yesterday / last_7d / last_30d / this_month / last_month) keeps working, plus the previously-advertised-but-broken last_14d, last_90d, and custom range shapes.