feat(risk-monitor): measure the rule that fires, and give fundamentals their own channel

The Warning study measured a fitted percentile crossing that nothing consumes.
What reaches Telegram is a quadrant change: fixed 50/40 dividers, hysteresis,
two-session confirmation, 3-day cooldown. Those thresholds are constants, not
fits, so there is no training set to protect and all 11 detected corrections are
evaluable instead of the 4 that fell in a holdout.

Replaying it: 1/10 corrections, 0.9 false alarms/year. Random alarms at the same
firing rate match or beat that in 65% of draws. The panel now carries ablations
(does the quadrant machinery earn its place?), external baselines (does the score
earn its complexity?), and that null, because a bare "2 of 4" was unreadable in
either direction. Nothing in the alert path was retuned on the strength of it.

Fundamentals become a third channel rather than a term in either score. v3 cut
them arguing 12+8 of 100 points "could not change any published conclusion" --
true only when every technical sensor reads zero; weighted they moved the bar for
the 40 divider from 40 to 25. But no fusion weight is measurable either: with ~10
events and no fundamental history, any weight is a policy preference presented as
a measurement. So the read is a categorical state (supportive/neutral/adverse/
unknown) with an evidence grade, derived by fixed rules from stored facts, read
by confluence. The LLM extracts and explains; it does not score.

Absence stays absence throughout. `unknown` is unreachable by averaging, a stale
or empty observation may display but never confirm, extraction failures map to
`unknown` rather than `mixed`, and the study rows are coverage-matched and marked
not-measurable until enough corrections are covered -- otherwise a fortnight of
observations renders as 0/10 and reads as a failed test.

Observations become a real time series (migration 033); they lived in a single
overwritten settings slot, so no history existed to replay. Pre-rename snapshots
are adapted rather than discarded. METHODOLOGY stays v4 -- no score changed --
so no reseed; STUDY_SCHEMA moves to 3 and discards the cached report.

Post-deploy: re-run Event Study from Admin -> Jobs. The panel reads "not run yet"
until then.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/unit/test_regime_monitor.py

