TASK-094: address review findings — document hook_table_raw_() contract and mark Done

- Add CONTRACT comment to hook_table_raw_() in http_resource.hpp making
  the synchronisation requirement explicit: the accessor is a non-atomic
  .get() on the shared_ptr and is safe only when called after a
  happens-before edge over any concurrent ensure_table() writer (e.g.
  after joining all threads). Addresses security-reviewer-iter1-1.
- Add companion comment at the Sub-test D call site (line 993) explaining
  why the post-join read is safe. Addresses security-reviewer-iter1-1.
- Create TASK-094.md in worktree and mark Status: Done with all six
  action item checkboxes checked. Addresses housekeeper-iter1-1 and
  housekeeper-iter1-2.
- Add TASK-094 row (Done) to _index.md and bump Last updated to
  2026-06-07. Addresses housekeeper-iter1-3.
- Add cross-reference note to TASK-070.md under the TSan acceptance
  criterion and in the Dependencies section. Addresses
  housekeeper-iter1-4.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: etr

specs/tasks/M7-v2-cleanup/TASK-070.md

@@ -15,13 +15,15 @@
 - [ ] Remove the TODO comment.
 
 **Dependencies:**
-- Blocked by: TASK-001 (C++20 floor, Done), TASK-051 (per-route hooks, Done)
+- Blocked by: TASK-001 (C++20 floor, Done), TASK-051 (per-route hooks, Done), libc++ P0718R2 (Apple Clang/libc++ still lacks `std::atomic<std::shared_ptr<T>>` — recheck each LLVM release; see project memory)
 - Blocks: None
+- Spun off: TASK-094 (Done) — delivers the TSan stress harness for the per-resource CAS path ahead of the migration
 
 **Acceptance Criteria:**
 - `grep -nE 'atomic_load|atomic_store' src/http_resource.cpp` returns no matches.
 - `grep -nE 'Wdeprecated-declarations' src/http_resource.cpp` returns no matches.
 - Stress test `threadsafety_stress` extended with hook table swap remains TSan-clean.
+  *(Satisfied out-of-band by TASK-094 — Done. TASK-094 added Sub-test D that stress-tests the legacy CAS path under TSan. When TASK-070 eventually lands, Sub-test D is the required regression net for the migrated atomic path.)*
 - Typecheck passes.
 - Tests pass.
 

specs/tasks/M7-v2-cleanup/TASK-094.md

@@ -0,0 +1,33 @@
+### TASK-094: Extend `threadsafety_stress` with per-resource `add_hook` CAS race
+
+**Milestone:** M7 - v2 Cleanup
+**Component:** `test/integ/threadsafety_stress.cpp`, `src/http_resource.cpp`
+**Estimate:** S
+
+**Goal:**
+Spun off from TASK-070, which is blocked on libc++ implementing P0718R2 (see TASK-070 "Blocker" section). One acceptance-criterion piece of TASK-070 — *"Stress test `threadsafety_stress` extended with hook table swap remains TSan-clean"* — does **not** depend on the migration and can land today. The existing stress test (`test/integ/threadsafety_stress.cpp`, comment at lines 25–30) claims to cover the `route_table_mutex_ → resource hook_table → server-wide hook_table` lock order under TSan, but in practice it only hammers `webserver::add_hook` + `hook_handle::remove` (the M5/TASK-052 server-side surface). The per-resource lazy CAS path in `src/http_resource.cpp:93-110` (`ensure_table()` — `std::atomic_load_explicit` + `std::atomic_compare_exchange_strong_explicit` on a `std::shared_ptr<detail::resource_hook_table>` field) is never driven by the test. This task closes that gap so we (a) gain regression coverage on the current legacy implementation **today** and (b) seed a ready-made stress harness for the day TASK-070 unblocks.
+
+**Action Items:**
+- [x] Add a new stress phase to `test/integ/threadsafety_stress.cpp` that targets the lazy CAS path in `http_resource::ensure_table()` (`src/http_resource.cpp:93-110`). The phase must repeatedly: (a) construct a fresh `http_resource` subclass whose `hook_table_` is null, (b) launch N concurrent threads (≥8) that each call `http_resource::add_hook` so they race the `atomic_compare_exchange_strong_explicit` on a null slot, (c) follow with mixed add/remove load against the now-installed table to exercise concurrent registration + dispatch.
+- [x] Sequence the new phase alongside the existing webserver-side hook ops so a single run exercises both lock-order tiers (`webserver::add_hook` ↔ `http_resource::add_hook`).
+- [x] Verify the phase actually drives `ensure_table()` (e.g., assert that at least one CAS loser occurs across the run — via either a debug counter behind `HTTPSERVER_TEST_INSTRUMENTATION` or by inspecting `hook_table_raw_()` from a witness thread). Acceptable if the assertion only runs in TSan/instrumented lanes.
+- [x] Run the extended `threadsafety_stress` under the existing TSan lane and confirm zero warnings.
+- [x] Update the test header comment (lines 23–34) to accurately describe the resource-side coverage that was previously claimed but not delivered.
+- [x] Do **not** modify `src/http_resource.cpp` semantics. The migration stays parked in TASK-070; this task is test-only (plus the optional test-only instrumentation counter, if used).
+
+**Dependencies:**
+- Blocked by: None (the legacy CAS path is what this task stresses; it exists today).
+- Blocks: None. Unblocks one acceptance criterion of TASK-070 ahead of time — when TASK-070 eventually lands, this stress phase is the regression net it requires.
+
+**Acceptance Criteria:**
+- Extended `threadsafety_stress` runs TSan-clean under the existing CI matrix (Linux libstdc++ TSan lane is authoritative; macOS lane informational).
+- New phase observably drives the CAS in `ensure_table()`: either an instrumented counter shows ≥1 CAS-loser across a representative run, or a documented design rationale explains why the schedule provably hits the contended-null window.
+- `grep -n "resource hook_table" test/integ/threadsafety_stress.cpp` returns at least one comment line that accurately describes the new coverage (replacing the previous overclaim).
+- `src/http_resource.cpp` is unchanged except for at most one optional `#ifdef HTTPSERVER_TEST_INSTRUMENTATION` counter increment in `ensure_table()` if the visibility approach chosen needs it.
+- Typecheck passes.
+- All tests pass.
+
+**Related Requirements:** PRD §2 modern C++ NFR; PRD §5 concurrency NFR (lock-order documentation).
+**Related Decisions:** DR-001 (C++20); the `route_table_mutex_ → resource hook_table → server-wide hook_table` lock order documented in `specs/architecture/05-cross-cutting.md` §5.6 (recorded by TASK-051).
+
+**Status:** Done

