Closes #1115

Summary

Pivot to friend-injected process_frame for HTTP/2 hermetic dispatcher coverage. PR #1114 (Round 5 multiplier scaling) measured 0pp coverage delta on src/protocols/http2/http2_client.cpp under coverage instrumentation because the SETTINGS handshake now exceeds 15 s on shared CI runners — beyond any reasonable wait_for budget. Coverage Analysis run 25562347620 showed test #5868 FAILED at exactly 15.175 s and test #5869 hit the 300 s ctest timeout, proving the multiplier-scaling approach is structurally bounded.

This PR adopts "Option C" from the PR #1111 Round-4 diagnosis: invoke http2_client::process_frame() directly via a friend-access class, bypassing the SETTINGS handshake entirely. The seven dispatcher-only TEST_F that previously waited on peer.settings_exchanged() now construct frames via the production frame classes and inject them through the friend hook. Local execution time for these seven TEST_F dropped from a 15-second-then-fail measurement under coverage to 0 ms wall-clock per test under both Debug and Coverage builds.

Implementation

Friend hook

• src/internal/protocols/http2/http2_client.h: forward-declares kcenon::network::tests::support::http2_client_test_access and grants friend class access, both gated by #if defined(NETWORK_ENABLE_TEST_INJECTION). Production builds (where BUILD_TESTS=OFF) compile byte-identical because the macro is undefined.
• tests/support/http2_client_test_access.h: defines the friend class with three static forwarders — process_frame, goaway_received (atomic load accessor), connection_window_size (read-only field accessor).
• tests/CMakeLists.txt: no per-target macro definition; NETWORK_ENABLE_TEST_INJECTION propagates transitively from the network_system PUBLIC definition at cmake/network_system_targets.cmake:163-165. Same gate as quic_server.h:55 (probe pattern) and websocket_server.h:33. Single-sentinel codebase.

Test refactor

tests/unit/http2_client_branch_test.cpp — seven dispatcher TEST_F migrated:

1. ServerPingFrameDrivesHandlePingAndKeepsConnectionAlive — handle_ping_frame non-ACK arm
2. ServerPingAckFrameIsAbsorbedSilently — handle_ping_frame is_ack early-return arm
3. ServerGoawayFrameFlipsConnectionStateToDisconnected — handle_goaway_frame (asserts goaway_received_ flips via friend accessor)
4. ServerWindowUpdateOnConnectionStreamExpandsWindow — handle_window_update_frame connection-level branch (stream_id=0)
5. ServerWindowUpdateOnUnknownStreamIsSilentlyIgnored — handle_window_update_frame stream-not-found branch
6. ServerRstStreamOnUnknownStreamIsSilentlyIgnored — handle_rst_stream_frame lookup-miss branch
7. ProcessFrameNullPointerGuardReturnsInvalidArgument — process_frame null-pointer guard at line 622 (renamed from ServerUnknownFrameTypeIsHandledWithoutCrashing to accurately reflect what the post-refactor assertion covers; the wire-level unknown-type path is covered by MalformedServerSettingsTypeByteTriggersConnectTimeout via frame_injector)

All seven now construct frames via the production ping_frame / goaway_frame / window_update_frame / rst_stream_frame classes (matching wire-format dispatch) and call http2_client_test_access::process_frame(*client, std::move(frame)) against a freshly-constructed unconnected client.

Documentation

• CHANGELOG.md and docs/CHANGELOG.md (SSOT): record the Round 6 pivot under [Unreleased] including the 15.175 s → 0 ms wall-time collapse, the 7-of-21 dispatcher scope split, the production byte-identity guarantee, and the deferred post-merge coverage gate.

