fix(cachedclient): serve fresh period-based data without calling the API

[codemug]

The bug

_read_period_based fetched unconditionally. Its own comment said so:

"""Cache logic for Pattern B (period-based) endpoints."""
original_limit = bound_args.get(meta.limit_param) if meta.limit_param else None

# Always fetch from API with the caller's original params
result = await real_method(*original_args, **original_kwargs)

Storage was used only to merge and persist the response afterwards. That makes the Pattern B cache a write-through archive, not a cache — it never avoided a single network call. CachedClientConfig.staleness_days documents itself as controlling exactly this ("How many days old stored data can be before a Pattern B refetch is triggered") but was referenced nowhere except its own definition.

Pattern A (date-range) is unaffected — compute_gaps already does the right thing there.

Why it matters

Pattern B covers the statement endpoints: income-statement, balance-sheet-statement, cash-flow-statement, key-metrics. A 5,316-name universe therefore issues ~21k requests on every rebuild regardless of what is already on disk, and the provider's rate limiter stretches that into a 4–5 hour crawl.

Observed on a live deployment: the cache was measured at 99.2% populated for the configured universe —

income-statement          5274 / 5316
balance-sheet-statement   5266 / 5316
cash-flow-statement       5251 / 5316
key-metrics               5281 / 5316

— and a rebuild still re-fetched every ticker from scratch, writing 2,842 cache files in 10 minutes while re-downloading data it already had. Four consecutive builds failed to complete.

This is also a needless cost against the API quota: annual and quarterly statements change a handful of times a year.

The fix

Gate the fetch on the stored sidecar's last_updated against staleness_days. Everything needed already existed — StoredRangeMetadata.last_updated is populated on write and surfaced by get_stored_range(); only the check was missing.

Freshness deliberately errs toward refetching: a negative staleness_days, absent metadata, or an unreadable sidecar all fall through to the API. Serving stale data silently is worse than paying for one request.

staleness_days is passed to the proxy as a scalar rather than the config object, because client.py imports proxy.py and importing the config back would be circular.

Behaviour change

With the default staleness_days=1, a second call for the same key on the same day is now served from storage instead of re-fetching. test_period_based_merges_data asserted the old behaviour, so it now sets staleness_days=-1 to exercise the merge path explicitly — the merge logic itself is unchanged.

Tests

• test_period_based_serves_fresh_from_storage — two calls, exactly one API await
• test_period_based_refetches_when_storage_is_stale — sidecar aged, API called again
• test_period_based_fetches_when_nothing_stored — empty cache always reaches the API

tests/test_cachedclient/   104 passed
tests/                     935 passed
ruff check + ruff format --check   clean

🤖 Generated with Claude Code