feat(fred): get_observations, aligned and downsampled

[walkerhughes]

Closes #33. Third of the fred stack (#30), on top of #37.

The tool the server exists for. Three things it does that a wrapper over /series/observations does not.

1. Columnar output

FRED sends one object per observation:

{"realtime_start":"2026-08-05","realtime_end":"2026-08-05","date":"2025-01-01","value":"2.99098"}

On a normal request the two realtime fields carry the same value on every row, and the key names repeat once per observation. So the response becomes:

{"dates": ["2025-01-01", ...],
 "values": {"UNRATE": [4.0, ...], "CPIAUCSL": [2.99, ...]}}

Measured live on 20 years of DFF:

	chars
Raw FRED payload	694,388
This tool	2,856 (0.4%)

Several series share one date index, so a comparison is a single call and arrives already joined. Where a quarterly series has no monthly observation the value is null, not forward-filled: filling would invent numbers FRED never published.

2. Summary computed before downsampling

This is the part that makes long daily series usable, and the ordering is the whole trick. The fetch is unlimited and latest, prior, change, pct_change, min, max, mean and count are computed over every observation. Only the returned point list is thinned, to evenly spaced samples that always keep the first and last.

DFF, last 20 years:
  points  {returned: 120, total: 7305, dropped: 7185}
  summary min 0.04, max 5.41, latest 3.63

120 points, and the true 20-year range. A summary computed after thinning would quietly report the sample's range as the series' range, and nothing about the output would look wrong.

The daily test fixture is built from explicit knots that put the peak and the trough in the interior of the series, away from the endpoints downsampling always keeps. With extremes at the endpoints the test could not tell the two orderings apart.

Nothing is silently truncated: points reports total and dropped, with a note when thinning happened.

3. Argument correction

None of FRED's vocabulary is guessable, and all of these inputs are unambiguous, so they are translated rather than answered with a 400 about a variable name.

A model writes	Sent
units="yoy", "year over year", "inflation"	pc1
units="percent change", "mom"	pch
units="annualized", "saar"	pca
units="level", "raw", ""	lin
start="5y", "last 5 years", "18 months"	a date, counted back from today
start="2020", "2020-01"	2020-01-01
frequency="monthly"	m
aggregation_method="total"	sum

The response echoes units with a plain-English units_meaning, so the numbers are not left to be interpreted.

Date arithmetic is calendar-correct without a dependency: three months before 31 May is 28 February, and a year before 29 Feb 2024 is 28 Feb 2023. Both are tests. 2020-13-01 and a backwards range are caught here rather than at the API.

Errors

A bad ID among good ones costs only its own column:

{"values": {"UNRATE": [...]},
 "errors": {"NOPE": "Bad Request. The series does not exist."}}

Invalid units, unreadable dates, and reversed ranges never reach the API at all; the tests assert not fred.requests.

Verification

243 tests, 98% coverage, make check clean.

Live against the real API:

CPIAUCSL + UNRATE yoy since 2015 -> 120 dates, one index, CPI yoy 3.46 (2026-06-01)
DFF last 20y                     -> 120 of 7305 points, true min 0.04 / max 5.41