feat(aot): implement Source Generator architecture foundation for Native AOT compatibility

- Add conditional compilation strategy for multi-framework support
- Implement IAwsAccessor interface for type-safe AWS SDK private member access
- Create AwsAccessorRegistry for thread-safe accessor lookup in .NET 8+ builds
- Add SessionReflectionModern using UnsafeAccessor pattern (zero reflection)
- Preserve SessionReflectionLegacy for .NET Framework/Standard 2.0 compatibility
- Refactor SessionReflection as platform-specific facade with conditional compilation
- Enable AOT analyzers (EnableTrimAnalyzer, EnableSingleFileAnalyzer, EnableAotAnalyzer) for .NET 8+ targets
- Add proof-of-concept AmazonS3ClientAccessor demonstrating generated accessor pattern
- Configure projects for IsAotCompatible=true to enforce IL warning detection

Architecture supports:
- Legacy frameworks: netstandard2.0, net472 (traditional reflection)
- Modern frameworks: net8.0, net9.0 (UnsafeAccessor + Source Generator)
- Zero reflection API usage in AOT builds
- Fail-fast behavior when AWS SDK internal contracts change
- Automatic accessor registration via ModuleInitializer pattern

Ready for Source Generator implementation phase.

BREAKING CHANGE: SessionReflection implementation now varies by target framework.
Type-based overloads will be deprecated in future versions for .NET 8+ targets.

Author: Blind-Striker

src/LocalStack.Client/Generated/AmazonS3ClientAccessor.cs

@@ -0,0 +1,69 @@
+#if NET8_0_OR_GREATER
+using System.Runtime.CompilerServices;
+using Amazon.S3;
+
+namespace LocalStack.Client.Generated;
+
+/// <summary>
+/// Generated accessor for Amazon S3 Client using UnsafeAccessor pattern.
+/// This is a proof-of-concept implementation that would be generated by the Source Generator.
+/// </summary>
+[System.Diagnostics.CodeAnalysis.DynamicDependency("serviceMetadata", typeof(AmazonS3Client))]
+internal sealed class AmazonS3ClientAccessor : IAwsAccessor
+{
+    [UnsafeAccessor(UnsafeAccessorKind.StaticField, Name = "serviceMetadata")]
+    private static extern ref IServiceMetadata GetServiceMetadataField(AmazonS3Client? instance);
+
+    [UnsafeAccessor(UnsafeAccessorKind.Constructor)]
+    private static extern AmazonS3Config CreateS3Config();
+
+    // Note: We may need to access private fields in AmazonS3Config for region setting
+    // This depends on AWS SDK internal structure - will be discovered by the generator
+    public IServiceMetadata GetServiceMetadata()
+    {
+        return GetServiceMetadataField(null);
+    }
+
+    public ClientConfig CreateClientConfig()
+    {
+        return CreateS3Config();
+    }
+
+    public void SetRegion(ClientConfig clientConfig, RegionEndpoint regionEndpoint)
+    {
+        if (clientConfig is AmazonS3Config s3Config)
+        {
+            // Use public API if available, otherwise UnsafeAccessor would be generated
+            s3Config.RegionEndpoint = regionEndpoint;
+        }
+        else
+        {
+            throw new ArgumentException($"Expected AmazonS3Config, got {clientConfig.GetType().Name}", nameof(clientConfig));
+        }
+    }
+
+    public bool TrySetForcePathStyle(ClientConfig clientConfig, bool value)
+    {
+        if (clientConfig is AmazonS3Config s3Config)
+        {
+            s3Config.ForcePathStyle = value;
+            return true;
+        }
+        
+        return false;
+    }
+}
+
+/// <summary>
+/// Module initializer to register the S3 accessor.
+/// This would be generated automatically by the Source Generator.
+/// </summary>
+internal static class S3AccessorInitializer
+{
+    [ModuleInitializer]
+    internal static void RegisterS3Accessor()
+    {
+        AwsAccessorRegistry.Register<AmazonS3Client>(new AmazonS3ClientAccessor());
+    }
+}
+#endif

src/LocalStack.Client/LocalStack.Client.csproj

@@ -25,6 +25,13 @@
 		<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
 	</PropertyGroup>
 
+	<PropertyGroup Condition="'$(TargetFramework)' == 'net8.0' OR '$(TargetFramework)' == 'net9.0'">
+		<IsAotCompatible>true</IsAotCompatible>
+		<EnableTrimAnalyzer>true</EnableTrimAnalyzer>
+		<EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
+		<EnableAotAnalyzer>true</EnableAotAnalyzer>
+	</PropertyGroup>
+
 	<ItemGroup>
 		<PackageReference Include="AWSSDK.Core" />
 		<PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All" />