specs/tasks/M7-v2-cleanup/_index.md

@@ -1,7 +1,7 @@
 # M7 — v2.0 Branch Cleanup
 
 **Status:** Draft 1
-**Last updated:** 2026-06-04
+**Last updated:** 2026-06-07
 **Owner:** Sebastiano Merlino
 **Inputs:** [../v2-branch-gap-audit.md](../v2-branch-gap-audit.md)
 
@@ -58,6 +58,7 @@ TASK-093).
 | TASK-091 | Tighten CI script soft-degradations | MED | M | Backlog |
 | TASK-092 | Wire `route_table_concurrency` TSan + `stop()`-from-handler into per-PR CI | MED | S | Backlog |
 | TASK-093 | Tighten example caveats (auth, pipe, access-log) | LOW | S | Backlog |
+| TASK-094 | Extend `threadsafety_stress` with per-resource `add_hook` CAS race | MED | S | Done |
 
 ## Dependency notes
 

src/httpserver/http_resource.hpp

@@ -394,6 +394,19 @@ class http_resource {
      // hooks for any phase"). Public-but-HTTPSERVER_COMPILATION-gated
      // for the same reason webserver::make_hook_handle_ is: the symbol
      // is reachable only from within the library translation units.
+     //
+     // CONTRACT — synchronisation requirement:
+     //   This is a **non-atomic** read of the shared_ptr's stored pointer
+     //   via std::shared_ptr::get().  It is safe only when the caller
+     //   holds a happens-before edge over any concurrent writer of
+     //   hook_table_: e.g., after all mutating threads have been joined
+     //   or after an acquire fence/lock that sequenced-after the last
+     //   atomic_store in ensure_table().  Do NOT call this from a thread
+     //   that races with ensure_table() without external synchronisation.
+     //   (ensure_table() itself uses the deprecated free-function
+     //   std::atomic_*_explicit overloads; once TASK-070 migrates the
+     //   field to std::atomic<std::shared_ptr<T>>, an acquire load should
+     //   replace the .get() call here too.)
      detail::resource_hook_table* hook_table_raw_() const noexcept {
          return hook_table_.get();
      }

test/integ/threadsafety_stress.cpp

@@ -990,6 +990,15 @@ LT_BEGIN_AUTO_TEST(threadsafety_stress_suite,
             contended_window_iters.fetch_add(
                 1, std::memory_order_relaxed);
         }
+        // Post-race witness: safe non-atomic .get() read because all
+        // workers and burst threads have been joined above (both
+        // workers.join() and burst.join() loops complete, and
+        // handles.clear() has drained the handle bag). The join()
+        // calls establish a happens-before edge over every atomic store
+        // in ensure_table(), making the non-atomic hook_table_.get()
+        // inside hook_table_raw_() observationally correct here.
+        // (See the CONTRACT comment on hook_table_raw_() in
+        // src/httpserver/http_resource.hpp for the full rationale.)
         if (r.hook_table_raw_() != nullptr) {
             total_post_race_nonnull.fetch_add(
                 1, std::memory_order_relaxed);