[matt-edmondson]

Requested by Matt · project thread

One commit per issue (or per tight cluster), each with a regression test.

Persistence (FileSystem, Temp, ConfigHome, DataHome, InMemory)

FileSystem and Temp were two copies of the same code, so they now share Shared/FileRecordStore.cs (replacing PersistenceDefaults.cs). ConfigHome and DataHome now forward RetrieveOrCreateAsync to it instead of using the interface's check-then-store default.

• Fixes RetrieveOrCreateAsync overwrites a stored file it cannot parse with new T(), destroying the user's data #82: a record that is there but can't be parsed throws PersistenceProviderException instead of reading as missing, so RetrieveOrCreateAsync never writes a default over it. Behaviour change: RetrieveAsync of a malformed record now throws rather than returning null.
• Fixes Cancelling a FileSystem/Temp/ConfigHome/DataHome persistence call mid-operation throws PersistenceProviderException instead of OperationCanceledException #121: cancellation part way through surfaces as OperationCanceledException.
• Fixes FileSystem/Temp RetrieveAsync throws PersistenceProviderException instead of returning null when a concurrent RemoveAsync deletes the key #123: a remove landing between a reader's existence check and its read reports the key missing.
• Fixes FileSystem/Temp RemoveAsync, ClearAsync and StoreAsync(key, null) fail on Windows while another task reads or replaces the same key, because deletes have no sharing-violation retry #143: deletes retry the sharing violation a reader or replace raises.
• Fixes RetrieveOrCreateAsync can overwrite a record a concurrent StoreAsync just wrote with new T() (check-then-store race) #144: RetrieveOrCreateAsync publishes its new instance only if nothing appeared meanwhile. The new race test caught that .NET's non-overwriting File.Move is check-then-rename on Unix (measured: 4 lost writes in 3000), so AtomicFile.TryCreateAsync opens with FileMode.CreateNew instead, and readers wait briefly on an empty file. Off Windows, .NET's emulated FileShare.None refusal carries a raw EWOULDBLOCK (11 / 35) as its HResult, which now counts as a sharing violation. InMemory gets an atomic GetOrAdd-based version.
• Fixes Staging files left by an interrupted StoreAsync (<guid>.tmp holding a full record) are never cleaned up, and ClearAsync leaves them behind #145: ClearAsync removes <guid>.tmp staging files older than a minute (younger ones belong to writes in flight).
• TempPersistenceProvider gains a public BaseDirectory, like FileSystem's.

Cache

• Fixes InMemoryCacheProvider measures TTLs against the wall clock, so a system clock step makes entries outlive their TTL or expire early #162: lifetimes measured on Stopwatch timestamps, not DateTime.UtcNow. An internal clock constructor lets tests move time instead of sleeping.
• Fixes InMemoryCacheProvider never evicts expired entries unless that exact key is read again, so short-TTL caches grow without bound #79: sets sweep expired entries, at most once a second or once as many sets as the cache holds, so the cost stays amortised.
• Fixes InMemoryCacheProvider.GetOrAdd overwrites a concurrently Set value, and racing callers get an instance that isn't the cached one #85: GetOrAdd is declared on the provider and adds only if nothing live is cached; racing callers get the cached instance.

Smaller fixes

• Fixes UserDirectories honours drive-relative XDG_*_HOME values on Windows (\cfg, C:cfg) because it checks Path.IsPathRooted #139: UserDirectories uses Path.IsPathFullyQualified, so \cfg and C:cfg fall back to the defaults.
• Fixes Base64EncodingProvider.TryDecode accepts line-wrapped input on net8+ but rejects it on net6/net7/netstandard2.1 #140: Base64 skips ASCII whitespace on every target, not only net8+.
• Fixes TriangularDistributionProvider returns Infinity/NaN for wide finite bounds: Triangular(-1e308, 0, 1e308) has Mean = Infinity and every Sample = -Infinity #142: the triangular distribution works at half scale when max - min overflows, and its CDF is a product of ratios so wide-but-finite ranges no longer overflow the squares.
• Fixes Persistence keys COM¹–COM³, LPT¹–LPT³, COM0 and LPT0 aren't escaped, so on Windows they resolve to device names instead of files #146: COM0, LPT0 and the superscript COM¹²³ / LPT¹²³ are escaped.
• Fixes Registering a category's default provider before AddEssentials() makes the interface resolve to a different provider (JSON→TOML, Crypto→PCG, Gzip→ZLib, …) #149: the six category defaults in AddEssentials() go through AddDefaultOrKeep, so registering one first (including JSON with options) keeps it the default.
• Fixes HexEncodingProvider.TryEncode throws after partly writing the destination for inputs ≥ 1 GiB, and GetMaxEncodedLength returns a negative bound #150: the hex bound is computed in long; GetMaxEncodedLength throws for inputs that can't fit and TryEncode returns false instead of throwing after a partial write.
• Fixes JsonSerializationProvider.TrySerialize and Deserialize throw InvalidOperationException instead of returning false/default #161: JSON TrySerialize/Deserialize report System.Text.Json's InvalidOperationException as failure. It lands with RetrieveOrCreateAsync overwrites a stored file it cannot parse with new T(), destroying the user's data #82, as the issue asked.