@@ -51,8 +58,4 @@
 		<None Include="../../assets/localstack-dotnet-square.png" Pack="true" PackagePath="" />
 	</ItemGroup>
 
-	<PropertyGroup Condition="'$(TargetFramework)' == 'net472'">
-		<DefineConstants>NET472</DefineConstants>
-	</PropertyGroup>
-
 </Project>

src/LocalStack.Client/Utils/AwsAccessorRegistry.cs

@@ -0,0 +1,63 @@
+using System.Collections.Concurrent;
+
+namespace LocalStack.Client.Utils;
+
+/// <summary>
+/// Thread-safe registry for AWS client accessors.
+/// Populated by generated ModuleInitializer methods for .NET 8+ builds.
+/// </summary>
+public static class AwsAccessorRegistry
+{
+    private static readonly ConcurrentDictionary<Type, IAwsAccessor> _accessors = new();
+
+    /// <summary>
+    /// Registers an accessor for a specific AWS client type.
+    /// Called by generated ModuleInitializer methods.
+    /// </summary>
+    public static void Register<TClient>(IAwsAccessor accessor) where TClient : AmazonServiceClient
+    {
+        _accessors.TryAdd(typeof(TClient), accessor);
+    }
+
+    /// <summary>
+    /// Gets the registered accessor for the specified AWS client type.
+    /// Throws NotSupportedException if no accessor is registered.
+    /// </summary>
+    public static IAwsAccessor Get(Type clientType)
+    {
+        if (clientType == null)
+        {
+            throw new ArgumentNullException(nameof(clientType));
+        }
+
+        if (_accessors.TryGetValue(clientType, out var accessor))
+        {
+            return accessor;
+        }
+
+        throw new NotSupportedException(
+            $"No AWS accessor registered for client type '{clientType.FullName}'. " +
+            "Ensure the AWS SDK package is referenced and the project targets .NET 8 or later for AOT compatibility.");
+    }
+
+    /// <summary>
+    /// Attempts to get the registered accessor for the specified AWS client type.
+    /// Returns true if found, false otherwise.
+    /// </summary>
+    public static bool TryGet(Type clientType, out IAwsAccessor? accessor)
+    {
+        return _accessors.TryGetValue(clientType, out accessor);
+    }
+
+    /// <summary>
+    /// Gets the number of registered accessors.
+    /// Used for diagnostics and testing.
+    /// </summary>
+    public static int Count => _accessors.Count;
+
+    /// <summary>
+    /// Gets all registered client types.
+    /// Used for diagnostics and testing.
+    /// </summary>
+    public static IEnumerable<Type> RegisteredClientTypes => _accessors.Keys;
+}

src/LocalStack.Client/Utils/IAwsAccessor.cs

@@ -0,0 +1,32 @@
+namespace LocalStack.Client.Utils;
+
+/// <summary>
+/// Interface for type-safe AWS SDK private member access.
+/// Implementations are generated at compile-time for .NET 8+ or use reflection for legacy frameworks.
+/// </summary>
+public interface IAwsAccessor
+{
+    /// <summary>
+    /// Gets the service metadata for the AWS client.
+    /// Accesses the private static 'serviceMetadata' field.
+    /// </summary>
+    IServiceMetadata GetServiceMetadata();
+
+    /// <summary>
+    /// Creates a new ClientConfig instance for the AWS client.
+    /// Uses the appropriate constructor for the client's configuration type.
+    /// </summary>
+    ClientConfig CreateClientConfig();
+
+    /// <summary>
+    /// Sets the region endpoint on the client configuration.
+    /// Accesses private fields/properties for region configuration.
+    /// </summary>
+    void SetRegion(ClientConfig clientConfig, RegionEndpoint regionEndpoint);
+
+    /// <summary>
+    /// Attempts to set the ForcePathStyle property on the client configuration.
+    /// Returns true if the property exists and was set, false otherwise.
+    /// </summary>
+    bool TrySetForcePathStyle(ClientConfig clientConfig, bool value);
+}

src/LocalStack.Client/Utils/SessionReflection.cs

@@ -1,102 +1,45 @@
-#pragma warning disable S3011 // We need to use reflection to access private fields for service metadata
-namespace LocalStack.Client.Utils;
+namespace LocalStack.Client.Utils;
 
