TASK-056 validation iter1: address reviewer findings

Housekeeper:
- Mark all five TASK-056 action items complete ([x]) in v2-deferred-backlog-plan.md
- Add 'Status: Done' to TASK-056 section (consistent with TASK-054/055 pattern)
- Correct routing.md -> route-table.md filename in action item text

test-quality-reviewer (major):
- threadsafety_stress: add zero-floor guard (baseline = max(warmup_median, 1000ns))
  so the latency gate never becomes 'p99 < 0' on sub-microsecond hosts
- routing_regression_test: remove internal tier/is_prefix field assertions from
  all six collision tests; replace with observable-behaviour checks (does the
  surviving route resolve expected paths, does the failed registration leave
  no prefix terminus)

performance-reviewer (major):
- radix_tree: change insert/remove/has_terminus_at and tokenize() from
  std::string_view to const std::string& so callers holding a const std::string&
  avoid the extra copy through the string_view conversion when calling tokenize_url
- webserver_dispatch: fix misleading comment on the cache-miss copy path;
  clarify that a full copy (not move) is required because result is returned
  by value and moving captured_params out would silently empty the return value

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

specs/tasks/v2-deferred-backlog-plan.md

@@ -222,20 +222,20 @@ TASK-027 cleanup:
    collide on the cache key.
 
 **Action Items:**
-- [ ] Replace `std::unordered_map` with `std::map` (or a small
+- [x] Replace `std::unordered_map` with `std::map` (or a small
   flat_map) in the radix node child container. Benchmark the impact:
   acceptable if cache-miss path stays under 5 µs on the worst-case
   realistic tree depth.
-- [ ] Add the `is_prefix_match` guard at the call site of
+- [x] Add the `is_prefix_match` guard at the call site of
   `upsert_v2_param_route` so prefix-vs-exact terminus collisions are
   detected at registration time, not at lookup time.
-- [ ] Add a regression test
+- [x] Add a regression test
   `routing_regression_test.cpp::register_exact_after_prefix_does_not_collide`
   pinning the registration-time error.
-- [ ] Add a stress-test variant in `threadsafety_stress.cpp` that
+- [x] Add a stress-test variant in `threadsafety_stress.cpp` that
   hammers the registration path with adversarial path segments to
   confirm the new container is DoS-resistant.
-- [ ] Update `specs/architecture/04-components/routing.md` with the
+- [x] Update `specs/architecture/04-components/route-table.md` with the
   new container choice and rationale.
 
 **Dependencies:**
@@ -253,6 +253,8 @@ TASK-027 cleanup:
 **Related Findings:** task-027 #14, task-027 #18
 **Related Decisions:** §4.5 routing
 
+**Status:** Done
+
 ---
 
 ## TASK-057 — Redact credentials in `http_request::operator<<`

src/detail/webserver_dispatch.cpp

@@ -203,10 +203,17 @@ webserver_impl::lookup_v2(http_method method, const std::string& path) {
         }
     }  // table_lock released.
 
