Document the AccessRuleId write contract on ICollectionRepository

src/Core/AdminConsole/Repositories/ICollectionRepository.cs

@@ -54,8 +54,20 @@ public interface ICollectionRepository : IRepository<Collection, Guid>
     /// </summary>
     Task<CollectionAdminDetails?> GetByIdWithPermissionsAsync(Guid collectionId, Guid? userId, bool includeAccessRelationships);
 
+    /// <remarks>
+    /// Ignores <see cref="Collection.AccessRuleId"/>: a new collection is always created ungoverned, whatever the
+    /// caller set on <paramref name="obj"/>. Use <see cref="SetAccessRuleAssociationsAsync"/> to associate it with an
+    /// access rule.
+    /// </remarks>
     Task CreateAsync(Collection obj, IEnumerable<CollectionAccessSelection>? groups, IEnumerable<CollectionAccessSelection>? users);
+
+    /// <remarks>
+    /// Ignores <see cref="Collection.AccessRuleId"/>, whatever the caller set on <paramref name="obj"/>, so an
+    /// ordinary collection edit can neither erase nor forge a PAM association. Use
+    /// <see cref="SetAccessRuleAssociationsAsync"/> to change it.
+    /// </remarks>
     Task ReplaceAsync(Collection obj, IEnumerable<CollectionAccessSelection>? groups, IEnumerable<CollectionAccessSelection>? users);
+
     Task DeleteUserAsync(Guid collectionId, Guid organizationUserId);
     Task UpdateUsersAsync(Guid id, IEnumerable<CollectionAccessSelection> users);
     Task<ICollection<CollectionAccessSelection>> GetManyUsersByIdAsync(Guid id);

src/Infrastructure.Dapper/AdminConsole/Repositories/CollectionRepository.cs

@@ -225,10 +225,9 @@ public async Task<ICollection<CollectionAdminDetails>> GetManySharedByOrganizati
     }
 
     /// <remarks>
-    /// Does not persist <see cref="Collection.AccessRuleId"/>. The serialization round-trip copies it onto the
-    /// wrapper and Dapper binds it, but <c>[dbo].[Collection_Create]</c> accepts <c>@AccessRuleId</c> and
-    /// deliberately ignores it, so a new collection is always created ungoverned. Use
-    /// <see cref="SetAccessRuleAssociationsAsync"/> to associate it with an access rule.
+    /// Upholds the interface's <see cref="Collection.AccessRuleId"/> contract through the stored procedure: the
+    /// serialization round-trip copies the property onto the wrapper and Dapper binds it, but
+    /// <c>[dbo].[Collection_Create]</c> accepts <c>@AccessRuleId</c> and deliberately ignores it.
     /// </remarks>
     public async Task CreateAsync(Collection obj, IEnumerable<CollectionAccessSelection>? groups, IEnumerable<CollectionAccessSelection>? users)
     {
@@ -249,10 +248,9 @@ public async Task CreateAsync(Collection obj, IEnumerable<CollectionAccessSelect
     }
 
     /// <remarks>
-    /// Does not persist <see cref="Collection.AccessRuleId"/>. Every branch below routes through
-    /// <c>[dbo].[Collection_Update]</c>, which accepts <c>@AccessRuleId</c> and deliberately ignores it, so an
-    /// ordinary collection edit can neither erase nor forge a PAM association. Use
-    /// <see cref="SetAccessRuleAssociationsAsync"/> to change it.
+    /// Upholds the interface's <see cref="Collection.AccessRuleId"/> contract through the stored procedures: every
+    /// branch below routes into <c>[dbo].[Collection_Update]</c>, which accepts <c>@AccessRuleId</c> and deliberately
+    /// ignores it.
     /// </remarks>
     public async Task ReplaceAsync(Collection obj, IEnumerable<CollectionAccessSelection>? groups, IEnumerable<CollectionAccessSelection>? users)
     {