fix(envelope): classify malformed upstream JSON as UPSTREAM_ERROR

Addresses Codex review on PR #2 (P2, shared/envelope.py:113).

json.JSONDecodeError subclasses ValueError, so when Health Canada answers
HTTP 200 with an HTML error page, httpx's .json() raised inside a guarded
tool and fell through to the ValueError arm — reporting INVALID_INPUT and
blaming the caller for an upstream outage. It also broke live tests in a
confusing way: assert_live_or_transient tolerates only UPSTREAM_ERROR,
RATE_LIMITED and UPSTREAM_UNAVAILABLE, so a real outage failed as if the
arguments were wrong.

Handle JSONDecodeError ahead of the ValueError arm. A second test pins that
genuine argument-validation ValueErrors still return INVALID_INPUT, so the
fix cannot swallow real caller errors.

Verified the mechanism rather than assuming it: JSONDecodeError does
subclass ValueError, httpx .json() raises it on an HTML body, and both the
drug and nutrient clients call .json() inside the guarded path.

Also records in STATE.md that the same masking is latent in ~40 ValueError
arms downstream of shared/http.py:api_get, which has no decode guard. That
is pre-existing and best fixed once inside api_get; left out of this PR.

Author: mariomeyer

.planning/STATE.md

@@ -89,6 +89,16 @@ Open defect (found 2026-07-26, deferred to its own phase):
   behind an env-var key like Manitoba 511. Alberta AHS, parks, forest-area and
   Saskatchewan/Manitoba Hub services were probed at the same time and are healthy.
 
+- **Malformed-JSON masking is broader than the spot Codex flagged.** `upstream_guard`
+  is fixed, which covers drug_database and nutrient_file (they use their own clients).
+  But `shared/http.py:api_get` returns `response.json()` with no decode guard, and
+  ~40 `except ValueError -> INVALID_INPUT` arms across statcan, ircc, manitoba,
+  saskatchewan, nova_scotia, british_columbia and datastore sit downstream of it.
+  An upstream HTML error page therefore still surfaces as caller error in those
+  modules. Pre-existing, not introduced by Phase 20.1. The high-leverage fix is one
+  decode guard inside `api_get` rather than 40 call-site edits — deliberately left
+  out of PR #2 to keep it scoped.
+
 Remaining backlog (not defects):
 
 - `.planning/todos/pending/2026-04-12-research-cross-canada-er-wait-times-datasets.md`

src/mcp_canada/shared/envelope.py

@@ -1,6 +1,7 @@
 """Response envelope and error builders for standardized tool responses."""
 
 import functools
+import json
 import httpx
 from collections.abc import Callable
 
@@ -109,6 +110,15 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
                     f"{api_name} request failed: {type(exc).__name__}: {exc}",
                     lang=lang,
                 )
+            except json.JSONDecodeError as exc:
+                # Must precede the ValueError arm — JSONDecodeError subclasses it.
+                # An upstream HTML error page reaching httpx's .json() is an
+                # upstream failure, not a bad argument from the caller.
+                return make_error(
+                    "UPSTREAM_ERROR",
+                    f"{api_name} returned a malformed JSON body: {exc}",
+                    lang=lang,
+                )
             except ValueError as exc:
                 return make_error("INVALID_INPUT", str(exc), lang=lang)
         return wrapper

tests/test_envelope.py

@@ -120,6 +120,47 @@ async def boom(lang: str = "en") -> dict:
         assert result["error"]["code"] == "UPSTREAM_ERROR"
         assert "503" in result["error"]["message"]
 
+    @pytest.mark.asyncio
+    async def test_malformed_json_body_is_an_upstream_error_not_invalid_input(self):
+        """HTTP 200 carrying HTML must blame the upstream, not the caller.
+
+        json.JSONDecodeError subclasses ValueError, so httpx's .json() raising on
+        a Health Canada error page fell through to the ValueError handler and came
+        back as INVALID_INPUT — a valid tool call blamed for an upstream outage.
+        assert_live_or_transient tolerates only UPSTREAM_ERROR/RATE_LIMITED/
+        UPSTREAM_UNAVAILABLE, so this also broke live tests with a misleading code.
+        """
+        import httpx
+        from mcp_canada.shared.envelope import upstream_guard
+
+        @upstream_guard("test-api")
+        async def boom(lang: str = "en") -> dict:
+            response = httpx.Response(
+                200,
+                text="<html>503 Service Unavailable</html>",
+                request=httpx.Request("GET", "https://example.test"),
+            )
+            return response.json()
+
+        result = await boom()
+        assert result["error"]["code"] == "UPSTREAM_ERROR", (
+            f"malformed upstream JSON must not be reported as caller error: {result}"
+        )
+        assert "test-api" in result["error"]["message"]
+
+    @pytest.mark.asyncio
+    async def test_genuine_value_error_is_still_invalid_input(self):
+        """The JSONDecodeError fix must not swallow real argument validation."""
+        from mcp_canada.shared.envelope import upstream_guard
+
+        @upstream_guard("test-api")
+        async def boom(lang: str = "en") -> dict:
+            raise ValueError("din must be 8 digits")
+
+        result = await boom()
+        assert result["error"]["code"] == "INVALID_INPUT"
+        assert "din must be 8 digits" in result["error"]["message"]
+
     @pytest.mark.asyncio
     async def test_lang_is_propagated(self):
         import httpx