Clean up for async creation

AGENTS.md

@@ -179,3 +179,58 @@ SharpCompress supports multiple archive and compression formats:
 3. **Stream disposal** - Always set `LeaveStreamOpen` explicitly when needed (default is to close)
 4. **Tar + non-seekable stream** - Must provide file size or it will throw
 6. **Format detection** - Use `ReaderFactory.Open()` for auto-detection, test with actual archive files
+
+### Async Struct-Copy Bug in LZMA RangeCoder
+
+When implementing async methods on mutable `struct` types (like `BitEncoder` and `BitDecoder` in the LZMA RangeCoder), be aware that the async state machine copies the struct when `await` is encountered. This means mutations to struct fields after the `await` point may not persist back to the original struct stored in arrays or fields.
+
+**The Bug:**
+```csharp
+// BAD: async method on mutable struct
+public async ValueTask<uint> DecodeAsync(Decoder decoder, CancellationToken cancellationToken = default)
+{
+    var newBound = (decoder._range >> K_NUM_BIT_MODEL_TOTAL_BITS) * _prob;
+    if (decoder._code < newBound)
+    {
+        decoder._range = newBound;
+        _prob += (K_BIT_MODEL_TOTAL - _prob) >> K_NUM_MOVE_BITS;  // Mutates _prob
+        await decoder.Normalize2Async(cancellationToken).ConfigureAwait(false);  // Struct gets copied here
+        return 0;  // Original _prob update may be lost
+    }
+    // ...
+}
+```
+
+**The Fix:**
+Refactor async methods on mutable structs to perform all struct mutations synchronously before any `await`, or use a helper method to separate the await from the struct mutation:
+
+```csharp
+// GOOD: struct mutations happen synchronously, await is conditional
+public ValueTask<uint> DecodeAsync(Decoder decoder, CancellationToken cancellationToken = default)
+{
+    var newBound = (decoder._range >> K_NUM_BIT_MODEL_TOTAL_BITS) * _prob;
+    if (decoder._code < newBound)
+    {
+        decoder._range = newBound;
+        _prob += (K_BIT_MODEL_TOTAL - _prob) >> K_NUM_MOVE_BITS;  // All mutations complete
+        return DecodeAsyncHelper(decoder.Normalize2Async(cancellationToken), 0);  // Await in helper
+    }
+    decoder._range -= newBound;
+    decoder._code -= newBound;
+    _prob -= (_prob) >> K_NUM_MOVE_BITS;  // All mutations complete
+    return DecodeAsyncHelper(decoder.Normalize2Async(cancellationToken), 1);  // Await in helper
+}
+
+private static async ValueTask<uint> DecodeAsyncHelper(ValueTask normalizeTask, uint result)
+{
+    await normalizeTask.ConfigureAwait(false);
+    return result;
+}
+```
+
+**Why This Matters:**
+In LZMA, the `BitEncoder` and `BitDecoder` structs maintain adaptive probability models in their `_prob` field. When these structs are stored in arrays (e.g., `_models[m]`), the async state machine copy breaks the adaptive model, causing incorrect bit decoding and eventually `DataErrorException` exceptions.
+
+**Related Files:**
+- `src/SharpCompress/Compressors/LZMA/RangeCoder/RangeCoderBit.Async.cs` - Fixed
+- `src/SharpCompress/Compressors/LZMA/RangeCoder/RangeCoderBitTree.Async.cs` - Uses readonly structs, so this pattern doesn't apply

Directory.Packages.props

@@ -12,7 +12,7 @@
     <PackageVersion Include="System.Text.Encoding.CodePages" Version="10.0.0" />
     <PackageVersion Include="System.Buffers" Version="4.6.1" />
     <PackageVersion Include="System.Memory" Version="4.6.3" />
-    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.v3" Version="3.2.1" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
     <GlobalPackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <GlobalPackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.3" />

src/SharpCompress/Archives/AbstractArchive.Async.cs