-    // Step 3: install into cache (cache mutex only). Copy result.entry
-    // and result.captured_params into the cache_value — the caller
-    // consumes `result` after this returns, so a move-out would leave
-    // the caller reading a moved-from variant / empty captures vector.
+    // Step 3: install into cache (cache mutex only). Full copy of
+    // result.entry and result.captured_params into cache_value v, then
+    // return result by value (NRVO).
+    //
+    // Why copy and not move:
+    //   - result is returned by value on the next line; moving any field
+    //     out of it here would return a partially moved-from struct to
+    //     the caller, silently losing captured_params.
+    //   - result.entry carries a shared_ptr<http_resource> variant; the
+    //     copy atomically bumps the refcount once (unavoidable regardless
+    //     of move-or-copy for the cache slot).
     // (The same defensive copy lands in TASK-053; if TASK-053 merges
     // first this hunk becomes a benign duplicate.)
     if (result.found) {

src/httpserver/detail/radix_tree.hpp

@@ -103,7 +103,7 @@ class radix_tree {
     // (webserver_impl) is responsible for keeping the is_prefix argument
     // consistent with route_entry::is_prefix, which is the §4.7 source
     // of truth. Replaces an existing terminus of the same kind.
-    void insert(std::string_view path, T entry, bool is_prefix = false) {
+    void insert(const std::string& path, T entry, bool is_prefix = false) {
         radix_node<T>* node = root_.get();
         const auto segments = tokenize(path);
         for (const std::string& seg : segments) {
@@ -225,7 +225,7 @@ class radix_tree {
     // inserting a NEW exact terminus at /admin we need to refuse if a
     // prefix terminus is already registered at /admin (and vice versa)
     // — silent shadowing would corrupt the (method, path) cache key.
-    bool has_terminus_at(std::string_view path, bool is_prefix) const {
+    bool has_terminus_at(const std::string& path, bool is_prefix) const {
         const radix_node<T>* node = root_.get();
         const auto segments = tokenize(path);
         for (const std::string& seg : segments) {
@@ -249,7 +249,7 @@ class radix_tree {
     // NOTE: unlike find(), where descent uses the concrete request-path
     // segment value (e.g. "42"), remove() receives the registered pattern
     // (e.g. "{id}") and matches wildcard nodes by the placeholder shape.
-    bool remove(std::string_view path, bool is_prefix) {
+    bool remove(const std::string& path, bool is_prefix) {
         radix_node<T>* node = root_.get();
         const auto segments = tokenize(path);
         for (const std::string& seg : segments) {
@@ -285,10 +285,10 @@ class radix_tree {
     }
 
  private:
-    static std::vector<std::string> tokenize(std::string_view path) {
-        // tokenize_url takes a std::string by value via string_split; copy
-        // the view's contents to call it.
-        return ::httpserver::http::http_utils::tokenize_url(std::string{path});
+    static std::vector<std::string> tokenize(const std::string& path) {
+        // tokenize_url takes std::string by value; pass the already-owned
+        // string to avoid an extra copy when callers hold a const string&.
+        return ::httpserver::http::http_utils::tokenize_url(path);
     }
 
     static bool is_wildcard_segment(const std::string& seg) noexcept {

test/integ/threadsafety_stress.cpp

@@ -755,7 +755,16 @@ LT_BEGIN_AUTO_TEST(threadsafety_stress_suite,
     // Gate: p99 must not exceed 10× the warmup median. With std::map
     // (O(log n) per probe), the ratio in practice is < 3×; the 10×
     // gate gives the test margin under CI noise.
-    LT_CHECK_LT(p99, warmup_median * 10);
+    //
+    // Zero-floor guard: on sub-microsecond hosts or with a coarse
+    // steady_clock quantum the OS may quantise all warmup samples to 0 ns,
+    // making warmup_median == 0 and therefore warmup_median * 10 == 0,
+    // which turns the gate into `p99 < 0` — an impossible assertion that
+    // always fails. Clamp the baseline to at least 1 µs so the gate
+    // remains a meaningful "no spike" check even on very fast hardware.
+    const int64_t baseline = std::max(warmup_median,
+                                      static_cast<int64_t>(1000));
+    LT_CHECK_LT(p99, baseline * 10);
 
     ws.stop();
 LT_END_AUTO_TEST(adversarial_segments_registration_no_latency_spike)

test/unit/routing_regression_test.cpp

@@ -369,11 +369,15 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
     }
     LT_CHECK(threw);
     // Original prefix entry must remain intact (atomicity contract).
+    // Verify via observable behaviour: /admin/anything resolves (prefix
+    // semantics) and /admin also resolves (the prefix terminates here).
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/admin/anything"));
     LT_CHECK(r.found);
-    LT_CHECK(r.tier == ht::detail::webserver_impl::tier_hit::radix);
-    LT_CHECK(r.entry.is_prefix);
+    // Bare path also resolves via prefix.
+    auto r2 = impl_of(ws).lookup_v2(
+        ht::http_method::get, std::string("/admin"));
+    LT_CHECK(r2.found);
 LT_END_AUTO_TEST(register_exact_after_prefix_does_not_collide)
 
 LT_BEGIN_AUTO_TEST(routing_regression_suite,
@@ -391,14 +395,12 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
     }
     LT_CHECK(threw);
     // Original exact entry must remain intact: the bare path still
-    // resolves through the exact tier.
+    // resolves (observable behaviour — exact match exists).
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/admin"));
     LT_CHECK(r.found);
-    LT_CHECK(r.tier == ht::detail::webserver_impl::tier_hit::exact);
-    LT_CHECK(!r.entry.is_prefix);
     // And the failed prefix registration must NOT have planted a
-    // prefix terminus — /admin/sub must miss.
+    // prefix terminus — /admin/sub must miss (exact semantics preserved).
     auto sub = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/admin/sub"));
     LT_CHECK(!sub.found);
@@ -417,10 +419,15 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
         threw = true;
     }
     LT_CHECK(threw);
+    // Original prefix entry must remain intact: /static/x resolves
+    // (prefix semantics — deeper path matches), and /static itself also
+    // resolves (the prefix terminus is anchored here).
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/static/x"));
     LT_CHECK(r.found);
-    LT_CHECK(r.entry.is_prefix);
+    auto r2 = impl_of(ws).lookup_v2(
+        ht::http_method::get, std::string("/static"));
+    LT_CHECK(r2.found);
 LT_END_AUTO_TEST(register_path_after_prefix_does_not_collide)
 
 LT_BEGIN_AUTO_TEST(routing_regression_suite,
@@ -436,10 +443,14 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
         threw = true;
     }
     LT_CHECK(threw);
+    // Original exact entry must remain intact: /static resolves, but
+    // /static/sub does NOT (exact semantics — no deeper path matches).
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/static"));
     LT_CHECK(r.found);
-    LT_CHECK(!r.entry.is_prefix);
+    auto sub = impl_of(ws).lookup_v2(
+        ht::http_method::get, std::string("/static/sub"));
+    LT_CHECK(!sub.found);
 LT_END_AUTO_TEST(register_prefix_after_path_does_not_collide)
 
 LT_BEGIN_AUTO_TEST(routing_regression_suite,
@@ -458,12 +469,16 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
         threw = true;
     }
     LT_CHECK(threw);
-    // The original prefix entry must still match a deeper path.
+    // The original prefix entry must still match a deeper path
+    // (observable behaviour: /users/42/profile resolves via prefix).
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/users/42/profile"));
     LT_CHECK(r.found);
-    LT_CHECK(r.tier == ht::detail::webserver_impl::tier_hit::radix);
-    LT_CHECK(r.entry.is_prefix);
+    // The exact node itself also resolves (prefix captures /users/42 and
+    // any extension).
+    auto r2 = impl_of(ws).lookup_v2(
+        ht::http_method::get, std::string("/users/42"));
+    LT_CHECK(r2.found);
 LT_END_AUTO_TEST(parameterized_exact_after_parameterized_prefix_does_not_collide)
 
 LT_BEGIN_AUTO_TEST(routing_regression_suite,
@@ -480,11 +495,15 @@ LT_BEGIN_AUTO_TEST(routing_regression_suite,
         threw = true;
     }
     LT_CHECK(threw);
+    // Original exact entry must remain intact: /users/42 resolves.
     auto r = impl_of(ws).lookup_v2(
         ht::http_method::get, std::string("/users/42"));
     LT_CHECK(r.found);
-    LT_CHECK(r.tier == ht::detail::webserver_impl::tier_hit::radix);
-    LT_CHECK(!r.entry.is_prefix);
+    // The failed prefix registration must NOT have planted a prefix
+    // terminus — /users/42/profile must miss (exact semantics).
+    auto sub = impl_of(ws).lookup_v2(
+        ht::http_method::get, std::string("/users/42/profile"));
+    LT_CHECK(!sub.found);
 LT_END_AUTO_TEST(parameterized_prefix_after_parameterized_exact_does_not_collide)
 
 // ---------------------------------------------------------------------