From 451e5503ba0905728f9a28148af21eda81e58c8b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 27 Apr 2026 18:27:22 +0000
Subject: [PATCH] docs(web): SAFETY comment for DerivedStateActor

Document soundness of `unsafe impl Send` per audit AUD-1 (#435):
field-by-field Send rationale, single-WASM-thread invariant for
SendWrapper, and link back to spec follow-up F2.

Refs #435
---
 crates/web/src/state_bridge.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/crates/web/src/state_bridge.rs b/crates/web/src/state_bridge.rs
index bd2a598e..1ddbfd1c 100644
--- a/crates/web/src/state_bridge.rs
+++ b/crates/web/src/state_bridge.rs
@@ -84,6 +84,17 @@ impl<T: Send + Sync + 'static, U: PartialEq + Clone + Send + Sync + 'static> Han
     }
 }
 
+// SAFETY: All four fields are Send under the `T: Send + Sync` and `U: Send + Sync`
+// bounds on the impl: `StateRef<T>` and `Arc<Mutex<Option<U>>>` propagate Send from
+// their parameters, `Arc<dyn Fn(&T) -> U + Send + Sync>` is Send by its trait object
+// bound, and `SendWrapper<WriteSignal<U>>` is unconditionally Send with a runtime
+// panic on cross-thread access. The actor framework requires `Send` for spawning
+// across its mailbox, but the actor only ever runs on a single WASM thread (Leptos
+// is browser-only), so `SendWrapper`'s runtime check is never tripped. Manual impl
+// guards against future field additions silently breaking auto-derive — any new
+// `!Send` field must reaffirm or remove this assertion. Tracked alongside the
+// `cached` Mutex follow-up in
+// docs/specs/2026-04-26-state-management-model-design.md § Follow-up F2.
 unsafe impl<T: Send + Sync + 'static, U: PartialEq + Clone + Send + Sync + 'static> Send
     for DerivedStateActor<T, U>
 {