Streams, compression and encryption

• Fixes Gzip, Deflate, ZLib and Brotli TryDecompress return true for truncated input and hand back partial data #80: truncated Gzip, ZLib and Brotli input is a failure on every path, not a shorter success. Gzip's CRC-32 and length and ZLib's Adler-32 trailers are checked against the output (multi-member gzip still reads), and Brotli goes through BrotliDecoder, which reports an unfinished stream. Raw Deflate has no trailer, and its docs now say so.
• Fixes Compression, AES, encoding and obfuscation stream Try* methods throw NotSupportedException for a non-readable source or non-writable destination instead of returning false #86: every stream Try* in compression, AES, encoding and obfuscation returns false for an unreadable source or unwritable destination instead of throwing NotSupportedException.
• Fixes HMAC TryHash(key, Stream) throws ObjectDisposedException / NotSupportedException for a disposed or write-only stream instead of returning false #74: the hash and HMAC stream paths return false for an unreadable stream.
• Fixes FNV, Hex and byte-wise obfuscation stream paths read one byte at a time: ~11x slower and 32 bytes allocated per input byte on plain streams #91: FNV, Hex, Xor, Caesar and BitRotate stream paths work a chunk at a time instead of byte by byte.
• Fixes AesEncryptionProvider leaves copies of the key and plaintext in unzeroed heap arrays, unlike the HMAC providers #98: AES zeroes its key copies and plaintext buffers, with known-answer tests against EncryptCbc.
• Fixes Only Gzip checks that async compression output is byte-identical to sync; Deflate, ZLib, Brotli and AES have no such test (async-surface spec) #83: the async-equals-sync byte tests cover all four compressors and AES.

Other fixes

• Fixes Categorical distribution and Choose(items, weights) return zero-weight outcomes: weights [1e308, 1e308, 0] always sample index 2 #78: weighted Choose and the categorical distribution handle weights whose total overflows, and a trailing zero weight is never picked through rounding.
• Fixes TOML provider loses multi-word properties, lists and nested objects on a round trip, and throws MissingMethodException for records #69: TOML ignores unknown keys, binds through a cached delegate, and returns default for types it can't create.
• Fixes FileLoggingProvider deletes every rolled log file when a roll fails: each retry shifts history and deletes the oldest without completing the roll #120: the file logger's roll is transactional, so a reader holding a file can't lose entries; the roll is retried on the next write.
• Fixes NativeCommandExecutor.Execute ignores cancellation once the shell exits but a background child holds stdout open, then reports success #125 and Cancelling NativeCommandExecutor.Execute kills only the shell: work in a subshell, pipeline or child process keeps running and completes its side effects #97: command cancellation is honoured after the shell exits while a background child still holds its output. Cancelling NativeCommandExecutor.Execute kills only the shell: work in a subshell, pipeline or child process keeps running and completes its side effects #97's tree kill had already shipped in Kill the child when ExecuteAsync is cancelled, as Execute does [patch] #100.

Testing

Full Essentials.Tests on net10.0: 1336 passed, 1 skipped (a Windows-only test). The persistence suite passed 20 runs in a row after the create race fix. The whole solution builds with the analyzers on every target framework. The pre-net8 Base64 path compiles but only net10 runs in tests.

https://claude.ai/code/session_01TmbAehyjJjPCQdRASdECes

---

Generated by Claude Code

[matt-edmondson]

This stays as it is on purpose. The store's contract is that cancellation passes through and every other failure becomes a PersistenceProviderException, which this PR's CLAUDE.md entry for FileRecordStore documents. Narrowing the catch would let a serializer- or key-conversion failure of any other type escape unwrapped, which is a behavior change for callers.

---

Generated by Claude Code

[matt-edmondson]

This stays as it is. BrotliDecoder is a mutable struct, and a using local is read-only, so each Decompress call would run on a defensive copy. That works today only because the copy shares the decoder's native handle. The explicit try/finally keeps the calls on the one variable that gets disposed.

---

Generated by Claude Code

[matt-edmondson]

This stays as it is. BrotliDecoder is a mutable struct, and a using local is read-only, so each Decompress call would run on a defensive copy. That works today only because the copy shares the decoder's native handle. The explicit try/finally keeps the calls on the one variable that gets disposed.

---

Generated by Claude Code

[matt-edmondson]

This stays as it is. It's a test helper, and the guard just drops the cut offsets that fall outside a short payload, so a Where wouldn't make it any clearer.

---

Generated by Claude Code

[matt-edmondson]

Test on windows-latest failed in Concurrent_Stores_To_One_Key_Never_Throw_Or_Hide_The_Key. A read that landed while an overwriting move was swapping the record got UnauthorizedAccessException: the file being replaced was still pending deletion, so Windows returned access denied instead of a sharing violation. This PR's retry only covered the sharing violation.

The next commit also retries access denied on Windows reads. A real permission problem still surfaces once the attempts run out. I can only reproduce this on Windows, so the next Windows run is the check.

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
42 New issues
0 Accepted issues

Measures
0 Security Hotspots
91.5% Coverage on New Code
2.4% Duplication on New Code

See analysis details on SonarQube Cloud