+/// <summary>
+/// Platform-specific SessionReflection facade that chooses the appropriate implementation
+/// based on the target framework. Uses modern UnsafeAccessor pattern for .NET 8+ 
+/// and traditional reflection for legacy frameworks.
+/// </summary>
 public class SessionReflection : ISessionReflection
 {
+#if NET8_0_OR_GREATER
+    private static readonly ISessionReflection _implementation = new SessionReflectionModern();
+#else
+    private static readonly ISessionReflection _implementation = new SessionReflectionLegacy();
+#endif
+
     public IServiceMetadata ExtractServiceMetadata<TClient>() where TClient : AmazonServiceClient
     {
-        Type clientType = typeof(TClient);
-
-        return ExtractServiceMetadata(clientType);
+        return _implementation.ExtractServiceMetadata<TClient>();
     }
 
     public IServiceMetadata ExtractServiceMetadata(Type clientType)
     {
-        if (clientType == null)
-        {
-            throw new ArgumentNullException(nameof(clientType));
-        }
-
-        FieldInfo serviceMetadataField = clientType.GetField("serviceMetadata", BindingFlags.Static | BindingFlags.NonPublic) ??
-                                         throw new InvalidOperationException($"Invalid service type {clientType}");
-
-        #pragma warning disable CS8600,CS8603 // Not possible to get null value from this private field
-        var serviceMetadata = (IServiceMetadata)serviceMetadataField.GetValue(null);
-
-        return serviceMetadata;
+        return _implementation.ExtractServiceMetadata(clientType);
     }
 
     public ClientConfig CreateClientConfig<TClient>() where TClient : AmazonServiceClient
     {
-        Type clientType = typeof(TClient);
-
-        return CreateClientConfig(clientType);
+        return _implementation.CreateClientConfig<TClient>();
     }
 
     public ClientConfig CreateClientConfig(Type clientType)
     {
-        if (clientType == null)
-        {
-            throw new ArgumentNullException(nameof(clientType));
-        }
-
-        ConstructorInfo clientConstructorInfo = FindConstructorWithCredentialsAndClientConfig(clientType);
-        ParameterInfo clientConfigParam = clientConstructorInfo.GetParameters()[1];
-
-        return (ClientConfig)Activator.CreateInstance(clientConfigParam.ParameterType);
+        return _implementation.CreateClientConfig(clientType);
     }
 
     public void SetClientRegion(AmazonServiceClient amazonServiceClient, string systemName)
     {
-        if (amazonServiceClient == null)
-        {
-            throw new ArgumentNullException(nameof(amazonServiceClient));
-        }
-
-        PropertyInfo? regionEndpointProperty = amazonServiceClient.Config.GetType()
-                                                                  .GetProperty(nameof(amazonServiceClient.Config.RegionEndpoint),
-                                                                               BindingFlags.Public | BindingFlags.Instance);
-        regionEndpointProperty?.SetValue(amazonServiceClient.Config, RegionEndpoint.GetBySystemName(systemName));
+        _implementation.SetClientRegion(amazonServiceClient, systemName);
     }
 
     public bool SetForcePathStyle(ClientConfig clientConfig, bool value = true)
     {
-        if (clientConfig == null)
-        {
-            throw new ArgumentNullException(nameof(clientConfig));
-        }
-
-        PropertyInfo? forcePathStyleProperty = clientConfig.GetType().GetProperty("ForcePathStyle", BindingFlags.Public | BindingFlags.Instance);
-
-        if (forcePathStyleProperty == null)
-        {
-            return false;
-        }
-
-        forcePathStyleProperty.SetValue(clientConfig, value);
-
-        return true;
-    }
-
-    private static ConstructorInfo FindConstructorWithCredentialsAndClientConfig(Type clientType)
-    {
-        return clientType.GetConstructors(BindingFlags.Instance | BindingFlags.Public)
-                         .Single(info =>
-                         {
-                             ParameterInfo[] parameterInfos = info.GetParameters();
-
-                             if (parameterInfos.Length != 2)
-                             {
-                                 return false;
-                             }
-
-                             ParameterInfo credentialsParameter = parameterInfos[0];
-                             ParameterInfo clientConfigParameter = parameterInfos[1];
-
-                             return credentialsParameter.Name == "credentials" &&
-                                    credentialsParameter.ParameterType == typeof(AWSCredentials) &&
-                                    clientConfigParameter.Name == "clientConfig" &&
-                                    clientConfigParameter.ParameterType.IsSubclassOf(typeof(ClientConfig));
-                         });
+        return _implementation.SetForcePathStyle(clientConfig, value);
     }
 }