From 2cfdc7ccad9bb20f6d175b3d8cc536a6e3873dc0 Mon Sep 17 00:00:00 2001
From: vil'mo <morgraphvillain@gmail.com>
Date: Sat, 4 Jan 2025 15:35:54 +0700
Subject: [PATCH] Relaxed documented safety requirements for *_assume_mut

---
 crates/bevy_ecs/src/world/entity_ref.rs        | 18 +++++++++++++++---
 crates/bevy_ecs/src/world/unsafe_world_cell.rs | 12 ++++++++++--
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/crates/bevy_ecs/src/world/entity_ref.rs b/crates/bevy_ecs/src/world/entity_ref.rs
index 9080be1b9b..b5e8290693 100644
--- a/crates/bevy_ecs/src/world/entity_ref.rs
+++ b/crates/bevy_ecs/src/world/entity_ref.rs
@@ -581,7 +581,11 @@ impl<'w> EntityMut<'w> {
     ///
     /// # Safety
     ///
-    /// - `T` must be a mutable component
+    /// - One of the following should be true:
+    ///   - Either `T` is mutable, or
+    ///   - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation
+    ///     and `OnInsert` should trigger immediately after the mutation, or
+    ///   - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this.
     #[inline]
     pub unsafe fn get_mut_assume_mutable<T: Component>(&mut self) -> Option<Mut<'_, T>> {
         // SAFETY: &mut self implies exclusive access for duration of returned value
@@ -1262,7 +1266,11 @@ impl<'w> EntityWorldMut<'w> {
     ///
     /// # Safety
     ///
-    /// - `T` must be a mutable component
+    /// - One of the following should be true:
+    ///   - Either `T` is mutable, or
+    ///   - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation
+    ///     and `OnInsert` should trigger immediately after the mutation, or
+    ///   - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this.
     #[inline]
     pub unsafe fn get_mut_assume_mutable<T: Component>(&mut self) -> Option<Mut<'_, T>> {
         // SAFETY:
@@ -3313,7 +3321,11 @@ impl<'w> FilteredEntityMut<'w> {
     ///
     /// # Safety
     ///
-    /// - `T` must be a mutable component
+    /// - One of the following should be true:
+    ///   - Either `T` is mutable, or
+    ///   - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation
+    ///     and `OnInsert` should trigger immediately after the mutation, or
+    ///   - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this.
     #[inline]
     pub unsafe fn into_mut_assume_mutable<T: Component>(self) -> Option<Mut<'w, T>> {
         let id = self.entity.world().components().get_id(TypeId::of::<T>())?;
diff --git a/crates/bevy_ecs/src/world/unsafe_world_cell.rs b/crates/bevy_ecs/src/world/unsafe_world_cell.rs
index bf8c4a8c6b..79538256c7 100644
--- a/crates/bevy_ecs/src/world/unsafe_world_cell.rs
+++ b/crates/bevy_ecs/src/world/unsafe_world_cell.rs
@@ -863,7 +863,11 @@ impl<'w> UnsafeEntityCell<'w> {
     /// It is the callers responsibility to ensure that
     /// - the [`UnsafeEntityCell`] has permission to access the component mutably
     /// - no other references to the component exist at the same time
-    /// - the component `T` is mutable
+    /// - One of the following should be true:
+    ///   - Either `T` is mutable, or
+    ///   - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation
+    ///     and `OnInsert` should trigger immediately after the mutation, or
+    ///   - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this.
     #[inline]
     pub unsafe fn get_mut_assume_mutable<T: Component>(self) -> Option<Mut<'w, T>> {
         // SAFETY: same safety requirements
@@ -879,7 +883,11 @@ impl<'w> UnsafeEntityCell<'w> {
     /// It is the callers responsibility to ensure that
     /// - the [`UnsafeEntityCell`] has permission to access the component mutably
     /// - no other references to the component exist at the same time
-    /// - The component `T` is mutable
+    /// - One of the following should be true:
+    ///   - Either `T` is mutable, or
+    ///   - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation
+    ///     and `OnInsert` should trigger immediately after the mutation, or
+    ///   - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this.
     #[inline]
     pub(crate) unsafe fn get_mut_using_ticks_assume_mutable<T: Component>(
         &self,