What (One-liner)

One-shot macro dashboard aggregator: a single /mfle/snapshot call returns regime + cycle + CLI + output gap + key indicators (GDP / UNRATE / FEDFUNDS / CPI). 5 MFLE submodules in series. FRED unavailable → silent degrade to regime only; logic_lineage records which upstreams successfully contributed.

How to use

Drop macro_snapshot_v1 on Canvas (or macro_factor_v1, same endpoint). Optional regime_source=yfinance|fred. Typical pattern:

macro_snapshot_v1 → institution_composite (macro overlay input)
                 ↘
        casa_strategy_v1 / meta_strategy (strategy-pool context)

Core formulas

# 5-step aggregator (see frontmatter for the full flow):

1. regime    = detect_regime_from_{yfinance|fred}()
2. cycles    = cycles_from_gdp()                 if fred_available
3. cli       = get_composite_cli()                if fred_available
4. gap       = get_output_gap()                   if fred_available
5. indicators = get_series_recent(['GDPC1', 'UNRATE', 'FEDFUNDS', 'CPIAUCSL'])
                + aliases (unrate → unemployment_rate; fedfunds → fed_funds)
                + round(2) on yoy_pct fields

logic_lineage records each successful upstream tag, order = [regime, cycles, cli, gap]

Assumptions & applicability

Assumptions: FRED_API_KEY configured + US FRED series + each upstream provides its own available flag.

Applies to: Canvas macro overlay node, frontend dashboard one-shot fetch, cross-module context input.

Does not apply to: individual upstream calls (use each endpoint directly), fully offline, non-US, historical-time-point snapshots.

Input / Output contract

{regime_source?='yfinance'} → {regime, regime_confidence, cycle_phase, cycle_peak_date, cycle_trough_date, months_in_phase, leading_indicator_direction, output_gap_pct, key_indicators, logic_lineage}.

When FRED unavailable: cycle_* / leading_indicator_direction / output_gap_pct all None + key_indicators = {} + logic_lineage = ['tvp_kfavar_yfinance'].

Known limitations

1. regime_source='fred' silent fallback: falls back to yfinance when FRED is unavailable (only logic_lineage reveals it)
2. FRED unavailable → key_indicators empty dict + all FRED-dependent fields None
3. US series hard-coded, no regime override
4. key_indicators alias 2-way duplicate: unrate + unemployment_rate carry the same value (clients must decide which)
5. round(2) only on yoy_pct; recent values raw precision
6. logic_lineage records Pangura-level algorithm names only (does not track FRED fetch details)
7. No as_of / time_travel parameter (always latest)

References

Burns-Mitchell (1946) NBER Business Cycles dating + Primiceri (2005) TVP-SVAR + OECD (2012) CLI System. See frontmatter.

Golden Test

tests/golden/fixtures/tier3/macro_snapshot/ — 7 upstreams monkey-patched. 1e-12 tolerance (pure aggregation, field copy + round). 9 tests:

• yfinance_all_available — full snapshot byte-equal
• fred_all_available — regime_source='fred' + lineage[0]='tvp_kfavar_fred'
• fred_unavailable — degraded snapshot (regime-only + empty key_indicators)
• cycles_unavailable — cycles.available=False but CLI/gap still contribute
• determinism — 5 reruns byte-identical
• result_structure — 10 fixed top-level keys
• logic_lineage_ordering — append order regime → cycles → cli → gap
• key_indicators_aliasing — unrate==unemployment_rate / fedfunds==fed_funds
• regime_source_fallback_when_fred_unavailable — 'fred' + FRED down → silent yfinance fallback

Changelog

• 1.0.0 (2026-04-20) — First Active (Tier 3 batch 1.3, aggregator contract locked)