S3-E.3-followup: hedera_dual 真实证 + adapter 单测 + KNOWN_BROKEN_MIXED 立 ledger

## 背景:用户反向压测发现 S3-E.3 (commit 2d007f2) 验证不足

前一 commit msg 说 "L3 PASS = 双协议路由生效",**但**:
  - L3 只验 vegeta target schema 生成成功(exit=0)
  - 从未真打 HTTP 验返码
  - 新 adapter 0 个专属单测,只靠 cli e2e 偶然碰
  - body 里 `params: ['0.0.801']` 缺 'latest' + 用 3-part ID,我看到了却写成 "已知 defer" 而未承认是当前 commit 的真实生产 blocker

## 真实证(C1 — 真打 endpoint)

  curl POST https://mainnet.hashio.io/api -d \
    '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0.0.801"]}'
  → HTTP 400 {"error":{"code":-32602,"message":"Invalid parameter 0:
     Expected 0x prefixed string representing the address (20 bytes),
     value: 0.0.801"}}

正确 payload 真返 balance:
  curl POST ... -d '{"...","params":["0x0000000000000000000000000000000000000002","latest"]}'
  → HTTP 200 {"result":"0xdc190f51555e27b8e0800","jsonrpc":"2.0","id":1}

Mirror REST 真返 evm_address 字段:
  curl https://mainnet-public.mirrornode.hedera.com/api/v1/accounts/0.0.2
  → {"account":"0.0.2","evm_address":"0x0000000000000000000000000000000000000002",
     "balance":{"balance":1663012637744658}}

eth_blockNumber 纯活性:HTTP 200 result=0x5b10a68 ✓

## adapter 专属单测(C2/C3 — test_11, test_12)

(1) test_hedera_dual_adapter_routing —
    - REST method 'GET /api/v1/accounts/{addr}' → GET Mirror URL,address 入 path
    - eth_blockNumber → POST Hashio URL,empty params
    - eth_getBalance + param_format='address_latest' → POST Hashio,
      params=[addr, 'latest'](adapter 自身给得对!)
    - 缺 _meta.json_rpc_url → ValueError
    - 缺 BLOCKCHAIN_NODE → RuntimeError

(2) test_is_jsonrpc_method_regex —
    - 7 个 JSON-RPC namespace(eth_/net_/web3_/debug_/trace_)正路由
    - REST path / camelCase / 前缀干扰("ethReporter") 全否路由

L1 现 12/12 PASS(原 10 + 新 2)

## 关键发现:adapter 本身 OK,生产 mixed 失败在上游

test_11 证明 adapter 给 [addr, 'latest'] 正确 — 当 cli.py 传对 param_format。
但生产链路有两个上游 bug:

  PARAM    cli.py L40 `tpl.get("params", {})` 读 fetcher config,应读
           `tpl.get("param_formats", {})`。adapter 收 param_format=""
           → JsonRpcAdapter `_build_params("")` → 默认 [] → 缺 'latest'。
           影响所有 JSON-RPC chain 的 eth_* 调用。Fix wave: cli-param-bug

  ADDR_FMT fetch_active_accounts.py 不支持 hedera,只能吐 3-part 0.0.N。
           Mirror REST 接受(path 用原 ID),JSON-RPC Relay 要 0x 前缀
           20-byte hex。Mirror /accounts/{id} 返 evm_address 字段可用,
           但 fetcher 没接。Fix wave: S4(per-chain account fetcher)

## 诚实 ledger

(1) tests/test_chain_adapters.py 加 KNOWN_BROKEN_MIXED dict:
    {hedera: ("PARAM+ADDR_FMT", "cli-param-bug + S4", evidence)}
    不强制 assert,因为没有 mixed-path 自动测;留位给未来 wave。

(2) config/chains/hedera.json _meta 加 known_broken_mixed 字段:
    status: ADAPTER_OK_BUT_UPSTREAM_BROKEN
    evidence_date: 2026-05-24
    live_http_test: 上述 curl 命令 + HTTP 400 实证
    blockers: 上述 PARAM / ADDR_FMT 两条

## 校正前一 commit 的过度声明

commit 2d007f2 该说:
  "hedera_dual adapter 已实现并通过 L1 schema 验证;mixed 真生产链路
   阻于 cli.py PARAM bug 和 fetcher ADDR_FMT 缺失,见 KNOWN_BROKEN_MIXED。"
而不是:
  "L3 PASS → 双协议路由生效"(暗示生产可跑,实际不可)

adapter 本身的工作不撤回(test_11 实证 routing 正确),但 hedera 不能
算 "broken set 14→13",该算 "broken_cli 14→13 + broken_mixed 0→1"。

## 自审 E1-E5(本 commit)

E1 调研:回头验 docs/zh/chains/14-hedera.md E1-E15 + 现场 curl
E2 无降级:不撤 adapter / 不砍 method;承认 mixed 阻于上游,显式 ledger
E3 实证:真打 4 个 HTTP request 各拿返码 / 12/12 单测 PASS
E4 parallel-entry-trap:无
E5 ledger 单调:KNOWN_BROKEN_CLI 仍 13(hedera CLI 路径 single 健康);
                新建 KNOWN_BROKEN_MIXED = 1(hedera)— 这是新分类,
                不算 CLI ledger 增长

Author: StayHungryStayFoolish

config/chains/hedera.json

@@ -58,6 +58,16 @@
     "adapter_family_assigned_at": "2026-05-24T05:24:00.591042Z",
     "adapter_family_upgraded_at": "2026-05-24T18:00:00Z",
     "adapter_family_upgrade_note": "S3-E.3: was 'rest' (broken — couldn't route eth_*); upgraded to dual-protocol adapter that routes per-method between Mirror REST and JSON-RPC Relay.",
+    "known_broken_mixed": {
+      "status": "ADAPTER_OK_BUT_UPSTREAM_BROKEN",
+      "evidence_date": "2026-05-24",
+      "live_http_test": "curl POST mainnet.hashio.io/api eth_getBalance params=['0.0.801'] → HTTP 400 'Expected 0x prefixed string representing the address (20 bytes)'",
+      "blockers": [
+        "PARAM: cli.py L40 reads tpl['params'] (fetcher config) instead of tpl['param_formats'] (method→format) — eth_getBalance call gets [addr] not [addr, 'latest']. Affects all JSON-RPC chains.",
+        "ADDR_FMT: fetch_active_accounts.py does not produce EVM-format addresses for hedera (only 3-part 0.0.N). Mirror REST works (path uses raw ID), JSON-RPC Relay requires 0x-prefixed 20-byte hex."
+      ],
+      "fix_wave": "cli-param-bug (PARAM) + S4 (ADDR_FMT)"
+    },
     "json_rpc_url": "https://mainnet.hashio.io/api",
     "rest_paths": {
       "GET /api/v1/accounts/{addr}": {"method": "GET", "path": "/api/v1/accounts/{address}"},

tests/test_chain_adapters.py

@@ -370,6 +370,34 @@ def test_evm_compat_5chains_standard_enum():
 assert len(KNOWN_BROKEN_CLI) == 13, f"KNOWN_BROKEN_CLI must have exactly 13 entries (baseline 16 minus aptos S3-E.1 minus algorand S3-E.2 minus hedera S3-E.3), got {len(KNOWN_BROKEN_CLI)}"
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# KNOWN_BROKEN_MIXED — chains whose `single` benchmark passes L1-CLI test_10
+# but whose `mixed` (multi-method) path is broken in production (live HTTP
+# would 4xx/5xx). Documented here for honesty; not auto-asserted because we
+# don't yet have a `mixed` equivalent of test_10. When a future wave adds a
+# mixed-path test, this dict graduates to enforced invariant.
+#
+# Format: (chain, failure_layer, fix_wave, evidence)
+#   failure_layer:
+#     PARAM     — cli.py reads tpl['params'] (fetcher config) when it should
+#                 read tpl['param_formats'] (method→shape). Affects all
+#                 JSON-RPC chains' eth_* calls (missing 'latest'). Fix wave: cli-param-bug
+#     ADDR_FMT  — fetch_active_accounts.py doesn't know chain-specific address
+#                 transformations (hedera 3-part 0.0.N → EVM 0x...0N).
+#                 Fix wave: S4 (per-chain account fetcher)
+# ─────────────────────────────────────────────────────────────────────────────
+KNOWN_BROKEN_MIXED = {
+    "hedera": (
+        "PARAM+ADDR_FMT", "cli-param-bug + S4",
+        "S3-E.3 C1 实证:adapter routing 正确 (test_11 PASS),但 (1) cli.py L40 "
+        "读 tpl['params'] 应读 tpl['param_formats'] → eth_getBalance 缺 'latest'; "
+        "(2) fetch_active_accounts.py 不支持 hedera → 喂 3-part ID 0.0.N 给 Hashio "
+        "返 HTTP 400 'Expected 0x prefixed string representing the address (20 bytes)'. "
+        "需 fetcher 拿 mirror /accounts/{id} 的 evm_address 字段。"
+    ),
+}
+
+
 def _sample_address_for(family: str) -> str:
     """Return a family-appropriate sample address for the build-target probe.
 
@@ -477,6 +505,110 @@ def test_cli_build_target_all_36_chains():
     _ok(f"{len(healthy)}/36 healthy + {len(actually_broken)} known-broken (set matches expected)")
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Test 11: HederaDualAdapter — per-request protocol routing
+# ─────────────────────────────────────────────────────────────────────────────
+def test_hedera_dual_adapter_routing():
+    print("\n[11] HederaDualAdapter per-method protocol routing")
+    import base64 as _b64
+    import json as _json
+    from chain_adapters.hedera_dual import HederaDualAdapter, _is_jsonrpc_method
+
+    _saved = os.environ.get("BLOCKCHAIN_NODE")
+    os.environ["BLOCKCHAIN_NODE"] = "hedera"
+    try:
+        a = HederaDualAdapter()
+        mirror_url = "https://mainnet-public.mirrornode.hedera.com"
+        # REST path-style method → GET against passed rpc_url
+        tgt = a.build_vegeta_target(
+            method="GET /api/v1/accounts/{addr}",
+            address="0.0.2", rpc_url=mirror_url,
+        )
+        assert tgt["method"] == "GET", f"REST should be GET, got {tgt['method']}"
+        assert tgt["url"] == f"{mirror_url}/api/v1/accounts/0.0.2", f"got {tgt['url']}"
+        assert "body" not in tgt or not tgt.get("body"), "GET should have no body"
+        _ok("REST method → GET Mirror URL with address in path")
+
+        # JSON-RPC method → POST against _meta.json_rpc_url, NOT rpc_url
+        tgt = a.build_vegeta_target(
+            method="eth_blockNumber", address="",
+            rpc_url=mirror_url, param_format="no_params",
+        )
+        assert tgt["method"] == "POST", f"JSON-RPC should be POST, got {tgt['method']}"
+        assert tgt["url"] == "https://mainnet.hashio.io/api", \
+            f"JSON-RPC URL should come from _meta.json_rpc_url, got {tgt['url']}"
+        body = _json.loads(_b64.b64decode(tgt["body"]).decode())
+        assert body["method"] == "eth_blockNumber"
+        assert body["params"] == []
+        _ok("eth_blockNumber → POST Hashio with empty params")
+
+        # eth_getBalance routing → POST with [addr, "latest"] when param_format=address_latest
+        tgt = a.build_vegeta_target(
+            method="eth_getBalance",
+            address="0x0000000000000000000000000000000000000002",
+            rpc_url=mirror_url, param_format="address_latest",
+        )
+        assert tgt["url"] == "https://mainnet.hashio.io/api"
+        body = _json.loads(_b64.b64decode(tgt["body"]).decode())
+        assert body["params"] == ["0x0000000000000000000000000000000000000002", "latest"], \
+            f"params should be [addr, 'latest'], got {body['params']}"
+        _ok("eth_getBalance routes to Hashio with [addr, latest] payload")
+
+        # Missing _meta.json_rpc_url → ValueError (defensive check)
+        # We test by temporarily mutating the cached chain dict
+        a2 = HederaDualAdapter()
+        a2._load_chain("hedera")  # populate cache
+        original = a2._chain_cache["hedera"]["_meta"].pop("json_rpc_url")
+        try:
+            try:
+                a2.build_vegeta_target(method="eth_blockNumber", address="",
+                                       rpc_url=mirror_url, param_format="no_params")
+                assert False, "should have raised ValueError when json_rpc_url missing"
+            except ValueError as e:
+                assert "json_rpc_url" in str(e), f"error msg should mention json_rpc_url: {e}"
+            _ok("Missing _meta.json_rpc_url raises ValueError")
+        finally:
+            a2._chain_cache["hedera"]["_meta"]["json_rpc_url"] = original
+
+        # Missing BLOCKCHAIN_NODE → RuntimeError
+        del os.environ["BLOCKCHAIN_NODE"]
+        try:
+            a.build_vegeta_target(method="eth_blockNumber", address="",
+                                  rpc_url=mirror_url, param_format="no_params")
+            assert False, "should have raised RuntimeError when BLOCKCHAIN_NODE missing"
+        except RuntimeError as e:
+            assert "BLOCKCHAIN_NODE" in str(e)
+        _ok("Missing BLOCKCHAIN_NODE raises RuntimeError")
+    finally:
+        if _saved is None:
+            os.environ.pop("BLOCKCHAIN_NODE", None)
+        else:
+            os.environ["BLOCKCHAIN_NODE"] = _saved
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Test 12: _is_jsonrpc_method regex boundary
+# ─────────────────────────────────────────────────────────────────────────────
+def test_is_jsonrpc_method_regex():
+    print("\n[12] _is_jsonrpc_method routing regex boundary")
+    from chain_adapters.hedera_dual import _is_jsonrpc_method
+    # Positive cases — JSON-RPC namespaces
+    for m in ["eth_getBalance", "eth_call", "eth_blockNumber",
+              "net_version", "web3_clientVersion",
+              "debug_traceTransaction", "trace_block"]:
+        assert _is_jsonrpc_method(m), f"{m!r} should route to JSON-RPC"
+    # Negative cases — REST path keys, never JSON-RPC
+    for m in ["GET /api/v1/accounts/{addr}",
+              "GET /api/v1/balances?account.id={addr}",
+              "POST /api/v1/contracts/call",
+              "mirror_account_query",  # legacy logical name
+              "getAccount",            # camelCase non-eth
+              "ethReporter",           # starts with "eth" but no underscore
+              "_eth_getBalance"]:      # leading underscore
+        assert not _is_jsonrpc_method(m), f"{m!r} should NOT route to JSON-RPC"
+    _ok("regex correctly distinguishes 7 JSON-RPC namespaces from REST/other forms")
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Main
 # ─────────────────────────────────────────────────────────────────────────────
@@ -492,6 +624,8 @@ def main():
         test_jsonrpc_s3a_new_formats,
         test_evm_compat_5chains_standard_enum,
         test_cli_build_target_all_36_chains,
+        test_hedera_dual_adapter_routing,
+        test_is_jsonrpc_method_regex,
     ]
     print(f"Running {len(tests)} test groups for chain_adapters")
     for t in tests: