com.wallstop-studios.unity-helpers 2.0.0-rc81.7 → 2.0.0

package/Runtime/Core/Serialization/Serializer.cs

@@ -1,195 +1,2121 @@
-namespace WallstopStudios.UnityHelpers.Core.Serialization
-{
-    using System;
-    using System.ComponentModel;
-    using System.IO;
-    using System.Runtime.Serialization.Formatters.Binary;
-    using System.Text;
-    using System.Text.Json;
-    using System.Text.Json.Serialization;
-    using Extension;
-    using JsonConverters;
-    using TypeConverter = JsonConverters.TypeConverter;
-
-    internal static class SerializerEncoding
-    {
-        public static readonly Encoding Encoding;
-        public static readonly JsonSerializerOptions NormalJsonOptions;
-        public static readonly JsonSerializerOptions PrettyJsonOptions;
-
-        static SerializerEncoding()
-        {
-            Encoding = Encoding.UTF8;
-            NormalJsonOptions = new JsonSerializerOptions
-            {
-                IgnoreReadOnlyFields = false,
-                IgnoreReadOnlyProperties = false,
-                ReferenceHandler = ReferenceHandler.IgnoreCycles,
-                IncludeFields = true,
-                PropertyNameCaseInsensitive = true,
-                Converters =
-                {
-                    new JsonStringEnumConverter(),
-                    Vector3Converter.Instance,
-                    Vector2Converter.Instance,
-                    Vector4Converter.Instance,
-                    Matrix4x4Converter.Instance,
-                    TypeConverter.Instance,
-                    GameObjectConverter.Instance,
-                    ColorConverter.Instance,
-                },
-            };
-
-            PrettyJsonOptions = new JsonSerializerOptions
-            {
-                IgnoreReadOnlyFields = false,
-                IgnoreReadOnlyProperties = false,
-                ReferenceHandler = ReferenceHandler.IgnoreCycles,
-                PropertyNameCaseInsensitive = true,
-                IncludeFields = true,
-                Converters =
-                {
-                    new JsonStringEnumConverter(),
-                    Vector3Converter.Instance,
-                    Vector2Converter.Instance,
-                    Vector4Converter.Instance,
-                    Matrix4x4Converter.Instance,
-                    TypeConverter.Instance,
-                    GameObjectConverter.Instance,
-                    ColorConverter.Instance,
-                },
-                WriteIndented = true,
-            };
-        }
-    }
-
-    public enum SerializationType
-    {
-        SystemBinary,
-        Protobuf,
-    }
-
-    public static class Serializer
-    {
-        public static T Deserialize<T>(byte[] serialized, SerializationType serializationType)
-        {
-            switch (serializationType)
-            {
-                case SerializationType.SystemBinary:
-                    return BinaryDeserialize<T>(serialized);
-                case SerializationType.Protobuf:
-                    return ProtoDeserialize<T>(serialized);
-                default:
-                    throw new InvalidEnumArgumentException(
-                        nameof(serializationType),
-                        (int)serializationType,
-                        typeof(SerializationType)
-                    );
-            }
-        }
-
-        public static byte[] Serialize<T>(T instance, SerializationType serializationType)
-        {
-            switch (serializationType)
-            {
-                case SerializationType.SystemBinary:
-                    return BinarySerialize(instance);
-                case SerializationType.Protobuf:
-                    return ProtoSerialize(instance);
-                default:
-                    throw new InvalidEnumArgumentException(
-                        nameof(serializationType),
-                        (int)serializationType,
-                        typeof(SerializationType)
-                    );
-            }
-        }
-
-        public static T BinaryDeserialize<T>(byte[] data)
-        {
-            using MemoryStream memoryStream = new(data);
-            BinaryFormatter binaryFormatter = new();
-            memoryStream.Position = 0;
-            return (T)binaryFormatter.Deserialize(memoryStream);
-        }
-
-        public static byte[] BinarySerialize<T>(T input)
-        {
-            using MemoryStream memoryStream = new();
-            BinaryFormatter binaryFormatter = new();
-            binaryFormatter.Serialize(memoryStream, input);
-            return memoryStream.ToArray();
-        }
-
-        public static T ProtoDeserialize<T>(byte[] data)
-        {
-            using MemoryStream memoryStream = new(data);
-            return ProtoBuf.Serializer.Deserialize<T>(memoryStream);
-        }
-
-        public static T ProtoDeserialize<T>(byte[] data, Type type)
-        {
-            using MemoryStream memoryStream = new(data);
-            return (T)ProtoBuf.Serializer.Deserialize(type, memoryStream);
-        }
-
-        public static byte[] ProtoSerialize<T>(T input)
-        {
-            using MemoryStream memoryStream = new();
-            ProtoBuf.Serializer.Serialize(memoryStream, input);
-            return memoryStream.ToArray();
-        }
-
-        public static T JsonDeserialize<T>(string data, Type type = null)
-        {
-            return (T)
-                JsonSerializer.Deserialize(
-                    data,
-                    type ?? typeof(T),
-                    SerializerEncoding.NormalJsonOptions
-                );
-        }
-
-        public static byte[] JsonSerialize<T>(T input)
-        {
-            return JsonStringify(input).GetBytes();
-        }
-
-        public static string JsonStringify<T>(T input, bool pretty = false)
-        {
-            JsonSerializerOptions options = pretty
-                ? SerializerEncoding.PrettyJsonOptions
-                : SerializerEncoding.NormalJsonOptions;
-            Type parameterType = typeof(T);
-            if (
-                parameterType.IsAbstract
-                || parameterType.IsInterface
-                || parameterType == typeof(object)
-            )
-            {
-                object data = input;
-                if (data == null)
-                {
-                    return "{}";
-                }
-
-                Type type = data.GetType();
-                return JsonSerializer.Serialize(data, type, options);
-            }
-
-            return JsonSerializer.Serialize(input, options);
-        }
-
-        public static T ReadFromJsonFile<T>(string path)
-        {
-            string settingsAsText = File.ReadAllText(path, SerializerEncoding.Encoding);
-            return JsonDeserialize<T>(settingsAsText);
-        }
-
-        public static void WriteToJsonFile<T>(T input, string path, bool pretty = true)
-        {
-            string jsonAsText = JsonStringify(input, pretty);
-            File.WriteAllText(path, jsonAsText);
-        }
-    }
-}
+namespace WallstopStudios.UnityHelpers.Core.Serialization
+{
+    using System;
+    using System.Buffers;
+    using System.Collections.Concurrent;
+    using System.ComponentModel;
+    using System.IO;
+    using System.Linq;
+    using System.Reflection;
+    using System.Runtime.Serialization.Formatters.Binary;
+    using System.Text;
+    using System.Text.Json;
+    using System.Text.Json.Serialization;
+    using System.Threading.Tasks;
+    using JsonConverters;
+    using ProtoBuf;
+    using WallstopStudios.UnityHelpers.Core.Helper;
+    using TypeConverter = JsonConverters.TypeConverter;
+
+    internal static class SerializerEncoding
+    {
+        public static readonly Encoding Encoding;
+        public static readonly JsonSerializerOptions NormalJsonOptions;
+        public static readonly JsonSerializerOptions PrettyJsonOptions;
+        public static readonly JsonSerializerOptions FastJsonOptions;
+        public static readonly JsonSerializerOptions FastPocoJsonOptions;
+
+        public static JsonSerializerOptions GetNormalJsonOptions()
+        {
+            return new JsonSerializerOptions
+            {
+                IgnoreReadOnlyFields = false,
+                IgnoreReadOnlyProperties = false,
+                ReferenceHandler = ReferenceHandler.IgnoreCycles,
+                IncludeFields = true,
+                PropertyNameCaseInsensitive = true,
+                NumberHandling =
+                    JsonNumberHandling.AllowNamedFloatingPointLiterals
+                    | JsonNumberHandling.AllowReadingFromString,
+                ReadCommentHandling = JsonCommentHandling.Skip,
+                AllowTrailingCommas = true,
+                Converters =
+                {
+                    RangeConverterFactory.Instance,
+                    FastVector2IntConverter.Instance,
+                    FastVector3IntConverter.Instance,
+                    new JsonStringEnumConverter(),
+                    Vector3Converter.Instance,
+                    Vector2Converter.Instance,
+                    Vector4Converter.Instance,
+                    Vector2IntConverter.Instance,
+                    Vector3IntConverter.Instance,
+                    Matrix4x4Converter.Instance,
+                    QuaternionConverter.Instance,
+                    LayerMaskConverter.Instance,
+                    ResolutionConverter.Instance,
+                    RenderTextureDescriptorConverter.Instance,
+                    MinMaxCurveConverter.Instance,
+                    MinMaxGradientConverter.Instance,
+                    ColorBlockConverter.Instance,
+                    BoundingSphereConverter.Instance,
+                    RaycastHitConverter.Instance,
+                    TouchConverter.Instance,
+                    SceneConverter.Instance,
+                    PoseConverter.Instance,
+                    PlaneConverter.Instance,
+                    RayConverter.Instance,
+                    Ray2DConverter.Instance,
+                    RectOffsetConverter.Instance,
+                    RangeIntConverter.Instance,
+                    Hash128Converter.Instance,
+                    AnimationCurveConverter.Instance,
+                    GradientConverter.Instance,
+                    SphericalHarmonicsL2Converter.Instance,
+                    TypeConverter.Instance,
+                    GameObjectConverter.Instance,
+                    ColorConverter.Instance,
+                    Color32Converter.Instance,
+                    RectConverter.Instance,
+                    RectIntConverter.Instance,
+                    BoundsConverter.Instance,
+                    BoundsIntConverter.Instance,
+                    BitSetConverter.Instance,
+                    ImmutableBitSetConverter.Instance,
+                    DequeConverterFactory.Instance,
+                    CyclicBufferConverterFactory.Instance,
+                    KVector2Converter.Instance,
+                },
+            };
+            ;
+        }
+
+        public static JsonSerializerOptions GetPrettyJsonOptions()
+        {
+            return new JsonSerializerOptions
+            {
+                IgnoreReadOnlyFields = false,
+                IgnoreReadOnlyProperties = false,
+                ReferenceHandler = ReferenceHandler.IgnoreCycles,
+                PropertyNameCaseInsensitive = true,
+                IncludeFields = true,
+                NumberHandling =
+                    JsonNumberHandling.AllowNamedFloatingPointLiterals
+                    | JsonNumberHandling.AllowReadingFromString,
+                ReadCommentHandling = JsonCommentHandling.Skip,
+                AllowTrailingCommas = true,
+                Converters =
+                {
+                    RangeConverterFactory.Instance,
+                    FastVector2IntConverter.Instance,
+                    FastVector3IntConverter.Instance,
+                    new JsonStringEnumConverter(),
+                    Vector3Converter.Instance,
+                    Vector2Converter.Instance,
+                    Vector4Converter.Instance,
+                    Vector2IntConverter.Instance,
+                    Vector3IntConverter.Instance,
+                    Matrix4x4Converter.Instance,
+                    QuaternionConverter.Instance,
+                    LayerMaskConverter.Instance,
+                    ResolutionConverter.Instance,
+                    RenderTextureDescriptorConverter.Instance,
+                    MinMaxCurveConverter.Instance,
+                    MinMaxGradientConverter.Instance,
+                    ColorBlockConverter.Instance,
+                    BoundingSphereConverter.Instance,
+                    RaycastHitConverter.Instance,
+                    TouchConverter.Instance,
+                    SceneConverter.Instance,
+                    PoseConverter.Instance,
+                    PlaneConverter.Instance,
+                    RayConverter.Instance,
+                    Ray2DConverter.Instance,
+                    RectOffsetConverter.Instance,
+                    RangeIntConverter.Instance,
+                    Hash128Converter.Instance,
+                    AnimationCurveConverter.Instance,
+                    GradientConverter.Instance,
+                    SphericalHarmonicsL2Converter.Instance,
+                    TypeConverter.Instance,
+                    GameObjectConverter.Instance,
+                    ColorConverter.Instance,
+                    Color32Converter.Instance,
+                    RectConverter.Instance,
+                    RectIntConverter.Instance,
+                    BoundsConverter.Instance,
+                    BoundsIntConverter.Instance,
+                    BitSetConverter.Instance,
+                    ImmutableBitSetConverter.Instance,
+                    DequeConverterFactory.Instance,
+                    CyclicBufferConverterFactory.Instance,
+                    KVector2Converter.Instance,
+                },
+                WriteIndented = true,
+            };
+        }
+
+        public static JsonSerializerOptions GetFastJsonOptions()
+        {
+            return new JsonSerializerOptions
+            {
+                IgnoreReadOnlyFields = false,
+                IgnoreReadOnlyProperties = true,
+                ReferenceHandler = null,
+                PropertyNameCaseInsensitive = false,
+                IncludeFields = false,
+                NumberHandling = JsonNumberHandling.Strict,
+                ReadCommentHandling = JsonCommentHandling.Disallow,
+                AllowTrailingCommas = false,
+                Converters =
+                {
+                    RangeConverterFactory.Instance,
+                    FastVector2IntConverter.Instance,
+                    FastVector3IntConverter.Instance,
+                    Vector3Converter.Instance,
+                    Vector2Converter.Instance,
+                    Vector4Converter.Instance,
+                    Vector2IntConverter.Instance,
+                    Vector3IntConverter.Instance,
+                    Matrix4x4Converter.Instance,
+                    QuaternionConverter.Instance,
+                    LayerMaskConverter.Instance,
+                    ResolutionConverter.Instance,
+                    RenderTextureDescriptorConverter.Instance,
+                    MinMaxCurveConverter.Instance,
+                    MinMaxGradientConverter.Instance,
+                    ColorBlockConverter.Instance,
+                    BoundingSphereConverter.Instance,
+                    RaycastHitConverter.Instance,
+                    TouchConverter.Instance,
+                    SceneConverter.Instance,
+                    PoseConverter.Instance,
+                    PlaneConverter.Instance,
+                    RayConverter.Instance,
+                    Ray2DConverter.Instance,
+                    RectOffsetConverter.Instance,
+                    RangeIntConverter.Instance,
+                    Hash128Converter.Instance,
+                    AnimationCurveConverter.Instance,
+                    GradientConverter.Instance,
+                    SphericalHarmonicsL2Converter.Instance,
+                    TypeConverter.Instance,
+                    GameObjectConverter.Instance,
+                    ColorConverter.Instance,
+                    Color32Converter.Instance,
+                    RectConverter.Instance,
+                    RectIntConverter.Instance,
+                    BoundsConverter.Instance,
+                    BoundsIntConverter.Instance,
+                    BitSetConverter.Instance,
+                    ImmutableBitSetConverter.Instance,
+                    DequeConverterFactory.Instance,
+                    CyclicBufferConverterFactory.Instance,
+                    KVector2Converter.Instance,
+                },
+            };
+        }
+
+        public static JsonSerializerOptions GetFastPocoJsonOptions()
+        {
+            return new JsonSerializerOptions
+            {
+                IgnoreReadOnlyFields = false,
+                IgnoreReadOnlyProperties = false,
+                ReferenceHandler = null,
+                PropertyNameCaseInsensitive = false,
+                IncludeFields = false,
+                NumberHandling = JsonNumberHandling.Strict,
+                ReadCommentHandling = JsonCommentHandling.Disallow,
+                AllowTrailingCommas = false,
+                // No converters for POCO to minimize overhead
+            };
+        }
+
+        static SerializerEncoding()
+        {
+            Encoding = Encoding.UTF8;
+            NormalJsonOptions = GetNormalJsonOptions();
+            PrettyJsonOptions = GetPrettyJsonOptions();
+            FastJsonOptions = GetFastJsonOptions();
+            FastPocoJsonOptions = GetFastPocoJsonOptions();
+        }
+    }
+
+    /// <summary>
+    /// Selects the wire format used by <see cref="Serializer"/>.
+    /// </summary>
+    /// <remarks>
+    /// Choose a format based on your requirements:
+    /// <list type="bullet">
+    /// <item>
+    /// <description>
+    /// <see cref="Json"/> — Human‑readable and diff‑friendly. Uses System.Text.Json with Unity‑aware
+    /// converters for common types (e.g., Vector2/3/4, Matrix4x4, Color, Type).
+    /// Prefer for save files, configs, and tooling.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// <see cref="Protobuf"/> — Compact binary with great performance using protobuf‑net.
+    /// Prefer for networking, large payloads, and memory‑sensitive scenarios.
+    /// Requires opt‑in attributes like [ProtoContract]/[ProtoMember] or runtime models.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// <see cref="SystemBinary"/> — .NET BinaryFormatter. Legacy and trusted‑only. Not
+    /// cross‑version/portable and unsafe for untrusted input. Use only for ephemeral/dev data.
+    /// </description>
+    /// </item>
+    /// </list>
+    /// </remarks>
+    public enum SerializationType
+    {
+        /// <summary>Unspecified format; not valid for read/write.</summary>
+        [Obsolete("Please use a valid enum value")]
+        None = 0,
+
+        /// <summary>Legacy .NET BinaryFormatter. Trusted/ephemeral data only.</summary>
+        [Obsolete(
+            "BinaryFormatter is obsolete and unsafe for untrusted data. "
+                + "Prefer Json or Protobuf for new code."
+        )]
+        SystemBinary = 1,
+
+        /// <summary>protobuf-net compact binary. Best for networking and high-performance.</summary>
+        Protobuf = 2,
+
+        /// <summary>System.Text.Json text. Human-readable and diff-friendly.</summary>
+        Json = 3,
+    }
+
+    /// <summary>
+    /// Unified serialization helpers for JSON, protobuf‑net, and legacy BinaryFormatter.
+    /// </summary>
+    /// <remarks>
+    /// Highlights
+    /// <list type="bullet">
+    /// <item><description>JSON: Uses pooled writers and Unity‑aware converters; supports pretty printing.</description></item>
+    /// <item><description>Protobuf: Compact binary via protobuf‑net; supports interface/abstract types via root resolution or <see cref="RegisterProtobufRoot(Type, Type)"/>.</description></item>
+    /// <item><description>Binary: Convenience for legacy only; do not feed untrusted data.</description></item>
+    /// <item><description>Minimal allocations with ArrayPool-backed streams to reduce GC pressure.</description></item>
+    /// </list>
+    /// When to use what
+    /// <list type="bullet">
+    /// <item><description>Prefer <see cref="SerializationType.Json"/> for save systems, settings, and tools.</description></item>
+    /// <item><description>Prefer <see cref="SerializationType.Protobuf"/> for networking, large or frequent messages.</description></item>
+    /// <item><description>Reserve <see cref="SerializationType.SystemBinary"/> for trusted legacy scenarios only.</description></item>
+    /// </list>
+    /// </remarks>
+    /// <example>
+    /// JSON save/config
+    /// <code>
+    /// var save = new SaveData { Level = 3 };
+    /// // To string
+    /// string text = Serializer.JsonStringify(save, pretty: true);
+    /// // File IO
+    /// Serializer.WriteToJsonFile(save, "save.json", pretty: true);
+    /// var loaded = Serializer.ReadFromJsonFile&lt;SaveData&gt;("save.json");
+    /// </code>
+    /// Protobuf networking
+    /// <code>
+    /// [ProtoContract]
+    /// class NetworkMessage { [ProtoMember(1)] public int Id { get; set; } }
+    /// byte[] bytes = Serializer.ProtoSerialize(new NetworkMessage { Id = 42 });
+    /// NetworkMessage msg = Serializer.ProtoDeserialize&lt;NetworkMessage&gt;(bytes);
+    /// </code>
+    /// Legacy BinaryFormatter (trusted only)
+    /// <code>
+    /// byte[] blob = Serializer.BinarySerialize(obj);
+    /// var roundtrip = Serializer.BinaryDeserialize&lt;SomeType&gt;(blob);
+    /// </code>
+    /// </example>
+    public static class Serializer
+    {
+        /// <summary>
+        /// Returns a copy of the package's Normal JSON options. The returned instance is independent
+        /// of internal defaults, so modifying it won't affect global behavior. Cache and reuse the
+        /// returned instance across calls to benefit from System.Text.Json metadata caches.
+        /// </summary>
+        public static JsonSerializerOptions CreateNormalJsonOptions() =>
+            SerializerEncoding.GetNormalJsonOptions();
+
+        /// <summary>
+        /// Returns a copy of the package's Pretty (indented) JSON options.
+        /// </summary>
+        public static JsonSerializerOptions CreatePrettyJsonOptions() =>
+            SerializerEncoding.GetPrettyJsonOptions();
+
+        /// <summary>
+        /// Returns a copy of the package's Fast JSON options, tuned for hot paths with reduced validation
+        /// and features to minimize allocations and branching. See docs for trade-offs.
+        /// </summary>
+        public static JsonSerializerOptions CreateFastJsonOptions() =>
+            SerializerEncoding.GetFastJsonOptions();
+
+        /// <summary>
+        /// Returns a copy of the package's Fast POCO JSON options.
+        /// Strict, minimal, and with no Unity-specific converters.
+        /// Use for pure POCO graphs when you want the fastest possible serialization/deserialization.
+        /// Notes:
+        /// - Case-sensitive property names (faster matching)
+        /// - No comments/trailing commas; strict numbers only
+        /// - IncludeFields = false (prefer properties for performance)
+        /// - Returns a new instance each call; cache and reuse within your app to leverage STJ metadata caches
+        /// </summary>
+        public static JsonSerializerOptions CreateFastPocoJsonOptions() =>
+            new(SerializerEncoding.FastPocoJsonOptions);
+
+        // Small protobuf payloads benefit from protobuf-net's MemoryStream fast-path (TryGetBuffer).
+        // Larger payloads see wins from our pooled read-only stream to avoid per-iteration allocations.
+        private const int ProtobufMemoryStreamThreshold = 4096; // bytes
+
+        // Optional zero-copy path if protobuf-net supports ReadOnlyMemory<byte>/ReadOnlySequence<byte> overloads
+        private static readonly MethodInfo ProtoDeserializeTypeFromROM;
+        private static readonly MethodInfo ProtoDeserializeTypeFromROS;
+        private static readonly Func<
+            Type,
+            ReadOnlyMemory<byte>,
+            object
+        > ProtoDeserializeTypeFromROMFast;
+        private static readonly Func<
+            Type,
+            ReadOnlySequence<byte>,
+            object
+        > ProtoDeserializeTypeFromROSFast;
+
+        static Serializer()
+        {
+            // Initialize protobuf surrogates and any other serialization bootstrapping here
+            // so initialization does not depend on JSON option access.
+            ProtobufUnityModel.EnsureInitialized();
+            try
+            {
+                MethodInfo[] methods = typeof(ProtoBuf.Serializer).GetMethods(
+                    BindingFlags.Public | BindingFlags.Static
+                );
+                foreach (MethodInfo mi in methods)
+                {
+                    if (mi.Name != "Deserialize")
+                    {
+                        continue;
+                    }
+
+                    ParameterInfo[] pars = mi.GetParameters();
+                    if (pars.Length != 2)
+                    {
+                        continue;
+                    }
+
+                    if (pars[0].ParameterType != typeof(Type))
+                    {
+                        continue;
+                    }
+
+                    Type p1 = pars[1].ParameterType;
+                    switch (p1.IsGenericType)
+                    {
+                        case true when p1.GetGenericTypeDefinition() == typeof(ReadOnlyMemory<>):
+                        {
+                            Type genArg = p1.GetGenericArguments()[0];
+                            if (genArg == typeof(byte))
+                            {
+                                ProtoDeserializeTypeFromROM ??= mi;
+                                try
+                                {
+                                    ProtoDeserializeTypeFromROMFast =
+                                        ReflectionHelpers.GetStaticMethodInvoker<
+                                            Type,
+                                            ReadOnlyMemory<byte>,
+                                            object
+                                        >(mi);
+                                }
+                                catch { }
+                            }
+
+                            break;
+                        }
+                        case true when p1.GetGenericTypeDefinition() == typeof(ReadOnlySequence<>):
+                        {
+                            Type genArg = p1.GetGenericArguments()[0];
+                            if (genArg == typeof(byte))
+                            {
+                                ProtoDeserializeTypeFromROS ??= mi;
+                                try
+                                {
+                                    ProtoDeserializeTypeFromROSFast =
+                                        ReflectionHelpers.GetStaticMethodInvoker<
+                                            Type,
+                                            ReadOnlySequence<byte>,
+                                            object
+                                        >(mi);
+                                }
+                                catch { }
+                            }
+
+                            break;
+                        }
+                    }
+                }
+            }
+            catch
+            {
+                // Reflection probing failed; keep nulls and fall back to streams
+            }
+        }
+
+        private static readonly ConcurrentDictionary<Type, Type> ProtobufRootCache = new();
+        private static readonly Type NoRootMarker = typeof(void);
+
+        // Centralized decision logic for protobuf runtime vs declared handling
+        internal static bool ShouldUseRuntimeTypeForProtobuf<T>(
+            Type declared,
+            T instance,
+            bool forceRuntimeType
+        )
+        {
+            if (forceRuntimeType)
+            {
+                return true;
+            }
+
+            if (declared == null)
+            {
+                return true;
+            }
+
+            if (declared.IsInterface || declared.IsAbstract || declared == typeof(object))
+            {
+                return true;
+            }
+
+            // Last resort: if the declared type is a reference type and the runtime type differs,
+            // prefer using the runtime serializer to avoid protobuf-net subtype errors.
+            if (!declared.IsValueType && instance != null && instance.GetType() != declared)
+            {
+                return true;
+            }
+
+            return false;
+        }
+
+        private static readonly Utils.WallstopGenericPool<BinaryFormatter> BinaryFormatterPool =
+            new(() => new BinaryFormatter());
+
+        private static readonly Utils.WallstopGenericPool<Utf8JsonWriter> JsonWriterPool = new(
+            () => new Utf8JsonWriter(Stream.Null, new JsonWriterOptions { SkipValidation = true }),
+            onRelease: writer =>
+            {
+                writer.Reset(Stream.Null);
+            },
+            onDisposal: stream => stream.Dispose()
+        );
+
+        /// <summary>
+        /// Registers a concrete or abstract protobuf root type for a declared interface/abstract/object type.
+        /// The root must be assignable to <paramref name="declared"/> and annotated with [ProtoContract].
+        /// Subsequent deserializations to the declared type will use the registered root.
+        /// </summary>
+        /// <remarks>
+        /// Use this when deserializing to an interface/abstract/object and you want deterministic root selection
+        /// instead of relying on reflection inference.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// // Given an interface and concrete implementation
+        /// [ProtoContract] class PlayerJoined : IEvent { [ProtoMember(1)] public string Name { get; set; } }
+        /// Serializer.RegisterProtobufRoot(typeof(IEvent), typeof(PlayerJoined));
+        /// var evt = Serializer.ProtoDeserialize&lt;IEvent&gt;(bytes);
+        /// </code>
+        /// </example>
+        /// <exception cref="ArgumentNullException">If declared or root is null.</exception>
+        /// <exception cref="ArgumentException">If root is not assignable to declared or missing [ProtoContract].</exception>
+        /// <exception cref="InvalidOperationException">If a conflicting root is already registered.</exception>
+        public static void RegisterProtobufRoot(Type declared, Type root)
+        {
+            if (declared == null)
+            {
+                throw new ArgumentNullException(nameof(declared));
+            }
+            if (root == null)
+            {
+                throw new ArgumentNullException(nameof(root));
+            }
+            if (!declared.IsAssignableFrom(root))
+            {
+                throw new ArgumentException(
+                    $"Type {root.FullName} is not assignable to {declared.FullName}",
+                    nameof(root)
+                );
+            }
+            if (!ReflectionHelpers.HasAttributeSafe<ProtoContractAttribute>(root))
+            {
+                throw new ArgumentException(
+                    $"Type {root.FullName} must be annotated with [ProtoContract]",
+                    nameof(root)
+                );
+            }
+
+            if (ProtobufRootCache.TryGetValue(declared, out Type existing))
+            {
+                if (existing != root && existing != NoRootMarker)
+                {
+                    throw new InvalidOperationException(
+                        $"A different root {existing.FullName} is already registered for {declared.FullName}"
+                    );
+                }
+            }
+
+            ProtobufRootCache[declared] = root;
+        }
+
+        /// <summary>
+        /// Generic convenience overload for registering a protobuf root type.
+        /// </summary>
+        /// <remarks>
+        /// Useful for polymorphic APIs: map <typeparamref name="TDeclared"/> to <typeparamref name="TRoot"/> once,
+        /// then call <see cref="ProtoDeserialize{T}(byte[])"/> for the declared type.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// Serializer.RegisterProtobufRoot&lt;IEvent, PlayerJoined&gt;();
+        /// IEvent evt = Serializer.ProtoDeserialize&lt;IEvent&gt;(bytes);
+        /// </code>
+        /// </example>
+        public static void RegisterProtobufRoot<TDeclared, TRoot>()
+            where TRoot : TDeclared
+        {
+            RegisterProtobufRoot(typeof(TDeclared), typeof(TRoot));
+        }
+
+        /// <summary>
+        /// Deserializes a payload that was serialized with the specified <paramref name="serializationType"/>.
+        /// </summary>
+        /// <typeparam name="T">The target type.</typeparam>
+        /// <param name="serialized">Payload bytes to decode.</param>
+        /// <param name="serializationType">The format the payload is encoded with.</param>
+        /// <returns>The decoded instance.</returns>
+        /// <example>
+        /// JSON
+        /// <code>
+        /// byte[] data = Serializer.JsonSerialize(save);
+        /// SaveData loaded = Serializer.Deserialize&lt;SaveData&gt;(data, SerializationType.Json);
+        /// </code>
+        /// Protobuf
+        /// <code>
+        /// byte[] msg = Serializer.ProtoSerialize(message);
+        /// NetworkMessage decoded = Serializer.Deserialize&lt;NetworkMessage&gt;(msg, SerializationType.Protobuf);
+        /// </code>
+        /// </example>
+        public static T Deserialize<T>(byte[] serialized, SerializationType serializationType)
+        {
+            switch (serializationType)
+            {
+#pragma warning disable CS0618 // Type or member is obsolete
+                case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
+                {
+                    return BinaryDeserialize<T>(serialized);
+                }
+                case SerializationType.Protobuf:
+                {
+                    return ProtoDeserialize<T>(serialized);
+                }
+                case SerializationType.Json:
+                {
+                    return JsonDeserialize<T>(serialized);
+                }
+                default:
+                {
+                    throw new InvalidEnumArgumentException(
+                        nameof(serializationType),
+                        (int)serializationType,
+                        typeof(SerializationType)
+                    );
+                }
+            }
+        }
+
+        /// <summary>
+        /// Serializes an instance into bytes using the specified <paramref name="serializationType"/>.
+        /// </summary>
+        /// <typeparam name="T">The instance type.</typeparam>
+        /// <param name="instance">The instance to encode.</param>
+        /// <param name="serializationType">The target wire format.</param>
+        /// <returns>Serialized bytes.</returns>
+        /// <example>
+        /// <code>
+        /// // As bytes
+        /// byte[] data = Serializer.Serialize(save, SerializationType.Json);
+        /// // Later
+        /// SaveData loaded = Serializer.Deserialize&lt;SaveData&gt;(data, SerializationType.Json);
+        /// </code>
+        /// </example>
+        public static byte[] Serialize<T>(T instance, SerializationType serializationType)
+        {
+            switch (serializationType)
+            {
+#pragma warning disable CS0618 // Type or member is obsolete
+                case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
+                {
+                    return BinarySerialize(instance);
+                }
+                case SerializationType.Protobuf:
+                {
+                    return ProtoSerialize(instance);
+                }
+                case SerializationType.Json:
+                {
+                    return JsonSerialize(instance);
+                }
+                default:
+                {
+                    throw new InvalidEnumArgumentException(
+                        nameof(serializationType),
+                        (int)serializationType,
+                        typeof(SerializationType)
+                    );
+                }
+            }
+        }
+
+        /// <summary>
+        /// Serializes into a caller-provided buffer to avoid an extra allocation.
+        /// </summary>
+        /// <typeparam name="T">The instance type.</typeparam>
+        /// <param name="instance">The instance to encode.</param>
+        /// <param name="serializationType">The target wire format.</param>
+        /// <param name="buffer">Destination buffer reference. Resized if too small.</param>
+        /// <returns>The number of valid bytes written to <paramref name="buffer"/>.</returns>
+        public static int Serialize<T>(
+            T instance,
+            SerializationType serializationType,
+            ref byte[] buffer
+        )
+        {
+            switch (serializationType)
+            {
+#pragma warning disable CS0618 // Type or member is obsolete
+                case SerializationType.SystemBinary:
+#pragma warning restore CS0618 // Type or member is obsolete
+                {
+                    return BinarySerialize(instance, ref buffer);
+                }
+                case SerializationType.Protobuf:
+                {
+                    return ProtoSerialize(instance, ref buffer);
+                }
+                case SerializationType.Json:
+                {
+                    return JsonSerialize(instance, ref buffer);
+                }
+                default:
+                {
+                    throw new InvalidEnumArgumentException(
+                        nameof(serializationType),
+                        (int)serializationType,
+                        typeof(SerializationType)
+                    );
+                }
+            }
+        }
+
+        /// <summary>
+        /// Deserializes bytes using legacy <c>BinaryFormatter</c>.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="data">Serialized bytes.</param>
+        /// <remarks>
+        /// Security: Never deserialize untrusted data with BinaryFormatter. It is obsolete and unsafe.
+        /// Portability: Fragile across versions/platforms; avoid for long‑lived data.
+        /// Prefer <see cref="JsonDeserialize{T}(string, System.Type, System.Text.Json.JsonSerializerOptions)"/> or <see cref="ProtoDeserialize{T}(byte[])"/> in production.
+        /// </remarks>
+        public static T BinaryDeserialize<T>(byte[] data)
+        {
+            using Utils.PooledResource<PooledReadOnlyMemoryStream> lease =
+                PooledReadOnlyMemoryStream.Rent(out PooledReadOnlyMemoryStream stream);
+            stream.SetBuffer(data);
+            using Utils.PooledResource<BinaryFormatter> fmtLease = BinaryFormatterPool.Get(
+                out BinaryFormatter binaryFormatter
+            );
+            return (T)binaryFormatter.Deserialize(stream);
+        }
+
+        /// <summary>
+        /// Serializes an object using legacy <c>BinaryFormatter</c>.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">Object to serialize.</param>
+        /// <returns>Serialized bytes.</returns>
+        /// <remarks>
+        /// Use for trusted, temporary data only. Not safe for untrusted input. Prefer JSON or protobuf.
+        /// </remarks>
+        public static byte[] BinarySerialize<T>(T input)
+        {
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            using Utils.PooledResource<BinaryFormatter> fmtLease = BinaryFormatterPool.Get(
+                out BinaryFormatter binaryFormatter
+            );
+            binaryFormatter.Serialize(stream, input);
+            byte[] buffer = null;
+            stream.ToArrayExact(ref buffer);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Serializes to a caller buffer using <c>BinaryFormatter</c>.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">Object to serialize.</param>
+        /// <param name="buffer">Destination buffer reference. Resized if necessary.</param>
+        /// <returns>Number of bytes written.</returns>
+        public static int BinarySerialize<T>(T input, ref byte[] buffer)
+        {
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            using Utils.PooledResource<BinaryFormatter> fmtLease = BinaryFormatterPool.Get(
+                out BinaryFormatter binaryFormatter
+            );
+            binaryFormatter.Serialize(stream, input);
+            return stream.ToArrayExact(ref buffer);
+        }
+
+        /// <summary>
+        /// Deserializes protobuf‑net bytes to <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="data">Encoded protobuf payload.</param>
+        /// <returns>The decoded instance.</returns>
+        /// <remarks>
+        /// Polymorphism and interfaces:
+        /// - If <typeparamref name="T"/> is an interface, abstract type, or <see cref="object"/>, deserialization
+        ///   requires a concrete root type. We resolve this by either using an abstract base that is marked with
+        ///   <c>[ProtoContract]</c> and <c>[ProtoInclude]</c> for all subtypes (e.g.,
+        ///   <c>AbstractRandom</c> in the random package) or by a previously registered mapping via
+        ///   <see cref="RegisterProtobufRoot{TDeclared, TRoot}()"/>. If no unique root is found, a
+        ///   <see cref="ProtoException"/> is thrown to avoid ambiguous heuristics.
+        ///
+        /// Examples
+        /// <code><![CDATA[
+        /// // 1) Using an abstract base with [ProtoInclude]s
+        /// [ProtoContract]
+        /// abstract class Message { }
+        /// [ProtoContract] class Ping : Message { [ProtoMember(1)] public int Id { get; set; } }
+        /// // Deserialize to the abstract base; protobuf-net resolves to Ping
+        /// Message m = Serializer.ProtoDeserialize<Message>(bytes);
+        ///
+        /// // 2) Using an interface by registering a root
+        /// interface IEvent { }
+        /// [ProtoContract] class PlayerJoined : IEvent { [ProtoMember(1)] public string Name { get; set; } }
+        /// Serializer.RegisterProtobufRoot<IEvent, PlayerJoined>();
+        /// IEvent evt = Serializer.ProtoDeserialize<IEvent>(bytes);
+        ///
+        /// // 3) Overload that specifies the concrete type explicitly
+        /// IEvent evt2 = Serializer.ProtoDeserialize<IEvent>(bytes, typeof(PlayerJoined));
+        /// ]]></code>
+        /// </remarks>
+        public static T ProtoDeserialize<T>(byte[] data)
+        {
+            if (data == null)
+            {
+                throw new ProtoException("No data provided for Protobuf deserialization.");
+            }
+            try
+            {
+                // Prefer zero-copy ROM/ROS overloads when available
+                if (ProtoDeserializeTypeFromROMFast != null)
+                {
+                    ReadOnlyMemory<byte> rom = new(data);
+                    Type declared = typeof(T);
+                    if (
+                        ShouldUseRuntimeTypeForProtobuf<T>(
+                            declared,
+                            default,
+                            forceRuntimeType: false
+                        )
+                    )
+                    {
+                        Type root = ResolveProtobufRootType(declared);
+                        if (root != null)
+                        {
+                            return (T)ProtoDeserializeTypeFromROMFast(root, rom);
+                        }
+
+                        throw new ProtoException(
+                            $"Unable to resolve a unique protobuf root for declared type {declared.FullName}. Register a root via RegisterProtobufRoot or annotate a shared abstract base with [ProtoInclude]s."
+                        );
+                    }
+
+                    return (T)ProtoDeserializeTypeFromROMFast(declared, rom);
+                }
+
+                if (ProtoDeserializeTypeFromROSFast != null)
+                {
+                    ReadOnlySequence<byte> ros = new(data);
+                    Type declared = typeof(T);
+                    if (
+                        ShouldUseRuntimeTypeForProtobuf<T>(
+                            declared,
+                            default,
+                            forceRuntimeType: false
+                        )
+                    )
+                    {
+                        Type root = ResolveProtobufRootType(declared);
+                        if (root != null)
+                        {
+                            return (T)ProtoDeserializeTypeFromROSFast(root, ros);
+                        }
+
+                        throw new ProtoException(
+                            $"Unable to resolve a unique protobuf root for declared type {declared.FullName}. Register a root via RegisterProtobufRoot or annotate a shared abstract base with [ProtoInclude]s."
+                        );
+                    }
+
+                    return (T)ProtoDeserializeTypeFromROSFast(declared, ros);
+                }
+
+                // For small payloads, allow protobuf-net to use MemoryStream's non-copy buffer access
+                if (data.Length <= ProtobufMemoryStreamThreshold)
+                {
+                    using MemoryStream ms = new(data, writable: false);
+                    Type declared = typeof(T);
+                    if (
+                        ShouldUseRuntimeTypeForProtobuf<T>(
+                            declared,
+                            default,
+                            forceRuntimeType: false
+                        )
+                    )
+                    {
+                        Type root = ResolveProtobufRootType(declared);
+                        if (root != null)
+                        {
+                            return (T)ProtoBuf.Serializer.Deserialize(root, ms);
+                        }
+
+                        throw new ProtoException(
+                            $"Unable to resolve a unique protobuf root for declared type {declared.FullName}. Register a root via RegisterProtobufRoot or annotate a shared abstract base with [ProtoInclude]s."
+                        );
+                    }
+
+                    return ProtoBuf.Serializer.Deserialize<T>(ms);
+                }
+
+                // For larger payloads, prefer pooled stream to avoid per-iteration allocations
+                using Utils.PooledResource<PooledReadOnlyMemoryStream> lease =
+                    PooledReadOnlyMemoryStream.Rent(out PooledReadOnlyMemoryStream stream);
+                stream.SetBuffer(data);
+
+                Type declaredLarge = typeof(T);
+                if (
+                    ShouldUseRuntimeTypeForProtobuf<T>(
+                        declaredLarge,
+                        default,
+                        forceRuntimeType: false
+                    )
+                )
+                {
+                    Type root = ResolveProtobufRootType(declaredLarge);
+                    if (root != null)
+                    {
+                        return (T)ProtoBuf.Serializer.Deserialize(root, stream);
+                    }
+
+                    throw new ProtoException(
+                        $"Unable to resolve a unique protobuf root for declared type {declaredLarge.FullName}. Register a root via RegisterProtobufRoot or annotate a shared abstract base with [ProtoInclude]s."
+                    );
+                }
+
+                return ProtoBuf.Serializer.Deserialize<T>(stream);
+            }
+            catch (ProtoException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                throw new ProtoException(
+                    "Protobuf deserialization failed: invalid or corrupted data.",
+                    ex
+                );
+            }
+        }
+
+        // Attempts to resolve a concrete root type for protobuf-net when the declared generic type
+        // is interface/abstract/object.
+        // Rules:
+        // - If a root is explicitly registered, use it.
+        // - If the declared type itself is an abstract [ProtoContract] (with [ProtoInclude]s), return the declared type
+        //   to allow protobuf-net to handle subtypes via includes.
+        // - Do not auto-pick implementations based on reflection heuristics; require registration instead to avoid
+        //   ambiguity and brittle ordering of loaded types.
+        private static Type ResolveProtobufRootType(Type declared)
+        {
+            if (declared == null)
+            {
+                return null;
+            }
+
+            // If declared is already a usable concrete type, just return it
+            if (!declared.IsInterface && !declared.IsAbstract && declared != typeof(object))
+            {
+                return declared;
+            }
+
+            // If declared itself is an abstract [ProtoContract] base with [ProtoInclude]s, prefer it
+            if (
+                declared.IsAbstract
+                && ReflectionHelpers.HasAttributeSafe<ProtoContractAttribute>(declared)
+            )
+            {
+                return declared;
+            }
+
+            if (ProtobufRootCache.TryGetValue(declared, out Type cached))
+            {
+                return cached == NoRootMarker ? null : cached;
+            }
+
+            // Try to resolve a unique abstract [ProtoContract] base that implements the declared interface.
+            // This allows scenarios like: IRandom -> AbstractRandom (annotated with [ProtoContract] + [ProtoInclude]).
+            // We deliberately keep the search local to the declaring assembly to avoid brittle cross-assembly heuristics.
+            if (declared.IsInterface && declared != typeof(object))
+            {
+                try
+                {
+                    Type[] types = ReflectionHelpers.GetTypesFromAssembly(declared.Assembly);
+                    Type[] candidates = types
+                        .Where(t =>
+                            t.IsClass
+                            && t.IsAbstract
+                            && declared.IsAssignableFrom(t)
+                            && ReflectionHelpers.HasAttributeSafe<ProtoContractAttribute>(t)
+                        )
+                        .ToArray();
+
+                    switch (candidates.Length)
+                    {
+                        case 1:
+                        {
+                            Type root = candidates[0];
+                            ProtobufRootCache[declared] = root;
+                            return root;
+                        }
+                        case > 1:
+                        {
+                            // Prefer a candidate that explicitly declares [ProtoInclude]s if this disambiguates
+                            Type[] includeCandidates = candidates
+                                .Where(t =>
+                                    ReflectionHelpers.HasAttributeSafe<ProtoIncludeAttribute>(t)
+                                )
+                                .ToArray();
+
+                            if (includeCandidates.Length == 1)
+                            {
+                                Type root = includeCandidates[0];
+                                ProtobufRootCache[declared] = root;
+                                return root;
+                            }
+
+                            break;
+                        }
+                    }
+                }
+                catch
+                {
+                    // Reflection may fail in some restricted environments; fall through to marker/null
+                }
+            }
+
+            ProtobufRootCache[declared] = NoRootMarker;
+            return null;
+        }
+
+        /// <summary>
+        /// Deserializes protobuf‑net bytes into the provided <paramref name="type"/>.
+        /// </summary>
+        /// <typeparam name="T">Expected return type after cast.</typeparam>
+        /// <param name="data">Encoded protobuf payload.</param>
+        /// <param name="type">Concrete type to deserialize to.</param>
+        /// <returns>The decoded instance cast to <typeparamref name="T"/>.</returns>
+        public static T ProtoDeserialize<T>(byte[] data, Type type)
+        {
+            if (data == null)
+            {
+                throw new ArgumentException(nameof(data));
+            }
+
+            if (type == null)
+            {
+                throw new ArgumentNullException(nameof(type));
+            }
+
+            try
+            {
+                // Prefer zero-copy ROM/ROS overloads when available
+                if (ProtoDeserializeTypeFromROMFast != null)
+                {
+                    ReadOnlyMemory<byte> rom = new(data);
+                    return (T)ProtoDeserializeTypeFromROMFast(type, rom);
+                }
+                if (ProtoDeserializeTypeFromROSFast != null)
+                {
+                    ReadOnlySequence<byte> ros = new(data);
+                    return (T)ProtoDeserializeTypeFromROSFast(type, ros);
+                }
+
+                if (data.Length <= ProtobufMemoryStreamThreshold)
+                {
+                    using MemoryStream ms = new(data, writable: false);
+                    return (T)ProtoBuf.Serializer.Deserialize(type, ms);
+                }
+
+                using Utils.PooledResource<PooledReadOnlyMemoryStream> lease =
+                    PooledReadOnlyMemoryStream.Rent(out PooledReadOnlyMemoryStream stream);
+                stream.SetBuffer(data);
+                return (T)ProtoBuf.Serializer.Deserialize(type, stream);
+            }
+            catch (ProtoException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                throw new ProtoException(
+                    "Protobuf deserialization failed: invalid or corrupted data.",
+                    ex
+                );
+            }
+        }
+
+        /// <summary>
+        /// Serializes an instance to protobuf‑net bytes.
+        /// </summary>
+        /// <typeparam name="T">Declared type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="forceRuntimeType">When true, always serialize as the runtime type; otherwise uses declared type unless it is interface/abstract/object.</param>
+        /// <returns>Serialized bytes.</returns>
+        /// <example>
+        /// <code>
+        /// [ProtoContract]
+        /// class NetworkMessage { [ProtoMember(1)] public int Id { get; set; } }
+        /// var bytes = Serializer.ProtoSerialize(new NetworkMessage { Id = 5 });
+        /// var msg = Serializer.ProtoDeserialize&lt;NetworkMessage&gt;(bytes);
+        /// </code>
+        /// </example>
+        public static byte[] ProtoSerialize<T>(T input, bool forceRuntimeType = false)
+        {
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            Type declared = typeof(T);
+            bool useRuntime = ShouldUseRuntimeTypeForProtobuf(declared, input, forceRuntimeType);
+
+            if (useRuntime)
+            {
+                ProtoBuf.Serializer.NonGeneric.Serialize(stream, input);
+            }
+            else
+            {
+                ProtoBuf.Serializer.Serialize(stream, input);
+            }
+
+            byte[] buffer = null;
+            stream.ToArrayExact(ref buffer);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Serializes an instance to protobuf‑net bytes into a caller-provided buffer.
+        /// </summary>
+        /// <typeparam name="T">Declared type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="buffer">Destination buffer reference. Resized if necessary.</param>
+        /// <param name="forceRuntimeType">When true, always serialize as the runtime type.</param>
+        /// <returns>Number of bytes written.</returns>
+        public static int ProtoSerialize<T>(
+            T input,
+            ref byte[] buffer,
+            bool forceRuntimeType = false
+        )
+        {
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            Type declared = typeof(T);
+            bool useRuntime = ShouldUseRuntimeTypeForProtobuf(declared, input, forceRuntimeType);
+
+            if (useRuntime)
+            {
+                ProtoBuf.Serializer.NonGeneric.Serialize(stream, input);
+            }
+            else
+            {
+                ProtoBuf.Serializer.Serialize(stream, input);
+            }
+            return stream.ToArrayExact(ref buffer);
+        }
+
+        /// <summary>
+        /// Deserializes JSON text to <typeparamref name="T"/> using Unity‑aware converters.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="data">JSON string.</param>
+        /// <param name="type">Optional concrete target type (defaults to <typeparamref name="T"/>).</param>
+        /// <param name="options">Serializer options; defaults include converters for Unity types and ReferenceHandler.IgnoreCycles.</param>
+        /// <returns>The decoded instance.</returns>
+        public static T JsonDeserialize<T>(
+            string data,
+            Type type = null,
+            JsonSerializerOptions options = null
+        )
+        {
+            return (T)
+                JsonSerializer.Deserialize(
+                    data,
+                    type ?? typeof(T),
+                    options ?? SerializerEncoding.NormalJsonOptions
+                );
+        }
+
+        /// <summary>
+        /// Deserializes JSON bytes (UTF-8) to <typeparamref name="T"/> using Unity-aware converters.
+        /// Avoids intermediate string allocation by using span-based System.Text.Json APIs.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="data">UTF-8 JSON bytes.</param>
+        /// <param name="type">Optional concrete target type (defaults to <typeparamref name="T"/>).</param>
+        /// <param name="options">Serializer options; defaults include Unity converters.</param>
+        /// <returns>The decoded instance.</returns>
+        public static T JsonDeserialize<T>(
+            byte[] data,
+            Type type = null,
+            JsonSerializerOptions options = null
+        )
+        {
+            if (data == null)
+            {
+                throw new ArgumentNullException(nameof(data));
+            }
+
+            ReadOnlySpan<byte> span = new(data);
+            return (T)
+                JsonSerializer.Deserialize(
+                    span,
+                    type ?? typeof(T),
+                    options ?? SerializerEncoding.NormalJsonOptions
+                );
+        }
+
+        /// <summary>
+        /// Fast-path JSON deserialize using strict, allocation-lean options.
+        /// </summary>
+        public static T JsonDeserializeFast<T>(byte[] data)
+        {
+            if (data == null)
+            {
+                throw new ArgumentNullException(nameof(data));
+            }
+            ReadOnlySpan<byte> span = new(data);
+            return JsonSerializer.Deserialize<T>(span, SerializerEncoding.FastJsonOptions);
+        }
+
+        /// <summary>
+        /// Serializes an instance to JSON bytes (UTF‑8) using Unity‑aware converters.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <returns>UTF‑8 JSON bytes.</returns>
+        public static byte[] JsonSerialize<T>(T input)
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, SerializerEncoding.NormalJsonOptions, bufferWriter);
+            byte[] buffer = null;
+            bufferWriter.ToArrayExact(ref buffer);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Serializes an instance to JSON bytes (UTF-8) using caller-provided options.
+        /// Tip: Reuse the same options instance across calls to benefit from metadata caches.
+        /// </summary>
+        public static byte[] JsonSerialize<T>(T input, JsonSerializerOptions options)
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, options ?? SerializerEncoding.NormalJsonOptions, bufferWriter);
+            byte[] buffer = null;
+            bufferWriter.ToArrayExact(ref buffer);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Serializes an instance to JSON bytes (UTF‑8) into a caller-provided buffer.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="buffer">Destination buffer reference. Resized if necessary.</param>
+        /// <returns>Number of bytes written.</returns>
+        public static int JsonSerialize<T>(T input, ref byte[] buffer)
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, SerializerEncoding.NormalJsonOptions, bufferWriter);
+            return bufferWriter.ToArrayExact(ref buffer);
+        }
+
+        /// <summary>
+        /// Serializes into a caller-provided buffer using caller options.
+        /// Reuses the provided buffer when large enough to avoid allocations; resizes if necessary.
+        /// </summary>
+        public static int JsonSerialize<T>(
+            T input,
+            JsonSerializerOptions options,
+            ref byte[] buffer
+        )
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, options ?? SerializerEncoding.NormalJsonOptions, bufferWriter);
+            return bufferWriter.ToArrayExact(ref buffer);
+        }
+
+        /// <summary>
+        /// Serializes into a caller-provided buffer using caller options and a size hint to reduce growth copies.
+        /// Provide an approximate size of the final payload to minimize buffer growth/copy churn for large outputs.
+        /// Example: for large int[] payloads, estimate (count * 12) + overhead.
+        /// </summary>
+        public static int JsonSerialize<T>(
+            T input,
+            JsonSerializerOptions options,
+            int sizeHint,
+            ref byte[] buffer
+        )
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            if (sizeHint > 0)
+            {
+                bufferWriter.Preallocate(sizeHint);
+            }
+            WriteJsonToBuffer(input, options ?? SerializerEncoding.NormalJsonOptions, bufferWriter);
+            return bufferWriter.ToArrayExact(ref buffer);
+        }
+
+        /// <summary>
+        /// Fast-path JSON serialize using strict, allocation-lean options.
+        /// </summary>
+        public static byte[] JsonSerializeFast<T>(T input)
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, SerializerEncoding.FastJsonOptions, bufferWriter);
+            byte[] buffer = null;
+            bufferWriter.ToArrayExact(ref buffer);
+            return buffer;
+        }
+
+        /// <summary>
+        /// Fast-path JSON serialize into a caller-provided buffer.
+        /// </summary>
+        public static int JsonSerializeFast<T>(T input, ref byte[] buffer)
+        {
+            using Utils.PooledResource<PooledArrayBufferWriter> lease =
+                PooledArrayBufferWriter.Rent(out PooledArrayBufferWriter bufferWriter);
+            WriteJsonToBuffer(input, SerializerEncoding.FastJsonOptions, bufferWriter);
+            return bufferWriter.ToArrayExact(ref buffer);
+        }
+
+        private static void WriteJsonToStream<T>(
+            T input,
+            JsonSerializerOptions options,
+            Stream stream
+        )
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+            if (stream == null)
+            {
+                throw new ArgumentNullException(nameof(stream));
+            }
+
+            using (JsonWriterPool.Get(out Utf8JsonWriter writer))
+            {
+                writer.Reset(stream);
+                Type parameterType = typeof(T);
+                if (
+                    parameterType.IsAbstract
+                    || parameterType.IsInterface
+                    || parameterType == typeof(object)
+                )
+                {
+                    object data = input;
+                    if (data == null)
+                    {
+                        writer.WriteStartObject();
+                        writer.WriteEndObject();
+                        writer.Flush();
+                        return;
+                    }
+
+                    Type type = data.GetType();
+                    JsonSerializer.Serialize(writer, data, type, options);
+                }
+                else
+                {
+                    JsonSerializer.Serialize(writer, input, options);
+                }
+                writer.Flush();
+            }
+        }
+
+        /// <summary>
+        /// Serializes an instance to a JSON string.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="pretty">Write indented output when true.</param>
+        /// <returns>JSON text.</returns>
+        /// <example>
+        /// <code>
+        /// var json = Serializer.JsonStringify(save, pretty: true);
+        /// var roundtrip = Serializer.JsonDeserialize&lt;SaveData&gt;(json);
+        /// </code>
+        /// </example>
+        public static string JsonStringify<T>(T input, bool pretty = false)
+        {
+            JsonSerializerOptions options = pretty
+                ? SerializerEncoding.PrettyJsonOptions
+                : SerializerEncoding.NormalJsonOptions;
+
+            return JsonStringify(input, options);
+        }
+
+        /// <summary>
+        /// Serializes an instance to a JSON string using the provided <paramref name="options"/>.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="options">Serializer options.</param>
+        /// <returns>JSON text.</returns>
+        public static string JsonStringify<T>(T input, JsonSerializerOptions options)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            Type parameterType = typeof(T);
+            if (
+                parameterType.IsAbstract
+                || parameterType.IsInterface
+                || parameterType == typeof(object)
+            )
+            {
+                object data = input;
+                if (data == null)
+                {
+                    return "{}";
+                }
+
+                Type type = data.GetType();
+                return JsonSerializer.Serialize(data, type, options);
+            }
+
+            return JsonSerializer.Serialize(input, options);
+        }
+
+        /// <summary>
+        /// Reads JSON text from a file (UTF‑8) and deserializes to <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="path">File path.</param>
+        /// <returns>Decoded instance.</returns>
+        public static T ReadFromJsonFile<T>(string path)
+        {
+            byte[] settingsAsBytes = File.ReadAllBytes(path);
+            return JsonDeserialize<T>(settingsAsBytes);
+        }
+
+        private static void WriteJsonToBuffer<T>(
+            T input,
+            JsonSerializerOptions options,
+            PooledArrayBufferWriter buffer
+        )
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+            if (buffer == null)
+            {
+                throw new ArgumentNullException(nameof(buffer));
+            }
+
+            using (
+                Utf8JsonWriter writer = new(buffer, new JsonWriterOptions { SkipValidation = true })
+            )
+            {
+                Type parameterType = typeof(T);
+                if (
+                    parameterType.IsAbstract
+                    || parameterType.IsInterface
+                    || parameterType == typeof(object)
+                )
+                {
+                    object data = input;
+                    if (data == null)
+                    {
+                        writer.WriteStartObject();
+                        writer.WriteEndObject();
+                        writer.Flush();
+                        return;
+                    }
+
+                    Type type = data.GetType();
+                    JsonSerializer.Serialize(writer, data, type, options);
+                }
+                else
+                {
+                    JsonSerializer.Serialize(writer, input, options);
+                }
+                writer.Flush();
+            }
+        }
+
+        /// <summary>
+        /// Asynchronously reads JSON text from a file (UTF‑8) and deserializes to <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">Target type.</typeparam>
+        /// <param name="path">File path.</param>
+        /// <returns>Decoded instance.</returns>
+        public static async Task<T> ReadFromJsonFileAsync<T>(string path)
+        {
+            byte[] settingsAsBytes = await File.ReadAllBytesAsync(path);
+            return JsonDeserialize<T>(settingsAsBytes);
+        }
+
+        /// <summary>
+        /// Asynchronously reads JSON with cancellation.
+        /// </summary>
+        public static async Task<T> ReadFromJsonFileAsync<T>(
+            string path,
+            System.Threading.CancellationToken cancellationToken
+        )
+        {
+            using FileStream fs = new(
+                path,
+                FileMode.Open,
+                FileAccess.Read,
+                FileShare.Read,
+                4096,
+                useAsync: true
+            );
+            using Utils.PooledResource<PooledBufferStream> lease = PooledBufferStream.Rent(
+                out PooledBufferStream stream
+            );
+            byte[] buffer = new byte[8192];
+            int read;
+            while ((read = await fs.ReadAsync(buffer, 0, buffer.Length, cancellationToken)) > 0)
+            {
+                stream.Write(buffer, 0, read);
+            }
+            ArraySegment<byte> seg = stream.GetWrittenSegment();
+            return JsonDeserialize<T>(seg.Array.AsSpan(0, seg.Count).ToArray());
+        }
+
+        /// <summary>
+        /// Writes an instance to a JSON file (UTF‑8).
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="path">Destination file path.</param>
+        /// <param name="pretty">Write indented output when true.</param>
+        public static void WriteToJsonFile<T>(T input, string path, bool pretty = true)
+        {
+            string jsonAsText = JsonStringify(input, pretty);
+            File.WriteAllText(path, jsonAsText);
+        }
+
+        /// <summary>
+        /// Asynchronously writes an instance to a JSON file (UTF‑8).
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="path">Destination file path.</param>
+        /// <param name="pretty">Write indented output when true.</param>
+        public static async Task WriteToJsonFileAsync<T>(T input, string path, bool pretty = true)
+        {
+            string jsonAsText = JsonStringify(input, pretty);
+            await File.WriteAllTextAsync(path, jsonAsText);
+        }
+
+        /// <summary>
+        /// Asynchronously writes an instance to a JSON file (UTF‑8) with cancellation.
+        /// </summary>
+        public static async Task WriteToJsonFileAsync<T>(
+            T input,
+            string path,
+            bool pretty,
+            System.Threading.CancellationToken cancellationToken
+        )
+        {
+            string jsonAsText = JsonStringify(input, pretty);
+            byte[] bytes = SerializerEncoding.Encoding.GetBytes(jsonAsText);
+            using FileStream fs = new(
+                path,
+                FileMode.Create,
+                FileAccess.Write,
+                FileShare.None,
+                4096,
+                useAsync: true
+            );
+            await fs.WriteAsync(bytes, 0, bytes.Length, cancellationToken);
+        }
+
+        /// <summary>
+        /// Writes an instance to a JSON file (UTF‑8) using the provided <paramref name="options"/>.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="path">Destination file path.</param>
+        /// <param name="options">Serializer options.</param>
+        public static void WriteToJsonFile<T>(T input, string path, JsonSerializerOptions options)
+        {
+            string jsonAsText = JsonStringify(input, options);
+            File.WriteAllText(path, jsonAsText);
+        }
+
+        /// <summary>
+        /// Asynchronously writes an instance to a JSON file (UTF‑8) using the provided <paramref name="options"/>.
+        /// </summary>
+        /// <typeparam name="T">Instance type.</typeparam>
+        /// <param name="input">The instance to serialize.</param>
+        /// <param name="path">Destination file path.</param>
+        /// <param name="options">Serializer options.</param>
+        public static async Task WriteToJsonFileAsync<T>(
+            T input,
+            string path,
+            JsonSerializerOptions options
+        )
+        {
+            string jsonAsText = JsonStringify(input, options);
+            await File.WriteAllTextAsync(path, jsonAsText);
+        }
+
+        /// <summary>
+        /// Attempts to read JSON into an instance, returns false if file missing or invalid.
+        /// </summary>
+        public static bool TryReadFromJsonFile<T>(string path, out T value)
+        {
+            try
+            {
+                if (!File.Exists(path))
+                {
+                    value = default;
+                    return false;
+                }
+                string json = File.ReadAllText(path);
+                value = JsonDeserialize<T>(json);
+                return true;
+            }
+            catch
+            {
+                value = default;
+                return false;
+            }
+        }
+
+        /// <summary>
+        /// Attempts to write JSON to a file, returns false on failure.
+        /// </summary>
+        public static bool TryWriteToJsonFile<T>(T input, string path, bool pretty = true)
+        {
+            try
+            {
+                WriteToJsonFile(input, path, pretty);
+                return true;
+            }
+            catch
+            {
+                return false;
+            }
+        }
+    }
+
+    // Internal pooled, growable write stream backed by ArrayPool<byte> to reduce allocations
+    internal sealed class PooledBufferStream : Stream
+    {
+        private const int DefaultInitialCapacity = 256;
+
+        private byte[] _buffer;
+        private int _length;
+        private int _position;
+        private bool _disposed;
+
+        private static readonly Utils.WallstopGenericPool<PooledBufferStream> Pool = new(
+            producer: () => new PooledBufferStream(),
+            onRelease: stream => stream.ResetForReuse(),
+            onDisposal: stream => stream.Dispose()
+        );
+
+        public static Utils.PooledResource<PooledBufferStream> Rent(
+            out PooledBufferStream stream
+        ) => Pool.Get(out stream);
+
+        private PooledBufferStream(int initialCapacity = DefaultInitialCapacity)
+        {
+            if (initialCapacity < 1)
+            {
+                initialCapacity = DefaultInitialCapacity;
+            }
+
+            _buffer = ArrayPool<byte>.Shared.Rent(initialCapacity);
+            _length = 0;
+            _position = 0;
+        }
+
+        internal ArraySegment<byte> GetWrittenSegment()
+        {
+            return new ArraySegment<byte>(_buffer, 0, _length);
+        }
+
+        private void ResetForReuse()
+        {
+            _length = 0;
+            _position = 0;
+            _disposed = false;
+        }
+
+        public override bool CanRead => false;
+        public override bool CanSeek => true;
+        public override bool CanWrite => true;
+        public override long Length => _length;
+
+        public override long Position
+        {
+            get => _position;
+            set => Seek(value, SeekOrigin.Begin);
+        }
+
+        public override void Flush() { }
+
+        public override int Read(byte[] buffer, int offset, int count)
+        {
+            throw new NotSupportedException();
+        }
+
+        public override long Seek(long offset, SeekOrigin origin)
+        {
+            int basePos = origin switch
+            {
+                SeekOrigin.Begin => 0,
+                SeekOrigin.Current => _position,
+                SeekOrigin.End => _length,
+                _ => 0,
+            };
+            long newPos = basePos + offset;
+            if (newPos is < 0 or > int.MaxValue)
+            {
+                throw new ArgumentOutOfRangeException(nameof(offset));
+            }
+            _position = (int)newPos;
+            return _position;
+        }
+
+        public override void SetLength(long value)
+        {
+            if (value is < 0 or > int.MaxValue)
+            {
+                throw new ArgumentOutOfRangeException(nameof(value));
+            }
+            int newLen = (int)value;
+            EnsureCapacity(newLen);
+            _length = newLen;
+            if (_position > _length)
+            {
+                _position = _length;
+            }
+        }
+
+        public override void Write(byte[] buffer, int offset, int count)
+        {
+            int endPos = _position + count;
+            EnsureCapacity(endPos);
+            Array.Copy(buffer, offset, _buffer, _position, count);
+            _position = endPos;
+            if (endPos > _length)
+            {
+                _length = endPos;
+            }
+        }
+
+        public override void WriteByte(byte value)
+        {
+            int endPos = _position + 1;
+            EnsureCapacity(endPos);
+            _buffer[_position] = value;
+            _position = endPos;
+            if (endPos > _length)
+            {
+                _length = endPos;
+            }
+        }
+
+        private void EnsureCapacity(int required)
+        {
+            if (_buffer.Length >= required)
+            {
+                return;
+            }
+
+            int newSize = _buffer.Length;
+            if (newSize < DefaultInitialCapacity)
+            {
+                newSize = DefaultInitialCapacity;
+            }
+
+            while (newSize < required)
+            {
+                newSize = newSize < 1024 ? newSize * 2 : newSize + (newSize >> 1);
+            }
+            byte[] newBuf = ArrayPool<byte>.Shared.Rent(newSize);
+            if (_length > 0)
+            {
+                Array.Copy(_buffer, newBuf, _length);
+            }
+            ArrayPool<byte>.Shared.Return(_buffer);
+            _buffer = newBuf;
+        }
+
+        protected override void Dispose(bool disposing)
+        {
+            if (!_disposed)
+            {
+                if (_buffer != null)
+                {
+                    ArrayPool<byte>.Shared.Return(_buffer);
+                    _buffer = Array.Empty<byte>();
+                }
+                _length = 0;
+                _position = 0;
+                _disposed = true;
+            }
+            base.Dispose(disposing);
+        }
+
+        public int ToArrayExact(ref byte[] buffer)
+        {
+            if (buffer == null || buffer.Length < _length)
+            {
+                buffer = new byte[_length];
+            }
+
+            if (_length > 0)
+            {
+                Array.Copy(_buffer, buffer, _length);
+            }
+
+            return _length;
+        }
+
+        public override void Write(ReadOnlySpan<byte> buffer)
+        {
+            int count = buffer.Length;
+            int endPos = _position + count;
+            EnsureCapacity(endPos);
+            buffer.CopyTo(new Span<byte>(_buffer, _position, count));
+            _position = endPos;
+            if (endPos > _length)
+            {
+                _length = endPos;
+            }
+        }
+
+        public override ValueTask WriteAsync(
+            ReadOnlyMemory<byte> source,
+            System.Threading.CancellationToken cancellationToken = default
+        )
+        {
+            // Delegate to synchronous span-based path; callers expect a fast in-memory stream
+            Write(source.Span);
+            return new ValueTask();
+        }
+    }
+
+    // Internal pooled ArrayBufferWriter-like implementation to enable zero-copy JSON writing via IBufferWriter<byte>
+    internal sealed class PooledArrayBufferWriter : IBufferWriter<byte>, IDisposable
+    {
+        private const int DefaultInitialCapacity = 256;
+        private byte[] _buffer;
+        private int _written;
+        private bool _disposed;
+
+        private static readonly Utils.WallstopGenericPool<PooledArrayBufferWriter> Pool = new(
+            producer: () => new PooledArrayBufferWriter(),
+            onRelease: w =>
+            {
+                w.Reset();
+            }
+        );
+
+        public static Utils.PooledResource<PooledArrayBufferWriter> Rent(
+            out PooledArrayBufferWriter writer
+        ) => Pool.Get(out writer);
+
+        private PooledArrayBufferWriter(int initialCapacity = DefaultInitialCapacity)
+        {
+            _buffer = ArrayPool<byte>.Shared.Rent(initialCapacity);
+            _written = 0;
+        }
+
+        private void EnsureCapacity(int sizeHint)
+        {
+            if (sizeHint <= 0)
+            {
+                sizeHint = 1;
+            }
+            int required = _written + sizeHint;
+            if (_buffer.Length >= required)
+            {
+                return;
+            }
+
+            int newSize = _buffer.Length;
+            while (newSize < required)
+            {
+                newSize = newSize < 1024 ? newSize * 2 : newSize + (newSize >> 1);
+            }
+
+            byte[] newBuf = ArrayPool<byte>.Shared.Rent(newSize);
+            if (_written > 0)
+            {
+                Buffer.BlockCopy(_buffer, 0, newBuf, 0, _written);
+            }
+            ArrayPool<byte>.Shared.Return(_buffer);
+            _buffer = newBuf;
+        }
+
+        public void Advance(int count)
+        {
+            _written += count;
+        }
+
+        public Memory<byte> GetMemory(int sizeHint = 0)
+        {
+            EnsureCapacity(sizeHint);
+            return _buffer.AsMemory(_written);
+        }
+
+        public Span<byte> GetSpan(int sizeHint = 0)
+        {
+            EnsureCapacity(sizeHint);
+            return _buffer.AsSpan(_written);
+        }
+
+        public int WrittenCount => _written;
+
+        public void Preallocate(int sizeHint)
+        {
+            EnsureCapacity(sizeHint);
+        }
+
+        public int ToArrayExact(ref byte[] buffer)
+        {
+            if (buffer == null || buffer.Length < _written)
+            {
+                buffer = new byte[_written];
+            }
+            if (_written > 0)
+            {
+                Buffer.BlockCopy(_buffer, 0, buffer, 0, _written);
+            }
+            return _written;
+        }
+
+        private void Reset()
+        {
+            // Keep the rented buffer to avoid churn; just reset write cursor.
+            if (_buffer == null || _buffer.Length == 0)
+            {
+                _buffer = ArrayPool<byte>.Shared.Rent(DefaultInitialCapacity);
+            }
+            _written = 0;
+            _disposed = false;
+        }
+
+        public void Dispose()
+        {
+            if (!_disposed)
+            {
+                if (_buffer != null)
+                {
+                    ArrayPool<byte>.Shared.Return(_buffer);
+                }
+                _buffer = Array.Empty<byte>();
+                _written = 0;
+                _disposed = true;
+            }
+        }
+    }
+
+    // Internal pooled read-only stream over an existing byte[] to avoid MemoryStream allocation in deserialization paths
+    internal sealed class PooledReadOnlyMemoryStream : Stream
+    {
+        private byte[] _buffer = Array.Empty<byte>();
+        private int _position;
+        private int _length;
+
+        private static readonly Utils.WallstopGenericPool<PooledReadOnlyMemoryStream> Pool = new(
+            producer: () => new PooledReadOnlyMemoryStream(),
+            onRelease: s =>
+            {
+                s.ResetForReuse();
+            }
+        );
+
+        public static Utils.PooledResource<PooledReadOnlyMemoryStream> Rent(
+            out PooledReadOnlyMemoryStream stream
+        ) => Pool.Get(out stream);
+
+        public void SetBuffer(byte[] buffer)
+        {
+            _buffer = buffer ?? Array.Empty<byte>();
+            _position = 0;
+            _length = _buffer.Length;
+        }
+
+        private void ResetForReuse()
+        {
+            SetBuffer(Array.Empty<byte>());
+        }
+
+        public override bool CanRead => true;
+        public override bool CanSeek => true;
+        public override bool CanWrite => false;
+        public override long Length => _length;
+
+        public override long Position
+        {
+            get => _position;
+            set
+            {
+                if (value is < 0 or > int.MaxValue)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value));
+                }
+                _position = (int)value;
+            }
+        }
+
+        public override void Flush() { }
+
+        public override int Read(byte[] buffer, int offset, int count)
+        {
+            if (buffer == null)
+            {
+                throw new ArgumentNullException(nameof(buffer));
+            }
+
+            if ((uint)offset > buffer.Length || (uint)count > buffer.Length - offset)
+            {
+                throw new ArgumentOutOfRangeException();
+            }
+            int remaining = _length - _position;
+            if (remaining <= 0)
+            {
+                return 0;
+            }
+            if (count > remaining)
+            {
+                count = remaining;
+            }
+
+            Array.Copy(_buffer, _position, buffer, offset, count);
+            _position += count;
+            return count;
+        }
+
+        // Span-based fast-path used by modern callers (e.g., protobuf-net)
+        public override int Read(Span<byte> destination)
+        {
+            int remaining = _length - _position;
+            if (remaining <= 0)
+            {
+                return 0;
+            }
+
+            int toCopy = destination.Length;
+            if (toCopy > remaining)
+            {
+                toCopy = remaining;
+            }
+
+            new ReadOnlySpan<byte>(_buffer, _position, toCopy).CopyTo(destination);
+            _position += toCopy;
+            return toCopy;
+        }
+
+        public override ValueTask<int> ReadAsync(
+            Memory<byte> destination,
+            System.Threading.CancellationToken cancellationToken = default
+        )
+        {
+            // Delegate to synchronous span-based path; this stream is purely in-memory
+            int read = Read(destination.Span);
+            return new ValueTask<int>(read);
+        }
+
+        public override int ReadByte()
+        {
+            if (_position >= _length)
+            {
+                return -1;
+            }
+
+            return _buffer[_position++];
+        }
+
+        public override long Seek(long offset, SeekOrigin origin)
+        {
+            int basePos = origin switch
+            {
+                SeekOrigin.Begin => 0,
+                SeekOrigin.Current => _position,
+                SeekOrigin.End => _length,
+                _ => 0,
+            };
+            long newPos = basePos + offset;
+            if (newPos is < 0 or > int.MaxValue)
+            {
+                throw new IOException("Attempted to seek outside the stream bounds.");
+            }
+            _position = (int)newPos;
+            return _position;
+        }
+
+        public override void SetLength(long value)
+        {
+            throw new NotSupportedException();
+        }
+
+        public override void Write(byte[] buffer, int offset, int count)
+        {
+            throw new NotSupportedException();
+        }
+
+        public override void WriteByte(byte value)
+        {
+            throw new NotSupportedException();
+        }
+    }
+}