@@ -0,0 +1,103 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using SharpCompress.Common;
+using SharpCompress.Readers;
+
+namespace SharpCompress.Archives;
+
+public abstract partial class AbstractArchive<TEntry, TVolume>
+    where TEntry : IArchiveEntry
+    where TVolume : IVolume
+{
+    #region Async Support
+
+    // Async properties
+    public virtual IAsyncEnumerable<TEntry> EntriesAsync => _lazyEntriesAsync;
+
+    public IAsyncEnumerable<TVolume> VolumesAsync => _lazyVolumesAsync;
+
+    protected virtual async IAsyncEnumerable<TEntry> LoadEntriesAsync(
+        IAsyncEnumerable<TVolume> volumes
+    )
+    {
+        foreach (var item in LoadEntries(await volumes.ToListAsync()))
+        {
+            yield return item;
+        }
+    }
+
+    public virtual async ValueTask DisposeAsync()
+    {
+        if (!_disposed)
+        {
+            await foreach (var v in _lazyVolumesAsync)
+            {
+                v.Dispose();
+            }
+            foreach (var v in _lazyEntriesAsync.GetLoaded().Cast<Entry>())
+            {
+                v.Close();
+            }
+            _sourceStream?.Dispose();
+
+            _disposed = true;
+        }
+    }
+
+    private async ValueTask EnsureEntriesLoadedAsync()
+    {
+        await _lazyEntriesAsync.EnsureFullyLoaded();
+        await _lazyVolumesAsync.EnsureFullyLoaded();
+    }
+
+    private async IAsyncEnumerable<IArchiveEntry> EntriesAsyncCast()
+    {
+        await foreach (var entry in EntriesAsync)
+        {
+            yield return entry;
+        }
+    }
+
+    IAsyncEnumerable<IArchiveEntry> IAsyncArchive.EntriesAsync => EntriesAsyncCast();
+
+    IAsyncEnumerable<IVolume> IAsyncArchive.VolumesAsync => VolumesAsyncCast();
+
+    private async IAsyncEnumerable<IVolume> VolumesAsyncCast()
+    {
+        await foreach (var volume in _lazyVolumesAsync)
+        {
+            yield return volume;
+        }
+    }
+
+    public async ValueTask<IAsyncReader> ExtractAllEntriesAsync()
+    {
+        if (!await IsSolidAsync() && Type != ArchiveType.SevenZip)
+        {
+            throw new SharpCompressException(
+                "ExtractAllEntries can only be used on solid archives or 7Zip archives (which require random access)."
+            );
+        }
+        await EnsureEntriesLoadedAsync();
+        return await CreateReaderForSolidExtractionAsync();
+    }
+
+    public virtual ValueTask<bool> IsSolidAsync() => new(false);
+
+    public async ValueTask<bool> IsCompleteAsync()
+    {
+        await EnsureEntriesLoadedAsync();
+        return await EntriesAsync.AllAsync(x => x.IsComplete);
+    }
+
+    public async ValueTask<long> TotalSizeAsync() =>
+        await EntriesAsync.AggregateAsync(0L, (total, cf) => total + cf.CompressedSize);
+
+    public async ValueTask<long> TotalUncompressedSizeAsync() =>
+        await EntriesAsync.AggregateAsync(0L, (total, cf) => total + cf.Size);
+
+    public ValueTask<bool> IsEncryptedAsync() => new(IsEncrypted);
+
+    #endregion
+}

src/SharpCompress/Archives/AbstractArchive.cs

@@ -7,7 +7,7 @@
 
 namespace SharpCompress.Archives;
 
