mwfj · mwfj · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ A C++17 network server and gateway built on the Reactor pattern. It uses non-blo
 - **TLS/SSL** — OpenSSL 3.x integration for downstream server TLS and upstream client TLS
 - **Upstream Proxy** — per-service connection pools with TLS, streaming response relay, retry policy, trailer handling, and header rewriting
 - **HTTP/2 Upstream** — per-upstream opt-in multiplexed H2 client (donated-lease pattern), ALPN-negotiated `auto / always / never` dispatch, two-deadline send-stall + response-timeout model, transport-drain-driven sink dispatch, GOAWAY/PING liveness, live-reloadable session settings
-- **gRPC Proxying** — inbound classifier (HTTP/2 + `application/grpc` content-type, with per-route `proxy.protocol: auto/grpc/rest` override), `grpc-timeout` quad-state parser + dedicated `ArmGrpcDeadline` enforcement, Trailers-Only synthesis for every middleware-reject / proxy-failure / deadline path (`MakeGrpcErrorResponse` + HTTP→gRPC status mapping), `te: trailers` outbound force-fold, distinct `RESULT_GRPC_DEADLINE_EXCEEDED` for circuit-breaker classification, happy-path peer-trailer `grpc-status` snapshot for observability
+- **gRPC Proxying** — inbound classifier (HTTP/2 + `application/grpc` content-type, with per-route `proxy.protocol: auto/grpc/rest` override), `grpc-timeout` quad-state parser + dedicated `ArmGrpcDeadline` enforcement, Trailers-Only synthesis for every middleware-reject / proxy-failure / deadline path, `te: trailers` outbound force-fold, distinct `RESULT_GRPC_DEADLINE_EXCEEDED` for circuit-breaker classification, trailer-status retry on `grpc-status: UNAVAILABLE` with gRFC A6 pushback support, OTel SERVER/CLIENT span split per gRPC semconv with `rpc.server.call.duration` + `rpc.client.call.duration` histograms, and a per-route gRPC-Web bridge (`proxy.grpc_web.enabled`) that translates `application/grpc-web[-text]` from HTTP/1.1 + HTTP/2 carriers into canonical gRPC
 - **Rate Limiting** — per-client / per-route token-bucket middleware with LRU eviction, `RateLimit-*` headers, dry-run mode, hot reload
 - **Circuit Breaking** — per-upstream state machines, retry budgets, dry-run mode, wait-queue drain, hot-reloadable breaker tuning
 - **OAuth 2.0 Token Validation** — JWT validation with JWKS/OIDC discovery, multi-issuer policies, outbound identity headers, and RFC 7662 introspection mode

diff --git a/docs/testing.md b/docs/testing.md
@@ -3,7 +3,7 @@
 ## Running Tests
 
 ```bash
-make test               # Build and run all suites (1694 tests across 44+ suites at HEAD)
+make test               # Build and run all suites (1901 tests across 47+ suites at HEAD)
 ./test_runner                   # Run all tests directly (after building)
 ./test_runner help              # Print every supported flag
 
@@ -95,7 +95,7 @@ make test_auth_race
 make test_auth_observability
 ```
 
-At current head, `./test_runner` reports **1694 / 1694 passing** (100 %).
+At current head, `./test_runner` reports **1901 / 1901 passing** (100 %).
 
 ## Test Suites
 