@@ -28,7 +28,7 @@ from app.services.regime_monitor_service import (
     drawdown_pct,
     f2_credit_spreads,
     current_observation,
-    fundamental_overlay,
+    fundamental_context,
     p1_trend_break,
     p2_death_cross,
     p3_drawdown,
@@ -40,6 +40,24 @@ from app.services.regime_monitor_service import (
 )
 
 
+async def _no_observations(_db):
+    return []
+
+
+async def _skip_recording(_db, _observation):
+    return None
+
+
+class _CommitOnlyDB:
+    """Enough session for writers that own their own transaction boundary."""
+
+    def __init__(self) -> None:
+        self.commits = 0
+
+    async def commit(self) -> None:
+        self.commits += 1
+
+
 def _dated(values: list[float], end: date = date(2026, 6, 26)) -> list[tuple[date, float]]:
     return [
         (end - timedelta(days=len(values) - 1 - index), value)
@@ -215,7 +233,7 @@ def test_score_pillars_gates_band_below_75_percent_coverage():
     assert result["band"] is None
 
 
-def test_fundamental_overlay_never_replays_before_effective_date_and_expires():
+def test_fundamental_context_never_replays_before_effective_date_and_expires():
     overrides = {
         "f1_score": 0.0,
         "f3_score": 100.0,
@@ -226,19 +244,19 @@ def test_fundamental_overlay_never_replays_before_effective_date_and_expires():
     }
     config = {**DEFAULT_CONFIG, "fundamental_staleness_days": 80}
 
-    pending = fundamental_overlay(overrides, config, date(2026, 6, 1))
+    pending = fundamental_context(overrides, config, date(2026, 6, 1))
     assert pending["pending"] is True
     assert pending["available"] is False
     assert pending["capex"] is None
     # The effective date is still reported so a pending refresh is visible.
     assert pending["effective_date"] == "2026-06-02"
 
-    live = fundamental_overlay(overrides, config, date(2026, 6, 2))
+    live = fundamental_context(overrides, config, date(2026, 6, 2))
     assert live["available"] is True
     assert live["good_news_stock_down"] == "yes"
     assert live["earnings_stress"] == 100.0
 
-    expired = fundamental_overlay(overrides, config, date(2026, 8, 22))
+    expired = fundamental_context(overrides, config, date(2026, 8, 22))
     assert expired["stale"] is True
     assert expired["available"] is False
 
@@ -263,7 +281,7 @@ def test_live_observation_is_visible_before_its_effective_date():
     config = {**DEFAULT_CONFIG, "fundamental_staleness_days": 80}
 
     before = date(2026, 6, 1)
-    record = fundamental_overlay(overrides, config, before)
+    record = fundamental_context(overrides, config, before)
     now = current_observation(overrides, config, before)
 
     # Same day, same observation: the record hides it, the live reading shows it.
@@ -314,35 +332,256 @@ def test_an_uncollected_observation_is_not_reported_as_collected():
     assert current_observation(collected, DEFAULT_CONFIG, date(2026, 8, 7))["observed"] is True
 
 
-def test_fundamentals_do_not_move_the_warning_score():
-    """The v3 complaint: a maxed-out LLM read must not silently do nothing.
+def test_fundamental_state_never_averages_unknown_into_neutral():
+    """Missing evidence must not present as evidence of normality.
 
-    It no longer feeds Warning at all, so Warning is identical either way and
-    the observation is reported beside the score instead of buried in it.
+    This is the trap that mattered when the channel replaced the weighted
+    modifier: treating ``unknown`` as a middle value would let two ``cutting``
+    reads and two ``unknown`` ones land on "neutral". A single adverse read
+    carries on partial evidence; ``unknown`` survives only when *nothing* was
+    observed.
+    """
+    names = DEFAULT_CONFIG["tickers"]["hyperscalers"]
+
+    assert rms._capex_signal(dict.fromkeys(names, "unknown"), names) == "unknown"
+    assert rms._capex_signal(dict.fromkeys(names, "raising"), names) == "supportive"
+    assert rms._capex_signal(dict.fromkeys(names, "holding"), names) == "neutral"
+
+    half_cut = {names[0]: "cutting", names[1]: "cutting", **dict.fromkeys(names[2:], "unknown")}
+    assert rms._capex_signal(half_cut, names) == "adverse"
+
+    assert rms._reaction_signal("yes") == "adverse"
+    assert rms._reaction_signal("no") == "supportive"
+    assert rms._reaction_signal("mixed") == "neutral"
+    assert rms._reaction_signal(None) == "unknown"
+
+    combine = rms.combine_fundamental_signals
+    assert combine("unknown", "unknown") == "unknown"
+    assert combine("adverse", "supportive") == "adverse"   # one adverse read carries
+    assert combine("supportive", "unknown") == "supportive"
+    assert combine("neutral", "unknown") == "neutral"
+    assert combine("supportive", "neutral") == "neutral"
+    # Nothing combines *into* unknown -- that would be inventing missing evidence.
+    assert "unknown" not in {
+        combine(a, b)
+        for a in rms.FUNDAMENTAL_STATES
+        for b in rms.FUNDAMENTAL_STATES
+        if not (a == "unknown" and b == "unknown")
+    }
+
+
+def test_fundamental_context_is_a_channel_not_a_term_in_warning():
+    """The read is reported beside the scores and never added into them.
+
+    A weighted modifier was built and reverted: with ~10 correction events and
+    almost no fundamental history, any fusion weight is a policy preference
+    presented as a measurement, and adding a slow categorical judgement to a fast
+    continuous score manufactures precision by summing unlike things.
     """
     end = date(2026, 6, 26)
     rising = [100.0 + index * 0.2 for index in range(700)]
     prices = {"SMH": _dated(rising, end), "QQQ": _dated(rising, end), "SPY": _dated(rising, end)}
     args = (prices, [(end, 20.0)], [(end - timedelta(days=i), 4.0) for i in reversed(range(100))])
     tail = (copy.deepcopy(DEFAULT_CONFIG), end, [(end, 55.0)], [(end, 20.0)], {end: 25})
+    names = DEFAULT_CONFIG["tickers"]["hyperscalers"]
 
-    quiet = _compute_index(*args, {"f1_score": None, "f3_score": None}, *tail)
-    screaming = _compute_index(
-        *args,
-        {
-            "f1_score": 100.0,
-            "f3_score": 100.0,
-            "capex": dict.fromkeys(DEFAULT_CONFIG["tickers"]["hyperscalers"], "cutting"),
-            "good_news_stock_down": "yes",
+    def observed(capex_state: str, reaction: str) -> dict:
+        return {
+            "capex": dict.fromkeys(names, capex_state),
+            "good_news_stock_down": reaction,
             "effective_date": "2026-06-01",
-        },
-        *tail,
-    )
+            "fetched_at": "2026-06-01T00:00:00+00:00",
+            "source": "openai",
+        }
 
-    assert quiet["warning"]["score"] == screaming["warning"]["score"]
-    assert {p["id"] for p in quiet["warning"]["pillars"]} == set(WARNING_WEIGHTS)
-    assert screaming["fundamental_overlay"]["available"] is True
-    assert screaming["fundamental_overlay"]["capex_stress"] == 100.0
+    unobserved = _compute_index(*args, {"f1_score": None, "f3_score": None}, *tail)
+    supportive = _compute_index(*args, observed("raising", "no"), *tail)
+    adverse = _compute_index(*args, observed("cutting", "yes"), *tail)
+
+    # Every Warning is identical: the channel is not a term in the score.
+    scores = {
+        snapshot["warning"]["score"]
+        for snapshot in (unobserved, supportive, adverse)
+    }
+    assert len(scores) == 1
+    assert {p["id"] for p in unobserved["warning"]["pillars"]} == set(WARNING_WEIGHTS)
+    # And it never touches coverage, so a missing observation cannot suppress a
+    # band or silently redistribute weight onto the technical sensors.
+    assert len({s["warning"]["coverage"] for s in (unobserved, supportive, adverse)}) == 1
+
+    assert unobserved["fundamental_context"]["state"] == "unknown"
+    assert unobserved["fundamental_context"]["evidence_quality"] == "unavailable"
+    assert supportive["fundamental_context"]["state"] == "supportive"
+    assert adverse["fundamental_context"]["state"] == "adverse"
+    assert adverse["fundamental_context"]["evidence_quality"] == "complete"
+
+
+def test_a_fresh_but_empty_observation_is_available_to_show_and_not_usable():
+    """Collected-but-determined-nothing must not count as evidence.
+
+    `available` is about timing (there is an effective, non-stale record to
+    display); `usable` is about content. An LLM run that failed to extract
+    anything produces a perfectly fresh observation that knows nothing — and if
+    that counted, repeated extraction failures would slowly accumulate study
+    exposure until the fundamental rows reported a measurable 0/8 for a channel
+    that had never seen a thing.
+    """
+    config = copy.deepcopy(DEFAULT_CONFIG)
+    names = config["tickers"]["hyperscalers"]
+    as_of = date(2026, 6, 26)
+    base = {
+        "effective_date": "2026-06-01",
+        "fetched_at": "2026-06-01T00:00:00+00:00",
+        "source": "openai",
+    }
+
+    empty = fundamental_context(
+        {**base, "capex": dict.fromkeys(names, "unknown"), "good_news_stock_down": "unknown"},
+        config, as_of,
+    )
+    assert empty["state"] == "unknown"
+    assert empty["available"] is True   # there is a record, and it has a date
+    assert empty["usable"] is False     # but it says nothing
+
+    # One real signal is enough to be usable, on partial evidence.
+    partial = fundamental_context(
+        {
+            **base,
+            "capex": {names[0]: "cutting", **dict.fromkeys(names[1:], "unknown")},
+            "good_news_stock_down": "unknown",
+        },
+        config, as_of,
+    )
+    assert partial["state"] == "adverse"
+    assert partial["usable"] is True
+    assert partial["evidence_quality"] == "partial"
+
+    # Stale is neither available nor usable — `available` means effective *and*
+    # non-stale. What survives is `state`, which the card renders on its own
+    # (with the stale badge) so the last thing observed stays visible.
+    stale = fundamental_context(
+        {
+            **base,
+            "effective_date": "2026-01-01",
+            "capex": dict.fromkeys(names, "cutting"),
+            "good_news_stock_down": "yes",
+        },
+        config, as_of,
+    )
+    assert stale["state"] == "adverse"
+    assert stale["stale"] is True
+    assert stale["available"] is False
+    assert stale["usable"] is False
+
+    # Nothing collected at all: neither.
+    absent = fundamental_context({}, config, as_of)
+    assert (absent["available"], absent["usable"]) == (False, False)
+
+
+def test_the_live_reading_publishes_the_same_fields_as_the_record():
+    """"Same shape" has to mean the same fields, not the same ones it needs.
+
+    The frontend types both payloads as one interface, so a field present on the
+    record and missing from the live reading is an undefined at runtime that
+    TypeScript cannot catch across a trusted server boundary.
+    """
+    config = copy.deepcopy(DEFAULT_CONFIG)
+    names = config["tickers"]["hyperscalers"]
+    as_of = date(2026, 6, 26)
+    observation = {
+        "effective_date": "2026-06-01",
+        "fetched_at": "2026-06-01T00:00:00+00:00",
+        "source": "openai",
+        "capex": dict.fromkeys(names, "cutting"),
+        "good_news_stock_down": "yes",
+    }
+
+    record = fundamental_context(observation, config, as_of)
+    live = current_observation(observation, config, as_of)
+    assert set(record) <= set(live)
+    assert (live["state"], live["usable"]) == ("adverse", True)
+
+    # A just-collected observation is shown but is not yet in force, so it is
+    # available to read and not yet usable as evidence.
+    pending = current_observation(
+        {**observation, "effective_date": "2026-07-01"}, config, as_of
+    )
+    assert (pending["pending"], pending["available"], pending["usable"]) == (True, True, False)
+
+    # And an extraction that determined nothing is never usable, however fresh.
+    empty = current_observation(
+        {**observation, "capex": dict.fromkeys(names, "unknown"), "good_news_stock_down": "unknown"},
+        config, as_of,
+    )
+    assert (empty["state"], empty["usable"]) == ("unknown", False)
+
+
+def test_pre_rename_snapshots_keep_their_recorded_fundamental_evidence():
+    """The rename shipped without a methodology bump, so those rows were never reseeded.
+
+    Reading only the new key would turn real observations into `unknown` and
+    silently drop historical Path colours and legitimate study exposure.
+    """
+    names = DEFAULT_CONFIG["tickers"]["hyperscalers"]
+    legacy = {
+        "methodology": rms.METHODOLOGY,
+        "date": "2026-07-01",
+        "state": {"score": 10.0, "band": "stable"},
+        "warning": {"score": 20.0, "band": "stable"},
+        "fundamental_overlay": {
+            "available": True,
+            "pending": False,
+            "stale": False,
+            "effective_date": "2026-06-20",
+            "capex": {names[0]: "cutting", **dict.fromkeys(names[1:], "raising")},
+            "good_news_stock_down": "yes",
+            "source": "openai",
+            "fetched_at": "2026-06-19T00:00:00+00:00",
+        },
+    }
+
+    parsed = rms._parse_snapshot(json.dumps(legacy))
+    context = parsed["fundamental_context"]
+    assert context["state"] == "adverse"
+    assert context["evidence_quality"] == "complete"
+    assert context["usable"] is True
+    assert context["effective_date"] == "2026-06-20"
+
+    # A pending legacy overlay carried no facts, so it stays unknown rather than
+    # inventing an observation for a session nobody had looked at.
+    blank = json.loads(json.dumps(legacy))
+    blank["fundamental_overlay"] = {"pending": True, "stale": False, "capex": None}
+    blank_context = rms._parse_snapshot(json.dumps(blank))["fundamental_context"]
+    assert blank_context["state"] == "unknown"
+    assert blank_context["evidence_quality"] == "unavailable"
+    assert blank_context["usable"] is False
+
+    # A row already carrying the new key is left exactly as written.
+    modern = json.loads(json.dumps(legacy))
+    modern["fundamental_context"] = {"state": "supportive", "usable": True}
+    assert rms._parse_snapshot(json.dumps(modern))["fundamental_context"]["state"] == "supportive"
+
+
+def test_evidence_quality_ranks_what_an_operator_needs_first():
+    names = DEFAULT_CONFIG["tickers"]["hyperscalers"]
+    config = copy.deepcopy(DEFAULT_CONFIG)
+    full = dict.fromkeys(names, "raising")
+    partial = {names[0]: "raising", **dict.fromkeys(names[1:], "unknown")}
+
+    def quality(capex, reaction, *, observed=True, stale=False, source="openai"):
+        return rms._evidence_quality(
+            capex, reaction, names, observed=observed, stale=stale, source=source
+        )
+
+    assert quality(full, "no") == "complete"
+    assert quality(partial, "no") == "partial"
+    assert quality(full, None) == "partial"          # reaction unknown
+    assert quality(full, "no", source="manual") == "manual"
+    assert quality(full, "no", stale=True) == "stale"
+    # Nothing collected outranks every other grade.
+    assert quality(full, "no", observed=False, stale=True, source="manual") == "unavailable"
+    assert set(rms.EVIDENCE_QUALITY) >= {quality(full, "no"), quality(partial, "no")}
+    assert config["tickers"]["hyperscalers"] == names
 
 
 def test_capex_score_separates_holding_from_raising():
@@ -375,10 +614,12 @@ async def test_legacy_numeric_fundamentals_do_not_leak_into_v4(monkeypatch):
 
     result = await rms.get_fundamental_overrides(object())
 
-    assert result["methodology"] == "v4"
+    assert result["methodology"] == rms.METHODOLOGY
     assert result["f1_score"] is None
     assert result["f3_score"] is None
-    assert result["good_news_stock_down"] == "mixed"
+    # Not "mixed": an unreadable blob is an absence of an observation, and
+    # "mixed" is a genuinely observed mixed reaction.
+    assert result["good_news_stock_down"] == "unknown"
 
 
 @pytest.mark.asyncio
@@ -442,11 +683,12 @@ async def test_unlock_does_not_redate_a_fundamental_observation(monkeypatch):
 
     async def fake_update(_db, _key, value):
         saved.update(json.loads(value))
+        return None
 
     monkeypatch.setattr(rms, "get_fundamental_overrides", fake_get)
-    monkeypatch.setattr(rms, "update_setting", fake_update)
+    monkeypatch.setattr(rms.settings_store, "upsert_setting", fake_update)
 
-    result = await rms.set_fundamental_overrides(object(), locked=False)
+    result = await rms.set_fundamental_overrides(_CommitOnlyDB(), locked=False)
 
     assert result["locked"] is False
     assert result["fetched_at"] == stored["fetched_at"]
@@ -476,14 +718,22 @@ async def test_manual_fundamentals_are_categorical_and_derived(monkeypatch):
 
     async def fake_update(_db, _key, value):
         saved.update(json.loads(value))
+        return None
 
     monkeypatch.setattr(rms, "get_fundamental_overrides", fake_get)
-    monkeypatch.setattr(rms, "update_setting", fake_update)
+    monkeypatch.setattr(rms.settings_store, "upsert_setting", fake_update)
+    # A manual save now also appends to the point-in-time series.
+    monkeypatch.setattr(rms, "record_fundamental_observation", _skip_recording)
     capex = {names[0]: "cutting", **dict.fromkeys(names[1:], "holding")}
 
+    db = _CommitOnlyDB()
     result = await rms.set_fundamental_overrides(
-        object(), capex=capex, good_news_stock_down="mixed"
+        db, capex=capex, good_news_stock_down="mixed"
     )
+    # The series row is a second write after update_setting's own commit, so the
+    # writer has to take one -- record_fundamental_observation deliberately does
+    # not, or it would steal update_regime_monitor's transaction boundary.
+    assert db.commits == 1
 
     assert result["f1_score"] == 62.5  # one cutting (100) + three holding (50)
     assert result["f3_score"] is None
@@ -498,7 +748,9 @@ async def test_manual_fundamentals_are_categorical_and_derived(monkeypatch):
 async def test_prior_snapshot_is_immutable_without_explicit_rebuild(db_session):
     snapshot_date = date(2026, 6, 26)
     first = {
-        "methodology": "v4",
+        # Must be the *current* methodology: a foreign row does not parse, so it
+        # reads as absent and the rewrite guard never comes into play.
+        "methodology": rms.METHODOLOGY,
         "date": snapshot_date.isoformat(),
         "state": {"score": 10.0, "band": "stable"},
         "warning": {"score": 20.0, "band": "stable"},
@@ -571,6 +823,8 @@ async def test_routine_can_refresh_latest_trading_session_after_civil_day_rolls(
     monkeypatch.setattr(rms.breadth_service, "compute_breadth_details", fake_breadth)
     monkeypatch.setattr(rms, "_latest_snapshot_row", fake_latest)
     monkeypatch.setattr(rms, "_upsert_snapshot", fake_upsert)
+    monkeypatch.setattr(rms, "get_fundamental_observations", _no_observations)
+    monkeypatch.setattr(rms, "record_fundamental_observation", _skip_recording)
 
     result = await rms.update_regime_monitor(FakeDB())
 
@@ -636,6 +890,8 @@ async def test_a_stale_sensor_revision_reseeds_stored_history(
         ("_fetch_fred_series", fake_fred),
         ("_latest_snapshot_row", fake_latest),
         ("_upsert_snapshot", fake_upsert),
+        ("get_fundamental_observations", _no_observations),
+        ("record_fundamental_observation", _skip_recording),
     ):
         monkeypatch.setattr(rms, name, value)
     monkeypatch.setattr(rms.breadth_service, "compute_breadth_details", fake_breadth)
@@ -722,7 +978,7 @@ def test_compute_index_uses_one_max_price_vote_and_has_no_combined_score():
     price = next(p for p in result["state"]["pillars"] if p["id"] == "price")
     sensor_scores = [sensor["score"] for sensor in price["sensors"] if sensor["score"] is not None]
     assert price["score"] == max(sensor_scores)
-    assert result["methodology"] == "v4"
+    assert result["methodology"] == rms.METHODOLOGY
     assert "combined" not in result
     assert result["basket"]["members_available"] == 25