-public abstract class AbstractArchive<TEntry, TVolume> : IArchive, IAsyncArchive
+public abstract partial class AbstractArchive<TEntry, TVolume> : IArchive, IAsyncArchive
     where TEntry : IArchiveEntry
     where TVolume : IVolume
 {
@@ -16,6 +16,10 @@ public abstract class AbstractArchive<TEntry, TVolume> : IArchive, IAsyncArchive
     private bool _disposed;
     private readonly SourceStream? _sourceStream;
 
+    // Async fields - kept in original file per refactoring rules
+    private readonly LazyAsyncReadOnlyCollection<TVolume> _lazyVolumesAsync;
+    private readonly LazyAsyncReadOnlyCollection<TEntry> _lazyEntriesAsync;
+
     protected ReaderOptions ReaderOptions { get; }
 
     internal AbstractArchive(ArchiveType type, SourceStream sourceStream)
@@ -77,16 +81,6 @@ internal AbstractArchive(ArchiveType type)
     protected virtual IAsyncEnumerable<TVolume> LoadVolumesAsync(SourceStream sourceStream) =>
         LoadVolumes(sourceStream).ToAsyncEnumerable();
 
-    protected virtual async IAsyncEnumerable<TEntry> LoadEntriesAsync(
-        IAsyncEnumerable<TVolume> volumes
-    )
-    {
-        foreach (var item in LoadEntries(await volumes.ToListAsync()))
-        {
-            yield return item;
-        }
-    }
-
     IEnumerable<IArchiveEntry> IArchive.Entries => Entries.Cast<IArchiveEntry>();
 
     IEnumerable<IVolume> IArchive.Volumes => _lazyVolumes.Cast<IVolume>();
@@ -156,85 +150,4 @@ public bool IsComplete
             return Entries.All(x => x.IsComplete);
         }
     }
-
-    #region Async Support
-
-    private readonly LazyAsyncReadOnlyCollection<TVolume> _lazyVolumesAsync;
-    private readonly LazyAsyncReadOnlyCollection<TEntry> _lazyEntriesAsync;
-
-    public virtual async ValueTask DisposeAsync()
-    {
-        if (!_disposed)
-        {
-            await foreach (var v in _lazyVolumesAsync)
-            {
-                v.Dispose();
-            }
-            foreach (var v in _lazyEntriesAsync.GetLoaded().Cast<Entry>())
-            {
-                v.Close();
-            }
-            _sourceStream?.Dispose();
-
-            _disposed = true;
-        }
-    }
-
-    private async ValueTask EnsureEntriesLoadedAsync()
-    {
-        await _lazyEntriesAsync.EnsureFullyLoaded();
-        await _lazyVolumesAsync.EnsureFullyLoaded();
-    }
-
-    public virtual IAsyncEnumerable<TEntry> EntriesAsync => _lazyEntriesAsync;
-
-    private async IAsyncEnumerable<IArchiveEntry> EntriesAsyncCast()
-    {
-        await foreach (var entry in EntriesAsync)
-        {
-            yield return entry;
-        }
-    }
-
-    IAsyncEnumerable<IArchiveEntry> IAsyncArchive.EntriesAsync => EntriesAsyncCast();
-
-    private async IAsyncEnumerable<IVolume> VolumesAsyncCast()
-    {
-        await foreach (var volume in VolumesAsync)
-        {
-            yield return volume;
-        }
-    }
-
-    public IAsyncEnumerable<IVolume> VolumesAsync => VolumesAsyncCast();
-
-    public async ValueTask<IAsyncReader> ExtractAllEntriesAsync()
-    {
-        if (!IsSolid && Type != ArchiveType.SevenZip)
-        {
-            throw new SharpCompressException(
-                "ExtractAllEntries can only be used on solid archives or 7Zip archives (which require random access)."
-            );
-        }
-        await EnsureEntriesLoadedAsync();
-        return await CreateReaderForSolidExtractionAsync();
-    }
-
-    public virtual ValueTask<bool> IsSolidAsync() => new(false);
-
-    public async ValueTask<bool> IsCompleteAsync()
-    {
-        await EnsureEntriesLoadedAsync();
-        return await EntriesAsync.AllAsync(x => x.IsComplete);
-    }
-
-    public async ValueTask<long> TotalSizeAsync() =>
-        await EntriesAsync.AggregateAsync(0L, (total, cf) => total + cf.CompressedSize);
-
-    public async ValueTask<long> TotalUncompressedSizeAsync() =>
-        await EntriesAsync.AggregateAsync(0L, (total, cf) => total + cf.Size);
-
-    public ValueTask<bool> IsEncryptedAsync() => new(IsEncrypted);
-
-    #endregion
 }