diff --git a/server/auth_claims.cc → server/auth/auth_claims.cc b/server/auth_claims.cc → server/auth/auth_claims.cc
diff --git a/server/auth_error_responses.cc → server/auth/auth_error_responses.cc b/server/auth_error_responses.cc → server/auth/auth_error_responses.cc
diff --git a/server/auth_manager.cc → server/auth/auth_manager.cc b/server/auth_manager.cc → server/auth/auth_manager.cc
diff --git a/server/auth_middleware.cc → server/auth/auth_middleware.cc b/server/auth_middleware.cc → server/auth/auth_middleware.cc
diff --git a/server/auth_policy_matcher.cc → server/auth/auth_policy_matcher.cc b/server/auth_policy_matcher.cc → server/auth/auth_policy_matcher.cc
diff --git a/server/auth_upstream_http_client.cc → server/auth/auth_upstream_http_client.cc b/server/auth_upstream_http_client.cc → server/auth/auth_upstream_http_client.cc
diff --git a/server/auth_url_util.cc → server/auth/auth_url_util.cc b/server/auth_url_util.cc → server/auth/auth_url_util.cc
diff --git a/server/introspection_cache.cc → server/auth/introspection_cache.cc b/server/introspection_cache.cc → server/auth/introspection_cache.cc
diff --git a/server/introspection_client.cc → server/auth/introspection_client.cc b/server/introspection_client.cc → server/auth/introspection_client.cc
diff --git a/server/issuer.cc → server/auth/issuer.cc b/server/issuer.cc → server/auth/issuer.cc
diff --git a/server/jwks_cache.cc → server/auth/jwks_cache.cc b/server/jwks_cache.cc → server/auth/jwks_cache.cc
diff --git a/server/jwks_fetcher.cc → server/auth/jwks_fetcher.cc b/server/jwks_fetcher.cc → server/auth/jwks_fetcher.cc
diff --git a/server/jwt_verifier.cc → server/auth/jwt_verifier.cc b/server/jwt_verifier.cc → server/auth/jwt_verifier.cc
diff --git a/server/oidc_discovery.cc → server/auth/oidc_discovery.cc b/server/oidc_discovery.cc → server/auth/oidc_discovery.cc
diff --git a/server/token_hasher.cc → server/auth/token_hasher.cc b/server/token_hasher.cc → server/auth/token_hasher.cc
diff --git a/server/circuit_breaker_host.cc → ...r/circuit_breaker/circuit_breaker_host.cc b/server/circuit_breaker_host.cc → ...r/circuit_breaker/circuit_breaker_host.cc
diff --git a/server/circuit_breaker_manager.cc → ...ircuit_breaker/circuit_breaker_manager.cc b/server/circuit_breaker_manager.cc → ...ircuit_breaker/circuit_breaker_manager.cc
diff --git a/server/circuit_breaker_slice.cc → .../circuit_breaker/circuit_breaker_slice.cc b/server/circuit_breaker_slice.cc → .../circuit_breaker/circuit_breaker_slice.cc
diff --git a/server/circuit_breaker_window.cc → ...circuit_breaker/circuit_breaker_window.cc b/server/circuit_breaker_window.cc → ...circuit_breaker/circuit_breaker_window.cc
diff --git a/server/retry_budget.cc → server/circuit_breaker/retry_budget.cc b/server/retry_budget.cc → server/circuit_breaker/retry_budget.cc
diff --git a/server/cli_parser.cc → server/cli/cli_parser.cc b/server/cli_parser.cc → server/cli/cli_parser.cc
diff --git a/server/daemonizer.cc → server/cli/daemonizer.cc b/server/daemonizer.cc → server/cli/daemonizer.cc
diff --git a/server/pid_file.cc → server/cli/pid_file.cc b/server/pid_file.cc → server/cli/pid_file.cc
diff --git a/server/signal_handler.cc → server/cli/signal_handler.cc b/server/signal_handler.cc → server/cli/signal_handler.cc
diff --git a/server/config_loader.cc → server/config/config_loader.cc b/server/config_loader.cc → server/config/config_loader.cc
diff --git a/server/grpc_status.cc → server/grpc/grpc_status.cc b/server/grpc_status.cc → server/grpc/grpc_status.cc
diff --git a/server/grpc_synthesis.cc → server/grpc/grpc_synthesis.cc b/server/grpc_synthesis.cc → server/grpc/grpc_synthesis.cc
diff --git a/server/grpc_timeout.cc → server/grpc/grpc_timeout.cc b/server/grpc_timeout.cc → server/grpc/grpc_timeout.cc
diff --git a/server/grpc_web_bridge.cc → server/grpc/grpc_web_bridge.cc b/server/grpc_web_bridge.cc → server/grpc/grpc_web_bridge.cc
diff --git a/server/body_stream.cc → server/http/body_stream.cc b/server/body_stream.cc → server/http/body_stream.cc
diff --git a/server/http2_trailer_sanitizer.cc → server/http/http2_trailer_sanitizer.cc b/server/http2_trailer_sanitizer.cc → server/http/http2_trailer_sanitizer.cc
diff --git a/server/http_connection_handler.cc → server/http/http_connection_handler.cc b/server/http_connection_handler.cc → server/http/http_connection_handler.cc
diff --git a/server/http_parser.cc → server/http/http_parser.cc b/server/http_parser.cc → server/http/http_parser.cc
diff --git a/server/http_response.cc → server/http/http_response.cc b/server/http_response.cc → server/http/http_response.cc
diff --git a/server/http_router.cc → server/http/http_router.cc b/server/http_router.cc → server/http/http_router.cc
diff --git a/server/http_server.cc → server/http/http_server.cc b/server/http_server.cc → server/http/http_server.cc
diff --git a/server/route_trie.cc → server/http/route_trie.cc b/server/route_trie.cc → server/http/route_trie.cc
diff --git a/server/http2_connection_handler.cc → server/http2/http2_connection_handler.cc b/server/http2_connection_handler.cc → server/http2/http2_connection_handler.cc
diff --git a/server/http2_session.cc → server/http2/http2_session.cc b/server/http2_session.cc → server/http2/http2_session.cc
diff --git a/server/http2_stream.cc → server/http2/http2_stream.cc b/server/http2_stream.cc → server/http2/http2_stream.cc
diff --git a/server/protocol_detector.cc → server/http2/protocol_detector.cc b/server/protocol_detector.cc → server/http2/protocol_detector.cc
diff --git a/server/logger.cc → server/log/logger.cc b/server/logger.cc → server/log/logger.cc
diff --git a/server/dns_resolver.cc → server/net/dns_resolver.cc b/server/dns_resolver.cc → server/net/dns_resolver.cc
diff --git a/server/attr_value.cc → server/observability/attr_value.cc b/server/attr_value.cc → server/observability/attr_value.cc
diff --git a/server/batch_span_processor.cc → server/observability/batch_span_processor.cc b/server/batch_span_processor.cc → server/observability/batch_span_processor.cc
diff --git a/server/composite_propagator.cc → server/observability/composite_propagator.cc b/server/composite_propagator.cc → server/observability/composite_propagator.cc
diff --git a/server/counter.cc → server/observability/counter.cc b/server/counter.cc → server/observability/counter.cc
diff --git a/server/histogram.cc → server/observability/histogram.cc b/server/histogram.cc → server/observability/histogram.cc
diff --git a/server/jaeger_propagator.cc → server/observability/jaeger_propagator.cc b/server/jaeger_propagator.cc → server/observability/jaeger_propagator.cc
diff --git a/server/meter.cc → server/observability/meter.cc b/server/meter.cc → server/observability/meter.cc
diff --git a/server/meter_provider.cc → server/observability/meter_provider.cc b/server/meter_provider.cc → server/observability/meter_provider.cc
diff --git a/server/metric_label_registry.cc → ...er/observability/metric_label_registry.cc b/server/metric_label_registry.cc → ...er/observability/metric_label_registry.cc
diff --git a/server/metric_writer_context.cc → ...er/observability/metric_writer_context.cc b/server/metric_writer_context.cc → ...er/observability/metric_writer_context.cc
diff --git a/server/metrics_catalog.cc → server/observability/metrics_catalog.cc b/server/metrics_catalog.cc → server/observability/metrics_catalog.cc
diff --git a/server/metrics_handler.cc → server/observability/metrics_handler.cc b/server/metrics_handler.cc → server/observability/metrics_handler.cc
diff --git a/server/observability_manager.cc → ...er/observability/observability_manager.cc b/server/observability_manager.cc → ...er/observability/observability_manager.cc
diff --git a/server/observability_middleware.cc → ...observability/observability_middleware.cc b/server/observability_middleware.cc → ...observability/observability_middleware.cc
diff --git a/server/otlp_http_exporter.cc → server/observability/otlp_http_exporter.cc b/server/otlp_http_exporter.cc → server/observability/otlp_http_exporter.cc
diff --git a/server/otlp_transport.cc → server/observability/otlp_transport.cc b/server/otlp_transport.cc → server/observability/otlp_transport.cc
diff --git a/server/periodic_metric_reader.cc → ...r/observability/periodic_metric_reader.cc b/server/periodic_metric_reader.cc → ...r/observability/periodic_metric_reader.cc
diff --git a/server/prometheus_exporter.cc → server/observability/prometheus_exporter.cc b/server/prometheus_exporter.cc → server/observability/prometheus_exporter.cc
diff --git a/server/propagator.cc → server/observability/propagator.cc b/server/propagator.cc → server/observability/propagator.cc
diff --git a/server/sampler.cc → server/observability/sampler.cc b/server/sampler.cc → server/observability/sampler.cc
diff --git a/server/span.cc → server/observability/span.cc b/server/span.cc → server/observability/span.cc
diff --git a/server/trace_id.cc → server/observability/trace_id.cc b/server/trace_id.cc → server/observability/trace_id.cc
diff --git a/server/trace_state.cc → server/observability/trace_state.cc b/server/trace_state.cc → server/observability/trace_state.cc
diff --git a/server/tracer.cc → server/observability/tracer.cc b/server/tracer.cc → server/observability/tracer.cc
diff --git a/server/tracer_provider.cc → server/observability/tracer_provider.cc b/server/tracer_provider.cc → server/observability/tracer_provider.cc
diff --git a/server/rate_limit_zone.cc → server/rate_limit/rate_limit_zone.cc b/server/rate_limit_zone.cc → server/rate_limit/rate_limit_zone.cc
diff --git a/server/rate_limiter.cc → server/rate_limit/rate_limiter.cc b/server/rate_limiter.cc → server/rate_limit/rate_limiter.cc
diff --git a/server/token_bucket.cc → server/rate_limit/token_bucket.cc b/server/token_bucket.cc → server/rate_limit/token_bucket.cc
diff --git a/server/tls_client_context.cc → server/tls/tls_client_context.cc b/server/tls_client_context.cc → server/tls/tls_client_context.cc
diff --git a/server/tls_connection.cc → server/tls/tls_connection.cc b/server/tls_connection.cc → server/tls/tls_connection.cc
diff --git a/server/tls_context.cc → server/tls/tls_context.cc b/server/tls_context.cc → server/tls/tls_context.cc
diff --git a/server/grpc_web_inbound_body_stream.cc → .../upstream/grpc_web_inbound_body_stream.cc b/server/grpc_web_inbound_body_stream.cc → .../upstream/grpc_web_inbound_body_stream.cc
diff --git a/server/h2_connection_table.cc → server/upstream/h2_connection_table.cc b/server/h2_connection_table.cc → server/upstream/h2_connection_table.cc
diff --git a/server/header_rewriter.cc → server/upstream/header_rewriter.cc b/server/header_rewriter.cc → server/upstream/header_rewriter.cc
diff --git a/server/http_request_serializer.cc → server/upstream/http_request_serializer.cc b/server/http_request_serializer.cc → server/upstream/http_request_serializer.cc
diff --git a/server/pool_partition.cc → server/upstream/pool_partition.cc b/server/pool_partition.cc → server/upstream/pool_partition.cc
diff --git a/server/proxy_handler.cc → server/upstream/proxy_handler.cc b/server/proxy_handler.cc → server/upstream/proxy_handler.cc
diff --git a/server/proxy_transaction.cc → server/upstream/proxy_transaction.cc b/server/proxy_transaction.cc → server/upstream/proxy_transaction.cc
diff --git a/server/retry_policy.cc → server/upstream/retry_policy.cc b/server/retry_policy.cc → server/upstream/retry_policy.cc
diff --git a/server/upstream_connection.cc → server/upstream/upstream_connection.cc b/server/upstream_connection.cc → server/upstream/upstream_connection.cc
diff --git a/server/upstream_h2_codec.cc → server/upstream/upstream_h2_codec.cc b/server/upstream_h2_codec.cc → server/upstream/upstream_h2_codec.cc
diff --git a/server/upstream_h2_connection.cc → server/upstream/upstream_h2_connection.cc b/server/upstream_h2_connection.cc → server/upstream/upstream_h2_connection.cc
diff --git a/server/upstream_host_pool.cc → server/upstream/upstream_host_pool.cc b/server/upstream_host_pool.cc → server/upstream/upstream_host_pool.cc
diff --git a/server/upstream_http_codec.cc → server/upstream/upstream_http_codec.cc b/server/upstream_http_codec.cc → server/upstream/upstream_http_codec.cc
diff --git a/server/upstream_manager.cc → server/upstream/upstream_manager.cc b/server/upstream_manager.cc → server/upstream/upstream_manager.cc
diff --git a/server/websocket_connection.cc → server/ws/websocket_connection.cc b/server/websocket_connection.cc → server/ws/websocket_connection.cc
diff --git a/server/websocket_frame.cc → server/ws/websocket_frame.cc b/server/websocket_frame.cc → server/ws/websocket_frame.cc
diff --git a/server/websocket_handshake.cc → server/ws/websocket_handshake.cc b/server/websocket_handshake.cc → server/ws/websocket_handshake.cc
diff --git a/server/websocket_parser.cc → server/ws/websocket_parser.cc b/server/websocket_parser.cc → server/ws/websocket_parser.cc
diff --git a/test/auth_failure_mode_test.h → test/auth/auth_failure_mode_test.h b/test/auth_failure_mode_test.h → test/auth/auth_failure_mode_test.h
diff --git a/test/auth_foundation_test.h → test/auth/auth_foundation_test.h b/test/auth_foundation_test.h → test/auth/auth_foundation_test.h
diff --git a/test/auth_integration_test.h → test/auth/auth_integration_test.h b/test/auth_integration_test.h → test/auth/auth_integration_test.h
diff --git a/test/auth_introspection_integration_test.h → ...uth/auth_introspection_integration_test.h b/test/auth_introspection_integration_test.h → ...uth/auth_introspection_integration_test.h
diff --git a/test/auth_manager_test.h → test/auth/auth_manager_test.h b/test/auth_manager_test.h → test/auth/auth_manager_test.h
diff --git a/test/auth_multi_issuer_test.h → test/auth/auth_multi_issuer_test.h b/test/auth_multi_issuer_test.h → test/auth/auth_multi_issuer_test.h
diff --git a/test/auth_observability_test.h → test/auth/auth_observability_test.h b/test/auth_observability_test.h → test/auth/auth_observability_test.h
diff --git a/test/auth_race_test.h → test/auth/auth_race_test.h b/test/auth_race_test.h → test/auth/auth_race_test.h
diff --git a/test/auth_reload_test.h → test/auth/auth_reload_test.h b/test/auth_reload_test.h → test/auth/auth_reload_test.h
diff --git a/test/auth_websocket_upgrade_test.h → test/auth/auth_websocket_upgrade_test.h b/test/auth_websocket_upgrade_test.h → test/auth/auth_websocket_upgrade_test.h
diff --git a/test/header_rewriter_auth_test.h → test/auth/header_rewriter_auth_test.h b/test/header_rewriter_auth_test.h → test/auth/header_rewriter_auth_test.h
diff --git a/test/introspection_cache_test.h → test/auth/introspection_cache_test.h b/test/introspection_cache_test.h → test/auth/introspection_cache_test.h
diff --git a/test/introspection_client_test.h → test/auth/introspection_client_test.h b/test/introspection_client_test.h → test/auth/introspection_client_test.h
diff --git a/test/jwks_cache_test.h → test/auth/jwks_cache_test.h b/test/jwks_cache_test.h → test/auth/jwks_cache_test.h
diff --git a/test/jwt_verifier_test.h → test/auth/jwt_verifier_test.h b/test/jwt_verifier_test.h → test/auth/jwt_verifier_test.h
diff --git a/test/oidc_discovery_test.h → test/auth/oidc_discovery_test.h b/test/oidc_discovery_test.h → test/auth/oidc_discovery_test.h
diff --git a/test/circuit_breaker_components_test.h → ...breaker/circuit_breaker_components_test.h b/test/circuit_breaker_components_test.h → ...breaker/circuit_breaker_components_test.h
diff --git a/test/circuit_breaker_integration_test.h → ...reaker/circuit_breaker_integration_test.h b/test/circuit_breaker_integration_test.h → ...reaker/circuit_breaker_integration_test.h
diff --git a/test/circuit_breaker_observability_test.h → ...aker/circuit_breaker_observability_test.h b/test/circuit_breaker_observability_test.h → ...aker/circuit_breaker_observability_test.h
diff --git a/test/circuit_breaker_reload_test.h → ...uit_breaker/circuit_breaker_reload_test.h b/test/circuit_breaker_reload_test.h → ...uit_breaker/circuit_breaker_reload_test.h
diff --git a/test/circuit_breaker_retry_budget_test.h → ...eaker/circuit_breaker_retry_budget_test.h b/test/circuit_breaker_retry_budget_test.h → ...eaker/circuit_breaker_retry_budget_test.h
diff --git a/test/circuit_breaker_test.h → test/circuit_breaker/circuit_breaker_test.h b/test/circuit_breaker_test.h → test/circuit_breaker/circuit_breaker_test.h
diff --git a/test/circuit_breaker_wait_queue_drain_test.h → ...r/circuit_breaker_wait_queue_drain_test.h b/test/circuit_breaker_wait_queue_drain_test.h → ...r/circuit_breaker_wait_queue_drain_test.h
diff --git a/test/cli_test.h → test/cli/cli_test.h b/test/cli_test.h → test/cli/cli_test.h
diff --git a/test/config_test.h → test/config/config_test.h b/test/config_test.h → test/config/config_test.h
diff --git a/test/grpc_obs_test.h → test/grpc/grpc_obs_test.h b/test/grpc_obs_test.h → test/grpc/grpc_obs_test.h
@@ -73,7 +73,7 @@
 #include "observability/sampler.h"
 #include "observability/trace_id.h"
 
