fix(shared): kill 9 real json_native mutants, document 5 as equivalent (#250)

[cdeust]

Summary

Closes #250. mcp_server/shared/json_native.py is this repo's demonstrated
mutation-testing module ([tool.mutmut]'s committed scope) — 14 of its 43
mutants survived. Reproduced exactly (uv run mutmut run, no arguments):
43/43 killed 29, survived 14, the same 14 IDs the issue lists.

Triage:

• 9 real gaps (mutants 34-42): the tolist()-failure debug log
  (logger.debug("tolist() conversion failed for %r: %s", type(obj), exc))
  had no test asserting the format string or either argument — a dropped
  arg, a swapped arg, or a reworded message all survived silently.
• 5 documented equivalents (mutants 11, 17, 21, 22, 23) — verified, not
  asserted:
  • bytes.decode("utf-8", …) vs "UTF-8": codecs.lookup() is
    case-insensitive — codecs.lookup("utf-8") is codecs.lookup("UTF-8")
    is True.
  • typing.cast("SupportsFloat", obj)'s type-hint string: cast's
    source (inspect.getsource(typing.cast)) is literally return val —
    the first argument is never read at runtime, for any input.

Fix

1. Added TestTolistFailureLogging to tests_py/shared/test_json_native.py:
   forces a tolist() that raises, then asserts the exact log record
   (record.msg, both record.args) via caplog — kills all 9 real
   survivors.
2. Documented the 5 equivalents at their use sites (§12.1) with the
   verification command, not just a claim.
3. Boy-scout (§14): to_json_native was already 48 lines before this
   change — over this repo's own 40-line/method convention (CLAUDE.md) and
   at the coding-standards.md §4 50-line hard cap once my initial fix's
   documentation comments pushed it to 60. Split into
   _decode_bytes/_coerce_number/_tolist_fallback + a thin dispatcher,
   each new helper under 20 lines. Behavior-preserving: all 14 pre-existing
   tests pass byte-for-byte unchanged (the proof), and the whole local
   suite is green (6527 passed, 0 failed).

Verification

• Scoped mutation run (committed [tool.mutmut] scope, uv run mutmut run
  with no arguments) after the fix: 51 mutants (split creates more mutation
  sites) → 46 killed, 0 surviving non-equivalent mutants — the same 5
  equivalents, renumbered under the new helper names
  (_decode_bytes__mutmut_6, _coerce_number__mutmut_{2,6,7,8}).
• ruff check / ruff format --check: clean.
• pyright: 0 errors, 0 warnings, 0 informations on both touched files.
• Local full suite: 6527 passed (this machine's local count differs from
  CI's per repo convention — CI is the source of truth for the number
  quoted at merge time).

Completion Ledger

Path introduced by this diff	Asserting test / evidence
_decode_bytes returns decoded str, invalid bytes replaced	TestContainers::test_bytes_decode_to_str, test_invalid_utf8_bytes_replaced_not_raised (pre-existing, unchanged, still pass against the extracted helper)
_decode_bytes — mutmut_11 equivalent (case-insensitive codec name)	Documented equivalent at use site; verified codecs.lookup("utf-8") is codecs.lookup("UTF-8") — no test possible or needed
_coerce_number returns float for Decimal	TestScalars::test_decimal_becomes_float (pre-existing, unchanged)
_coerce_number returns None on TypeError/ValueError (complex etc.) → caller falls through	Covered transitively by TestFallback::test_unknown_object_stringifies_rather_than_crashing (no complex-specific test existed pre-change or post-change; behavior unchanged)
_coerce_number — mutmut_17/21/22/23 equivalent (cast's type-hint string unused at runtime)	Documented equivalent at use site; verified via inspect.getsource(typing.cast)
_tolist_fallback success path recurses into to_json_native	TestContainers::test_numpy_array_becomes_list, TestScalars::test_numpy_float32_becomes_python_float/test_numpy_int64_becomes_python_int/test_numpy_bool_becomes_native (pre-existing, unchanged)
_tolist_fallback failure path: logs exact format string + (type(obj), exc), returns sentinel → caller stringifies	New: TestTolistFailureLogging::test_logs_type_and_exception_then_falls_back_to_str
to_json_native dispatcher: every branch unchanged in order/semantics	Full existing 14-test file green, unchanged assertions

No unmapped paths. No deviations from the issue's acceptance criteria — all
three checkboxes met: 0 surviving non-equivalent mutants; every survivor
triaged (killed or documented-equivalent with a written, verified
rationale); the kill test exercises the actual failure-path signal
(caplog), not a downstream side effect.

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