Scope clarification (issue body's "24" vs the actual 7 refactored)

The issue body referenced "24 dispatcher TEST_F"; the actual count of * NETWORK_COVERAGE_TIMEOUT_MULTIPLIER call sites in branch_test.cpp is 28, but those conflate three distinct categories:

• 7 dispatcher-only (Phase 2E.R3 batch, Server* + ProcessFrame* TEST_F): refactored here.
• 14 connect-state public-API (StartStream*, WriteStream*, CancelStream*, SecondConnect*, SendRequestTimesOut*, PostWithBody*, SetSettings*, etc.): NOT refactored — they assert client→server transmission, not just dispatch. process_frame injection cannot replace them; they remain on the multiplier scaffold from PR fix(test): apply NETWORK_COVERAGE_TIMEOUT_MULTIPLIER at explicit wait_for call sites (#1112) #1114.
• 4 early-connect parse-error (Drop*, Truncate*, Malformed*): NOT refactored — fixed 300 ms cap, never reach peer.settings_exchanged().
• 2 inside #ifndef NETWORK_COVERAGE_BUILD (SlowWrite*, EchoOneTruncate*): excluded from coverage runs by CMake; out of scope.
• 1 connect-handshake (ConnectAttemptsHandshakeAgainstLoopbackTlsPeer): passes in 0.27 s; the issue explicitly says keep on async transport.

The coverage gain comes from the seven dispatcher-only TEST_F newly hitting handle_*_frame and process_frame defensive arm counters under instrumentation.

Review

Two review rounds with the dev/reviewer fleet team, followed by a team-lead surgical correction. Six commits on the branch.

Round 1 (initial 3 commits — 8b53db80, f82e3792, 8aad4721):

• 0 Critical, 1 Major, 3 Minor, 2 Info findings.
• Major M1 — ServerUnknownFrameTypeIsHandledWithoutCrashing naming accuracy.
• Minor m1 (header comment about macro distinction), Minor m2 (Http2ClientTestAccess PascalCase struct vs quic_server_probe snake_case class naming convention), Minor m3 (commit subject length).

Round 2 (commit 1e9d8b11):

• Adopted reviewer's Round 1 Recommendation A: switched friend gate from NETWORK_HTTP2_CLIENT_FRIEND_TESTS to the existing NETWORK_ENABLE_TEST_INJECTION (PUBLIC, used by quic_server.h:55 and websocket_server.h:33). Resolves m1 trivially (single sentinel) and m2 (rename Http2ClientTestAccess → http2_client_test_access).
• M1 demoted to Minor (deferred) per max-2-rounds policy. Reviewer approved this Round 2 state and pushed it as the initial PR head.

Post-approval Round 3 (commit 2581b148):

• After PR creation, dev silently complied with the original Round 1 M1 rename: ServerUnknownFrameTypeIsHandledWithoutCrashing → ProcessFrameNullPointerGuardReturnsInvalidArgument, aligning the test name with the post-refactor assertion (null-pointer guard at http2_client.cpp:622, not wire-level unknown-type behavior). Quality-good fix that reviewer originally requested.
• Dev also pushed a separate post-approval commit (b126ff31) reverting the gate back to a NETWORK_HTTP2_CLIENT_FRIEND_TESTS PRIVATE-scoped macro — a regression of the Round 2 fix that reviewer had explicitly endorsed. Reviewer escalated to team-lead.
• Team-lead resolution (force-push, this PR head = fefcfec8): surgically dropped b126ff31 (the macro regression) while preserving 2581b148 (the M1 rename, applied as cherry-pick). The single-sentinel NETWORK_ENABLE_TEST_INJECTION state from Round 2 is restored. The PR is now equivalent to Round 2 + M1 rename + CHANGELOG.

Lead docs (commit fefcfec8):

• CHANGELOG entries (root + docs/CHANGELOG.md SSOT) added by team-lead as Task refactor: Remove version information and enhance test output #8 fallback when doc-writer remained dormant after Phase B unblock.

Approved for merge.

Test Plan

Local verification (Apple Clang, macOS Darwin 25.5.0)

The 0 ms-under-Coverage result is the load-bearing evidence: PR #1114 measured 15.175 s for ConnectCompletesSettingsExchangeWithMockPeer (test #5868) and a 300 s ctest-cap timeout for test #5869 in coverage run 25562347620. Direct process_frame injection collapses the 15 s → 0 ms — proof that the dispatcher branches are now actually executing under instrumentation.

CI matrix

This PR targets develop. Per workflow/branching-strategy.md, the full multi-platform matrix runs on PRs targeting main. The CI checks that DO run on this PR (Coverage Analysis + a subset of Ubuntu/macOS Debug/Release builds + GitGuardian + No-throw-in-public-headers) verify build correctness for the unified NETWORK_ENABLE_TEST_INJECTION gate. Full matrix verification will occur at the develop → main release PR.

Post-merge coverage gate (deferred verification)

Acceptance criterion #4 of #1115 is the post-merge coverage delta:

≥+20pp line AND ≥+10pp branch on src/protocols/http2/http2_client.cpp versus PR #1109 baseline (LH/LF=108/576 = 18.75% line, BRH/BRF=97/979 = 9.91% branch).

Cannot be verified pre-merge — the develop-branch Coverage Analysis workflow runs on push to develop, not on PR. After this PR squash-merges into develop:

1. Coverage Analysis workflow runs automatically.
2. Compare coverage_filtered.info post-merge LH/LF/BRH/BRF on http2_client.cpp against the 108/576 / 97/979 baseline.
3. If the gate is met (≥+20pp line / ≥+10pp branch), the Round-6 pivot is validated and dispatcher coverage is unblocked.
4. If not met, the right next move is to lower the gate or accept the gap with written justification (separate decision per the issue body's third Risks bullet) — Option C will have proven structurally insufficient for the line gate, in which case handle_settings_frame, handle_data_frame, handle_headers_frame (which require deeper preconditions) would need to be reachable through a different mechanism.

Conservative pre-merge estimate: 7 handlers × ~5-15 LOC each = 70-100 lines of dispatcher code newly reachable. Plausible delta: +10-18pp line, +8-15pp branch. Branch gate (≥+10pp) likely cleared; line gate (≥+20pp) at risk and may require a follow-up Round 7.

Risks

Per the issue body Risks section:

1. Wrong entry point: mitigated. process_frame has no is_connected_ precondition. Handlers that internally invoke send_frame (non-ACK PING, non-ACK SETTINGS) short-circuit via the connection_closed branch on an unconnected client — observed behavior, not UB. No setup_minimal_state_for_testing helper required.

2. Friend coupling: mitigated. Used http2_client_test_access class (single dedicated friend) per the issue body's preferred mitigation; production header is agnostic of GTest fixture class names. The friend declaration is gated by the existing NETWORK_ENABLE_TEST_INJECTION macro — the same single-sentinel pattern used by quic_server.h:55 / websocket_server.h:33. Friendship is compile-time only and adds no runtime cost; production builds (where BUILD_TESTS=OFF and the macro is undefined) compile byte-identical.

3. Coverage delta still 0pp: present and DEFERRED. See "Post-merge coverage gate" above. The wall-clock collapse from 15 s → 0 ms is strong indirect evidence that the dispatcher branches are now reachable, but the lcov/gcov measurement is the definitive proof.

Notable items deferred

• connection_window_size_ non-atomic (int32_t at http2_client.h:394): out of this PR's scope. Production code already mutates the field from the io thread without streams_mutex_ protection. The friend accessor reads it without synchronization. Safe in tests because no io thread runs on a fresh client. Future work could introduce std::atomic<int32_t> or a dedicated mutex.
• Commit subject length: per-commit subjects on the iteration branch are 70-83 chars (over the 50-char Conventional Commits guideline). Squash-merge will tighten. Suggested squash subject: test(http2-client): refactor 7 dispatcher TEST_F via friend hook (64 chars, captures both artifact and mechanism).

Rollback

git revert is sufficient. Test infrastructure plus a friend declaration in a single header gated by a test-only macro; no production-source semantics change.