-#include "h2_trailer_test.h"  // TrailerAwareHttp2Client + FindTrailer
+#include "http2/h2_trailer_test.h"  // TrailerAwareHttp2Client + FindTrailer
 
 #include <atomic>
 #include <chrono>

diff --git a/test/grpc_proxy_test.h → test/grpc/grpc_proxy_test.h b/test/grpc_proxy_test.h → test/grpc/grpc_proxy_test.h
@@ -44,7 +44,7 @@
 #include "observability/sampler.h"
 #include "observability/trace_id.h"  // RandomSource
 
-#include "h2_trailer_test.h"  // reuse TrailerAwareHttp2Client + FindTrailer
+#include "http2/h2_trailer_test.h"  // reuse TrailerAwareHttp2Client + FindTrailer
 #include "grpc/grpc_web_bridge.h"  // BuildTrailerFrame for GW1 expected-bytes
 #include "base64.h"                 // UTIL_NAMESPACE::EncodeNoNewline for GW2
 #include "http_test_client.h"       // SendHttpRequest, HasStatus, ExtractBody

diff --git a/test/grpc_test.h → test/grpc/grpc_test.h b/test/grpc_test.h → test/grpc/grpc_test.h
diff --git a/test/grpc_web_edge_test.h → test/grpc/grpc_web_edge_test.h b/test/grpc_web_edge_test.h → test/grpc/grpc_web_edge_test.h
@@ -78,7 +78,7 @@
 #include "upstream/grpc_web_inbound_body_stream.h"
 #include "base64.h"
 
