improve stable hash detection

Author: lofcz

README.md

@@ -270,6 +270,26 @@ public struct MyHandle
 
 This is the default behavior for system types like `System.Net.Http.Headers.HeaderDescriptor` to prevent breaking internal framework logic. Use this attribute if your custom structs behave similarly.
 
+### Stable Hash Opt-in
+
+Hash-based collections (`HashSet<T>`, `Dictionary<TKey, TValue>`, …) are cloned via a fast memberwise path whenever the key/element type's `GetHashCode` is known to be value-based. FastCloner figures this out automatically (and falls back to rebuilding the collection for identity-based hashes), but it can also be told explicitly with `[FastClonerStableHash]`:
+
+```csharp
+[FastClonerStableHash]
+public sealed class CompositeKey
+{
+    public int Major { get; }
+    public int Minor { get; }
+    public override int GetHashCode() => HashCode.Combine(Major, Minor);
+    public override bool Equals(object? obj)
+        => obj is CompositeKey other && other.Major == Major && other.Minor == Minor;
+}
+```
+
+Use it when `GetHashCode` is a pure function of the type's fields (or returns a constant). The attribute skips the runtime probe entirely, which is useful for types the probe cannot construct (abstract bases, types whose default-state `GetHashCode` would throw, etc.) and as a way to lock in the fast path explicitly.
+
+> **Do not** apply this attribute if `GetHashCode` depends on object identity (e.g. `RuntimeHelpers.GetHashCode(this)`, or hashes a per-instance handle that isn't preserved through cloning) — the cloned collection will be unable to find its own contents.
+
 ### Identity Preservation
 
 By default, FastCloner prioritizes performance by not tracking object identity during cloning. This means if the same object instance appears multiple times in your graph, each reference becomes a separate clone.

src/FastCloner.Benchmark/FastCloner.Benchmark.csproj

@@ -10,7 +10,7 @@
 
     <ItemGroup>
       <PackageReference Include="AnyClone" Version="1.1.6" />
-      <PackageReference Include="AutoMapper" Version="16.1.0" />
+      <PackageReference Include="AutoMapper" Version="16.1.1" />
       <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
       <PackageReference Include="DeepCloner" Version="0.10.4" />
       <PackageReference Include="DeepCopier" Version="1.0.4" />

src/FastCloner.Tests/FailureHypothesisTests.cs

@@ -1,12 +1,134 @@
 using System.Collections.Concurrent;
 using System.Reflection;
+using System.Runtime.CompilerServices;
 using System.Threading.Channels;
 using System.Threading.Tasks.Dataflow;
 using System.Threading.Tasks;
 
 namespace FastCloner.Tests;
 public class FailureHypothesisTests
 {
+    /// <summary>
+    /// Demonstrates a weakness: <see cref="FastClonerSafeTypes"/> assumes any class that overrides
+    /// <c>GetHashCode</c> has value-based hashing (<c>HasStableHashSemantics == true</c>). This drives
+    /// hash-based collections through a memberwise (raw field) clone path that copies the internal
+    /// <c>_slots</c>/<c>_buckets</c> arrays verbatim. When the override actually returns an identity-based
+    /// hash (e.g. <c>RuntimeHelpers.GetHashCode(this)</c>), the cloned bucket entries store the *original*
+    /// object's identity hash, but the elements inside are themselves deep-cloned and therefore have a
+    /// brand-new identity hash. The cloned set/dictionary is structurally corrupt: lookups by the
+    /// cloned key miss, even though the key is the very element stored in the clone.
+    /// </summary>
+    private sealed class IdentityHashedKey
+    {
+        public string Tag { get; set; } = "";
+        public override int GetHashCode() => RuntimeHelpers.GetHashCode(this);
+        public override bool Equals(object? obj) => ReferenceEquals(this, obj);
+    }
+
+    [Test]
+    public async Task HashSet_With_IdentityBased_OverriddenGetHashCode_Should_Be_Lookupable_After_Clone()
+    {
+        IdentityHashedKey item = new IdentityHashedKey { Tag = "a" };
+        HashSet<IdentityHashedKey> original = [item];
+
+        HashSet<IdentityHashedKey> clone = original.DeepClone();
+
+        await Assert.That(clone).IsNotSameReferenceAs(original);
+        await Assert.That(clone.Count).IsEqualTo(1);
+
+        IdentityHashedKey cloneItem = clone.Single();
+        await Assert.That(cloneItem).IsNotSameReferenceAs(item)
+            .Because("Element is a reference type and should be deep-cloned");
+
+        await Assert.That(clone.Contains(cloneItem)).IsTrue()
+            .Because("Looking up the actual element of the cloned set must succeed; " +
+                     "FastCloner copies the original identity-based hash into the cloned bucket, " +
+                     "while the cloned element has a new identity hash, so lookup misses.");
+    }
+
+    [Test]
+    public async Task Dictionary_With_IdentityBased_OverriddenGetHashCode_Key_Should_Be_Lookupable_After_Clone()
+    {
+        IdentityHashedKey key = new IdentityHashedKey { Tag = "k" };
+        Dictionary<IdentityHashedKey, int> original = new Dictionary<IdentityHashedKey, int> { [key] = 42 };
+
+        Dictionary<IdentityHashedKey, int> clone = original.DeepClone();
+
+        await Assert.That(clone).IsNotSameReferenceAs(original);
+        await Assert.That(clone.Count).IsEqualTo(1);
+
+        IdentityHashedKey cloneKey = clone.Keys.Single();
+        await Assert.That(cloneKey).IsNotSameReferenceAs(key);
+
+        await Assert.That(clone.TryGetValue(cloneKey, out int value)).IsTrue()
+            .Because("The cloned dictionary must be able to find its own key. " +
+                     "FastCloner stores stale identity hashes from the original key in the cloned bucket.");
+        await Assert.That(value).IsEqualTo(42);
+    }
+
+    /// <summary>
+    /// Type whose override would normally throw on a default-state probe instance (Tag is null, ToUpper NREs).
+    /// Without an opt-in, the probe catches the throw and conservatively rebuilds the collection. With
+    /// <see cref="FastClonerStableHashAttribute"/> the type author asserts the override is value-based, so
+    /// FastCloner skips the probe and uses the fast memberwise path. Lookups in the cloned set must still work.
+    /// </summary>
+    [FastClonerStableHash]
+    private sealed class ProbeUnfriendlyButStableKey
+    {
+        public string Tag { get; set; } = "";
+        public override int GetHashCode() => Tag.ToUpperInvariant().GetHashCode();
+        public override bool Equals(object? obj)
+            => obj is ProbeUnfriendlyButStableKey other
+               && string.Equals(Tag, other.Tag, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Same hash semantics as <see cref="ProbeUnfriendlyButStableKey"/> but without the attribute. Used to
+    /// assert that the attribute really is what changes the verdict (not some unrelated probe success).
+    /// </summary>
+    private sealed class ProbeUnfriendlyKeyNoAttribute
+    {
+        public string Tag { get; set; } = "";
+        public override int GetHashCode() => Tag.ToUpperInvariant().GetHashCode();
+        public override bool Equals(object? obj)
+            => obj is ProbeUnfriendlyKeyNoAttribute other
+               && string.Equals(Tag, other.Tag, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Test]
+    public async Task FastClonerStableHashAttribute_Marks_Type_As_Stable()
+    {
+        await Assert.That(global::FastCloner.Code.FastClonerSafeTypes.HasStableHashSemantics(typeof(ProbeUnfriendlyButStableKey)))
+            .IsTrue()
+            .Because("[FastClonerStableHash] must short-circuit the probe and declare stable semantics, " +
+                     "even when GetHashCode would throw on default-state instances.");
+
+        // Unchanged behavior for the attribute-less twin: probe throws on null Tag, conservative rebuild.
+        await Assert.That(global::FastCloner.Code.FastClonerSafeTypes.HasStableHashSemantics(typeof(ProbeUnfriendlyKeyNoAttribute)))
+            .IsFalse()
+            .Because("Without the opt-in, a probe that NREs on default state must fall back to rebuild.");
+    }
+
+    [Test]
+    public async Task FastClonerStableHashAttribute_Allows_FastPath_With_Correct_Lookup()
+    {
+        ProbeUnfriendlyButStableKey key = new ProbeUnfriendlyButStableKey { Tag = "Alpha" };
+        HashSet<ProbeUnfriendlyButStableKey> original = [key];
+
+        HashSet<ProbeUnfriendlyButStableKey> clone = original.DeepClone();
+
+        await Assert.That(clone).IsNotSameReferenceAs(original);
+        await Assert.That(clone.Count).IsEqualTo(1);
+
+        ProbeUnfriendlyButStableKey cloneKey = clone.Single();
+        await Assert.That(cloneKey).IsNotSameReferenceAs(key);
+        await Assert.That(clone.Contains(cloneKey)).IsTrue();
+
+        // Equality is case-insensitive, so a fresh key with different casing must also resolve.
+        await Assert.That(clone.Contains(new ProbeUnfriendlyButStableKey { Tag = "alpha" })).IsTrue()
+            .Because("Hash is value-based on Tag (case-insensitive) and survives the clone unchanged.");
+    }
+
     [Test]
     public async Task BufferBlock_Should_Be_Deep_Cloned_Independently()
     {

src/FastCloner.Tests/FastCloner.Tests.csproj

@@ -15,15 +15,15 @@
   <ItemGroup>
     <PackageReference Include="FluentNHibernate" Version="3.4.1" />
     <PackageReference Include="FluentValidation" Version="12.1.1" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
     <PackageReference Include="NHibernate" Version="5.6.0" />
-    <PackageReference Include="ObjectDumper.NET" Version="4.4.10-pre" />
+    <PackageReference Include="ObjectDumper.NET" Version="4.4.13-pre" />
     <PackageReference Include="System.Data.SqlClient" Version="4.9.1" />
     <PackageReference Include="System.Data.SQLite.Core" Version="1.0.119" />
     <PackageReference Include="System.Drawing.Common" Version="10.0.1" />
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing" Version="1.1.3" />
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing" Version="1.1.3" />
-    <PackageReference Include="TUnit" Version="1.22.6" />
+    <PackageReference Include="TUnit" Version="1.43.11" />
   </ItemGroup>
 
   <PropertyGroup>

src/FastCloner/Code/FastClonerSafeTypes.cs

@@ -1,8 +1,12 @@
 using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.Numerics;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+#if !MODERN
+using System.Runtime.Serialization;
+#endif
 using System.Text;
 
 namespace FastCloner.Code;
@@ -115,8 +119,6 @@ private static class TypePrefixes
         public const string SystemRuntimeType = "System.RuntimeType";
         public const string MicrosoftExtensions = "Microsoft.Extensions.DependencyInjection.";
     }
-
-    private static readonly Assembly propertyInfoAssembly = typeof(PropertyInfo).Assembly;
 
     private static bool IsReflectionType(Type type)
     {
@@ -206,7 +208,8 @@ private static bool CanReturnSameType(Type type, HashSet<Type>? processingTypes
 
         if (type.IsGenericType)
         {
-            Type? genericDef = type.GetGenericTypeDefinition();
+            Type genericDef = type.GetGenericTypeDefinition();
+            
             if (knownTypes.TryGetValue(genericDef, out bool isGenericSafe))
             {
                 knownTypes.TryAdd(type, isGenericSafe);
@@ -271,7 +274,7 @@ internal static void ClearKnownTypesCache()
     }
 
     /// <summary>
-    /// Determines whether GetHashCode() result won't change after deep cloning (best effort).
+    /// Determines whether GetHashCode() result won't change after deep cloning.
     /// </summary>
     internal static bool HasStableHashSemantics(Type type)
     {
@@ -280,29 +283,24 @@ internal static bool HasStableHashSemantics(Type type)
 
     private static bool CalculateHasStableHashSemantics(Type type)
     {
-        // Primitives are always stable - their hash is based on their value
         if (type.IsPrimitive)
             return true;
 
-        // String is immutable and has value-based hash
         if (type == typeof(string))
             return true;
 
-        // Enums are always stable - hash is based on underlying value
         if (type.IsEnum)
             return true;
 
-        // Value types: even if they don't override GetHashCode, their fields are copied
-        // so the hash remains consistent after cloning
         if (type.IsValueType)
             return true;
 
-        // Known safe types from our dictionary are stable
         if (DefaultKnownTypes.ContainsKey(type))
             return true;
-        
-        // Check if the type overrides GetHashCode (not using object.GetHashCode)
-        // If a type has overridden GetHashCode, it's using value-based hashing
+
+        if (type.IsDefined(typeof(FastClonerStableHashAttribute), inherit: true))
+            return true;
+
         MethodInfo? getHashCodeMethod = type.GetMethod(
             "GetHashCode",
             BindingFlags.Public | BindingFlags.Instance,
@@ -312,13 +310,46 @@ private static bool CalculateHasStableHashSemantics(Type type)
 
         if (getHashCodeMethod is not null && getHashCodeMethod.DeclaringType != typeof(object))
         {
-            // Type has custom GetHashCode implementation
-            // This indicates value-based equality semantics
-            return true;
+            return ProbeOverriddenHashIsValueBased(type);
         }
 
-        // Reference types using default GetHashCode use identity-based hash
-        // These are NOT stable after cloning
         return false;
     }
+
+    [SuppressMessage("Usage", "CA1816:Dispose methods should call SuppressFinalize")]
+    private static bool ProbeOverriddenHashIsValueBased(Type type)
+    {
+        if (type.IsAbstract || type.IsInterface || type.ContainsGenericParameters
+            || type.IsArray || type.IsPointer || type.IsByRef || type == typeof(string))
+        {
+            return false;
+        }
+
+        try
+        {
+            object instance1 = CreateUninitialized(type);
+            object instance2 = CreateUninitialized(type);
+            
+            GC.SuppressFinalize(instance1);
+            GC.SuppressFinalize(instance2);
+
+            int hash1 = instance1.GetHashCode();
+            int hash2 = instance2.GetHashCode();
+
+            return hash1 == hash2;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static object CreateUninitialized(Type type)
+    {
+#if MODERN
+        return RuntimeHelpers.GetUninitializedObject(type);
+#else
+        return FormatterServices.GetUninitializedObject(type);
+#endif
+    }
 }

src/FastCloner/Code/FastClonerStableHashAttribute.cs

@@ -0,0 +1,49 @@
+namespace FastCloner;
+
+/// <summary>
+/// Declares that <see cref="object.GetHashCode"/> on this type is stable across deep clones,
+/// i.e. a deep-cloned instance will always produce the same hash code as the original.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Applying this attribute lets FastCloner skip its runtime probe and use the fast memberwise
+/// clone path for hash-based collections (<see cref="System.Collections.Generic.HashSet{T}"/>,
+/// <see cref="System.Collections.Generic.Dictionary{TKey,TValue}"/>, etc.) keyed by this type,
+/// which is significantly cheaper than rebuilding the collection.
+/// </para>
+/// <para>
+/// Use this attribute when:
+/// <list type="bullet">
+/// <item><description>Your <c>GetHashCode</c> is a pure function of the type's fields, OR</description></item>
+/// <item><description>Your <c>GetHashCode</c> returns a constant, OR</description></item>
+/// <item><description>You know - by construction - that two equal-by-fields instances always hash the same.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// <b>Do not</b> apply this attribute if <c>GetHashCode</c> depends on object identity (e.g. uses
+/// <see cref="System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode(object)"/>, or hashes a
+/// per-instance handle that isn't preserved through cloning). Marking such a type as stable will
+/// produce hash collections that lose the ability to look up their own contents after a clone.
+/// </para>
+/// <para>
+/// This attribute is a positive declaration: it marks <i>this</i> type as stable. It does not affect
+/// the cloning behavior of the type's members.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// [FastClonerStableHash]
+/// public sealed class CompositeKey
+/// {
+///     public int Major { get; }
+///     public int Minor { get; }
+///     public override int GetHashCode() => HashCode.Combine(Major, Minor);
+///     public override bool Equals(object? obj)
+///         =&gt; obj is CompositeKey other &amp;&amp; other.Major == Major &amp;&amp; other.Minor == Minor;
+/// }
+/// </code>
+/// </example>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+public sealed class FastClonerStableHashAttribute : Attribute
+{
+}