-#include "h2_trailer_test.h"   // TrailerAwareHttp2Client, FindTrailer
+#include "http2/h2_trailer_test.h"   // TrailerAwareHttp2Client, FindTrailer
 
 #include <atomic>
 #include <chrono>

diff --git a/test/grpc_web_test.h → test/grpc/grpc_web_test.h b/test/grpc_web_test.h → test/grpc/grpc_web_test.h
diff --git a/test/http_internal_test.h → test/http/http_internal_test.h b/test/http_internal_test.h → test/http/http_internal_test.h
diff --git a/test/http_test.h → test/http/http_test.h b/test/http_test.h → test/http/http_test.h
diff --git a/test/route_test.h → test/http/route_test.h b/test/route_test.h → test/http/route_test.h
diff --git a/test/router_async_middleware_test.h → test/http/router_async_middleware_test.h b/test/router_async_middleware_test.h → test/http/router_async_middleware_test.h
@@ -25,7 +25,7 @@
 #include <unistd.h>
 
 // Pull in the H2 test client (declared in http2_test.h).
-#include "http2_test.h"
+#include "http2/http2_test.h"
 
 namespace RouterAsyncMiddlewareTests {
 

diff --git a/test/streaming_request_test.h → test/http/streaming_request_test.h b/test/streaming_request_test.h → test/http/streaming_request_test.h
diff --git a/test/timeout_test.h → test/http/timeout_test.h b/test/timeout_test.h → test/http/timeout_test.h
diff --git a/test/h2_trailer_test.h → test/http2/h2_trailer_test.h b/test/h2_trailer_test.h → test/http2/h2_trailer_test.h
diff --git a/test/http2_internal_test.h → test/http2/http2_internal_test.h b/test/http2_internal_test.h → test/http2/http2_internal_test.h
diff --git a/test/http2_test.h → test/http2/http2_test.h b/test/http2_test.h → test/http2/http2_test.h
diff --git a/test/dns_resolver_test.h → test/net/dns_resolver_test.h b/test/dns_resolver_test.h → test/net/dns_resolver_test.h
diff --git a/test/dual_stack_test.h → test/net/dual_stack_test.h b/test/dual_stack_test.h → test/net/dual_stack_test.h
diff --git a/test/observability_auth_trace_test.h → ...rvability/observability_auth_trace_test.h b/test/observability_auth_trace_test.h → ...rvability/observability_auth_trace_test.h
diff --git a/test/observability_catalog_test.h → ...bservability/observability_catalog_test.h b/test/observability_catalog_test.h → ...bservability/observability_catalog_test.h
diff --git a/test/observability_config_test.h → ...observability/observability_config_test.h b/test/observability_config_test.h → ...observability/observability_config_test.h
diff --git a/test/observability_connection_metrics_test.h → ...y/observability_connection_metrics_test.h b/test/observability_connection_metrics_test.h → ...y/observability_connection_metrics_test.h
diff --git a/test/observability_e2e_test.h → test/observability/observability_e2e_test.h b/test/observability_e2e_test.h → test/observability/observability_e2e_test.h
diff --git a/test/observability_export_pipeline_test.h → ...lity/observability_export_pipeline_test.h b/test/observability_export_pipeline_test.h → ...lity/observability_export_pipeline_test.h
diff --git a/test/observability_foundation_test.h → ...rvability/observability_foundation_test.h b/test/observability_foundation_test.h → ...rvability/observability_foundation_test.h
diff --git a/test/observability_issue_inject_test.h → ...ability/observability_issue_inject_test.h b/test/observability_issue_inject_test.h → ...ability/observability_issue_inject_test.h
@@ -14,7 +14,7 @@
 #include "observability/trace_id.h"
 #include "observability/tracer.h"
 #include "observability/tracer_provider.h"
-#include "observability_test_helpers.h"
+#include "observability/observability_test_helpers.h"
 
 #include <cstdint>
 #include <string>

diff --git a/test/observability_jaeger_propagator_test.h → ...ty/observability_jaeger_propagator_test.h b/test/observability_jaeger_propagator_test.h → ...ty/observability_jaeger_propagator_test.h
diff --git a/test/observability_kill_marshal_test.h → ...ability/observability_kill_marshal_test.h b/test/observability_kill_marshal_test.h → ...ability/observability_kill_marshal_test.h
diff --git a/test/observability_link_kill_test.h → ...ervability/observability_link_kill_test.h b/test/observability_link_kill_test.h → ...ervability/observability_link_kill_test.h
@@ -14,8 +14,8 @@
 #include "test_framework.h"
 #include "observability/observability_manager.h"
 #include "observability/observability_snapshot.h"
-#include "observability_test_helpers.h"
-#include "proxy_transaction_internal_test.h"
+#include "observability/observability_test_helpers.h"
+#include "upstream/proxy_transaction_internal_test.h"
 
 #include <atomic>
 #include <chrono>
@@ -53,7 +53,7 @@ class FakeTxLink final : public UpstreamTransactionLink {
 
 // ---- ProxyTransaction implements the interface correctly ----
 
-void TestProxyTxIsLink() {
+inline void TestProxyTxIsLink() {
     try {
         HttpRequest req;
         auto tx = ProxyTransactionInternalTests::MakeInternalProxyTransaction(req);
@@ -75,7 +75,7 @@ void TestProxyTxIsLink() {
 
 // ---- Linked snapshot kill flow: KillOutstandingSnapshots fires the kill ----
 
-void TestKillFlipsLinkedTransaction() {
+inline void TestKillFlipsLinkedTransaction() {
     try {
         auto m = MakeManager();
         auto snap = std::make_shared<ObservabilitySnapshot>();
@@ -108,7 +108,7 @@ void TestKillFlipsLinkedTransaction() {
 
 // ---- Empty link slot — kill loop must not crash on weak.lock() == null ----
 
-void TestKillTolerantOfMissingLink() {
+inline void TestKillTolerantOfMissingLink() {
     try {
         auto m = MakeManager();
         auto snap = std::make_shared<ObservabilitySnapshot>();
@@ -135,7 +135,7 @@ void TestKillTolerantOfMissingLink() {
 // finalized state under link_mtx and immediately mark the link
 // killed-for-shutdown so the caller's terminal gates short-circuit.
 
-void TestAttachAfterKillFlipsLinkImmediately() {
+inline void TestAttachAfterKillFlipsLinkImmediately() {
     try {
         auto m = MakeManager();
         auto snap = std::make_shared<ObservabilitySnapshot>();
@@ -192,7 +192,7 @@ void TestAttachAfterKillFlipsLinkImmediately() {
 // false, and leave the link's kill flag untouched. The kill loop
 // (or any future finalizer) is still in charge of marking the link.
 
-void TestAttachBeforeKillIsBenign() {
+inline void TestAttachBeforeKillIsBenign() {
     try {
         auto m = MakeManager();
         auto snap = std::make_shared<ObservabilitySnapshot>();
@@ -233,7 +233,7 @@ void TestAttachBeforeKillIsBenign() {
 // reach `serialized_request_ = HttpRequestSerializer::Serialize(...)`
 // and produce a non-empty wire image — the assertion catches that.
 
-void TestStartShortCircuitsOnFinalizedSnapshot() {
+inline void TestStartShortCircuitsOnFinalizedSnapshot() {
     try {
         auto m = MakeManager();
         auto snap = std::make_shared<ObservabilitySnapshot>();
@@ -266,7 +266,7 @@ void TestStartShortCircuitsOnFinalizedSnapshot() {
 
 // ---- AttachObservabilitySnapshot stores the snapshot for the link site ----
 
-void TestAttachSnapshotStoresHandle() {
+inline void TestAttachSnapshotStoresHandle() {
     try {
         HttpRequest req;
         auto tx = ProxyTransactionInternalTests::MakeInternalProxyTransaction(req);

diff --git a/test/observability_manager_test.h → ...bservability/observability_manager_test.h b/test/observability_manager_test.h → ...bservability/observability_manager_test.h
diff --git a/test/observability_metrics_test.h → ...bservability/observability_metrics_test.h b/test/observability_metrics_test.h → ...bservability/observability_metrics_test.h
diff --git a/test/observability_middleware_metrics_test.h → ...y/observability_middleware_metrics_test.h b/test/observability_middleware_metrics_test.h → ...y/observability_middleware_metrics_test.h
diff --git a/test/observability_pool_gauges_test.h → ...vability/observability_pool_gauges_test.h b/test/observability_pool_gauges_test.h → ...vability/observability_pool_gauges_test.h
diff --git a/test/observability_prometheus_test.h → ...rvability/observability_prometheus_test.h b/test/observability_prometheus_test.h → ...rvability/observability_prometheus_test.h
diff --git a/test/observability_propagator_test.h → ...rvability/observability_propagator_test.h b/test/observability_propagator_test.h → ...rvability/observability_propagator_test.h
diff --git a/test/observability_proxy_client_test.h → ...ability/observability_proxy_client_test.h b/test/observability_proxy_client_test.h → ...ability/observability_proxy_client_test.h
diff --git a/test/observability_self_handler_test.h → ...ability/observability_self_handler_test.h b/test/observability_self_handler_test.h → ...ability/observability_self_handler_test.h
diff --git a/test/observability_self_metrics_test.h → ...ability/observability_self_metrics_test.h b/test/observability_self_metrics_test.h → ...ability/observability_self_metrics_test.h
diff --git a/test/observability_shutdown_test.h → ...servability/observability_shutdown_test.h b/test/observability_shutdown_test.h → ...servability/observability_shutdown_test.h
@@ -8,7 +8,7 @@
 #include "test_framework.h"
 #include "observability/observability_manager.h"
 #include "observability/observability_snapshot.h"
-#include "observability_test_helpers.h"
+#include "observability/observability_test_helpers.h"
 
 #include <chrono>
 #include <memory>

diff --git a/test/observability_stress_test.h → ...observability/observability_stress_test.h b/test/observability_stress_test.h → ...observability/observability_stress_test.h
@@ -13,7 +13,7 @@
 #include "observability/observability_manager.h"
 #include "observability/observability_snapshot.h"
 #include "observability/resource.h"
-#include "observability_test_helpers.h"
+#include "observability/observability_test_helpers.h"
 
 #include <atomic>
 #include <chrono>

diff --git a/test/observability_test_helpers.h → ...bservability/observability_test_helpers.h b/test/observability_test_helpers.h → ...bservability/observability_test_helpers.h
diff --git a/test/observability_tracer_test.h → ...observability/observability_tracer_test.h b/test/observability_tracer_test.h → ...observability/observability_tracer_test.h
diff --git a/test/observability_ws_messages_test.h → ...vability/observability_ws_messages_test.h b/test/observability_ws_messages_test.h → ...vability/observability_ws_messages_test.h
diff --git a/test/rate_limit_test.h → test/rate_limit/rate_limit_test.h b/test/rate_limit_test.h → test/rate_limit/rate_limit_test.h
diff --git a/test/run_test.cc b/test/run_test.cc
@@ -1,81 +1,125 @@
-#include "proxy_transaction_internal_test.h"
-#include "http_internal_test.h"
-#include "http2_internal_test.h"
-#include "stress_test.h"
+// Internal tests use `#define private public` to access private members of
+// production classes. They MUST be included before any other header pulls in
+// those production classes with default access (the production headers'
+// #pragma once guard would otherwise prevent a second include with the macro
+// in effect). Within this group, proxy_transaction_internal_test.h goes FIRST
+// because its `#define private public` block also covers ConnectionHandler /
+// SocketHandler / UpstreamConnection — superset of the other internal tests'
+// reach.
+#include "upstream/proxy_transaction_internal_test.h"
+#include "http/http_internal_test.h"
+#include "http2/http2_internal_test.h"
+#include "observability/observability_link_kill_test.h"
+
+// Test suite headers — grouped by feature subfolder (mirroring include/),
+// alphabetical within each group. Root-level cross-cutting tests + the shared
+// test_framework header follow at the end. Subfolder names are lowercase to
+// match include/'s convention; namespace identifiers (e.g. HTTP_NAMESPACE)
+// remain UPPER_SNAKE_CASE per CODE_CONVENTIONS.md but folder paths do not.
+
+// auth/
+#include "auth/auth_failure_mode_test.h"
+#include "auth/auth_foundation_test.h"
+#include "auth/auth_integration_test.h"
+#include "auth/auth_introspection_integration_test.h"
+#include "auth/auth_manager_test.h"
+#include "auth/auth_multi_issuer_test.h"
+#include "auth/auth_observability_test.h"
+#include "auth/auth_race_test.h"
+#include "auth/auth_reload_test.h"
+#include "auth/auth_websocket_upgrade_test.h"
+#include "auth/header_rewriter_auth_test.h"
+#include "auth/introspection_cache_test.h"
+#include "auth/introspection_client_test.h"
+#include "auth/jwks_cache_test.h"
+#include "auth/jwt_verifier_test.h"
+#include "auth/oidc_discovery_test.h"
+
+// circuit_breaker/
+#include "circuit_breaker/circuit_breaker_components_test.h"
+#include "circuit_breaker/circuit_breaker_integration_test.h"
+#include "circuit_breaker/circuit_breaker_observability_test.h"
+#include "circuit_breaker/circuit_breaker_reload_test.h"
+#include "circuit_breaker/circuit_breaker_retry_budget_test.h"
+#include "circuit_breaker/circuit_breaker_test.h"
+#include "circuit_breaker/circuit_breaker_wait_queue_drain_test.h"
+
+// cli/
+#include "cli/cli_test.h"
+
+// config/
+#include "config/config_test.h"
+
+// grpc/
+#include "grpc/grpc_obs_test.h"
+#include "grpc/grpc_proxy_test.h"
+#include "grpc/grpc_test.h"
+#include "grpc/grpc_web_edge_test.h"
+#include "grpc/grpc_web_test.h"
+
+// http/ (http_internal_test.h included above in the internal-tests group)
+#include "http/http_test.h"
+#include "http/route_test.h"
+#include "http/router_async_middleware_test.h"
+#include "http/streaming_request_test.h"
+#include "http/timeout_test.h"
+
+// http2/ (http2_internal_test.h included above in the internal-tests group)
+#include "http2/h2_trailer_test.h"
+#include "http2/http2_test.h"
+
+// net/
+#include "net/dns_resolver_test.h"
+#include "net/dual_stack_test.h"
+
+// observability/
+#include "observability/observability_auth_trace_test.h"
+#include "observability/observability_catalog_test.h"
+#include "observability/observability_config_test.h"
+#include "observability/observability_connection_metrics_test.h"
+#include "observability/observability_e2e_test.h"
+#include "observability/observability_export_pipeline_test.h"
+#include "observability/observability_foundation_test.h"
+#include "observability/observability_issue_inject_test.h"
+#include "observability/observability_jaeger_propagator_test.h"
+#include "observability/observability_kill_marshal_test.h"
+// observability_link_kill_test.h included above in the internal-tests group
+#include "observability/observability_manager_test.h"
+#include "observability/observability_metrics_test.h"
+#include "observability/observability_middleware_metrics_test.h"
+#include "observability/observability_pool_gauges_test.h"
+#include "observability/observability_prometheus_test.h"
+#include "observability/observability_propagator_test.h"
+#include "observability/observability_proxy_client_test.h"
+#include "observability/observability_self_handler_test.h"
+#include "observability/observability_self_metrics_test.h"
+#include "observability/observability_shutdown_test.h"
+#include "observability/observability_stress_test.h"
+#include "observability/observability_tracer_test.h"
+#include "observability/observability_ws_messages_test.h"
+
+// rate_limit/
+#include "rate_limit/rate_limit_test.h"
+
+// tls/
+#include "tls/tls_test.h"
+
+// upstream/ (proxy_transaction_internal_test.h included above in the internal-tests group)
+#include "upstream/h2_upstream_test.h"
+#include "upstream/proxy_test.h"
+#include "upstream/upstream_pool_test.h"
+
+// ws/
+#include "ws/websocket_test.h"
+
+// test/ (root — cross-cutting infrastructure + shared framework)
 #include "basic_test.h"
-#include "race_condition_test.h"
-#include "timeout_test.h"
-#include "config_test.h"
-#include "http_test.h"
-#include "websocket_test.h"
-#include "tls_test.h"
-#include "cli_test.h"
-#include "http2_test.h"
-#include "route_test.h"
 #include "kqueue_test.h"
-#include "upstream_pool_test.h"
-#include "proxy_test.h"
-#include "rate_limit_test.h"
-#include "circuit_breaker_test.h"
-#include "circuit_breaker_components_test.h"
-#include "circuit_breaker_integration_test.h"
-#include "circuit_breaker_retry_budget_test.h"
-#include "circuit_breaker_wait_queue_drain_test.h"
-#include "circuit_breaker_observability_test.h"
-#include "circuit_breaker_reload_test.h"
-#include "auth_foundation_test.h"
-#include "jwt_verifier_test.h"
-#include "jwks_cache_test.h"
-#include "oidc_discovery_test.h"
-#include "header_rewriter_auth_test.h"
-#include "auth_manager_test.h"
-#include "auth_integration_test.h"
-#include "auth_failure_mode_test.h"
-#include "auth_reload_test.h"
-#include "auth_multi_issuer_test.h"
-#include "auth_websocket_upgrade_test.h"
-#include "auth_race_test.h"
-#include "dns_resolver_test.h"
-#include "dual_stack_test.h"
-#include "h2_upstream_test.h"
-#include "router_async_middleware_test.h"
-#include "introspection_cache_test.h"
+#include "race_condition_test.h"
 #include "sharded_lru_cache_test.h"
-#include "introspection_client_test.h"
-#include "auth_introspection_integration_test.h"
-#include "auth_observability_test.h"
-#include "observability_foundation_test.h"
-#include "observability_tracer_test.h"
-#include "observability_metrics_test.h"
-#include "observability_manager_test.h"
-#include "observability_propagator_test.h"
-#include "observability_jaeger_propagator_test.h"
-#include "observability_export_pipeline_test.h"
-#include "observability_prometheus_test.h"
-#include "observability_config_test.h"
-#include "observability_shutdown_test.h"
-#include "observability_link_kill_test.h"
-#include "observability_issue_inject_test.h"
-#include "observability_stress_test.h"
-#include "observability_e2e_test.h"
-#include "observability_self_handler_test.h"
-#include "observability_proxy_client_test.h"
-#include "observability_auth_trace_test.h"
-#include "observability_catalog_test.h"
-#include "observability_middleware_metrics_test.h"
-#include "observability_kill_marshal_test.h"
-#include "observability_ws_messages_test.h"
-#include "observability_self_metrics_test.h"
-#include "observability_connection_metrics_test.h"
-#include "observability_pool_gauges_test.h"
-#include "streaming_request_test.h"
-#include "h2_trailer_test.h"
-#include "grpc_test.h"
-#include "grpc_proxy_test.h"
-#include "grpc_obs_test.h"
-#include "grpc_web_test.h"
-#include "grpc_web_edge_test.h"
+#include "stress_test.h"
 #include "test_framework.h"
+
 #include <algorithm>
 #include <sys/resource.h>
 

diff --git a/test/tls_test.h → test/tls/tls_test.h b/test/tls_test.h → test/tls/tls_test.h
diff --git a/test/h2_upstream_test.h → test/upstream/h2_upstream_test.h b/test/h2_upstream_test.h → test/upstream/h2_upstream_test.h
@@ -5622,7 +5622,7 @@ void TestN9pH2ResponseTimeoutClosureHonorsShutdownKill() {
     // the lighter regression-prevention check.
     bool pass = false;
     try {
-        std::ifstream in("server/proxy_transaction.cc");
+        std::ifstream in("server/upstream/proxy_transaction.cc");
         std::string src((std::istreambuf_iterator<char>(in)),
                          std::istreambuf_iterator<char>());
         // Locate the H2 response-timeout closure (uniquely identified

diff --git a/test/proxy_test.h → test/upstream/proxy_test.h b/test/proxy_test.h → test/upstream/proxy_test.h
diff --git a/test/proxy_transaction_internal_test.h → ...pstream/proxy_transaction_internal_test.h b/test/proxy_transaction_internal_test.h → ...pstream/proxy_transaction_internal_test.h
diff --git a/test/upstream_pool_test.h → test/upstream/upstream_pool_test.h b/test/upstream_pool_test.h → test/upstream/upstream_pool_test.h
diff --git a/test/websocket_test.h → test/ws/websocket_test.h b/test/websocket_test.h → test/ws/websocket_test.h