Read a BigInteger's bytes as bytes, so converting one to a Number stops throwing (#585)

[Rafael-SOWNet]

Entity and Entity.Number both offer an implicit conversion from System.Numerics.BigInteger, and they did not agree.

Entity        fine  = new BigInteger(123456789);   // 123456789
Entity.Number threw = new BigInteger(123456789);   // FormatException: Illegal character found

Entity's reads the two's-complement bytes. Number's handed the same bytes to EInteger.FromString, whose byte[] overload reads them as ASCII digits:

// was
=> Integer.Create(EInteger.FromString(bigInt.ToByteArray()));
// is
=> Integer.Create(EInteger.FromBytes(bigInt.ToByteArray(), littleEndian: true));

So it failed for every value whose bytes are not digit characters — nearly all of them, 1 included. The handful that worked did so by accident: 12594 is the two bytes '2' and '1', and came back as 21.

Why nothing caught it

Nothing inside the library reaches that conversion. It exists only for callers, so no internal path and no test ever crossed it — the failure mode where a public API is broken precisely because it is public-only.

The test therefore requires the two conversions to agree, not merely that each works. One value converted two ways giving two answers is the defect; the exception is only how it showed up.

58 cases, over values on both sides of every byte boundary that matters — 127, 128, 255, 256, the long limits either side, and a value past 2^127 — plus the accidental-success case pinned so its old behaviour is on record.

How it was found

While documenting the members a #pragma warning disable CS1591 was covering, for #585. The two conversions live in different files and neither looks wrong on its own; reading them side by side is what showed it, and reading them side by side is exactly what documenting them required.

That is the second thing that sweep has turned up after the pragmas that were suppressing nothing.

Measured

Suite 7175 passed / 0 failed, 58 new. Recorded in BREAKING-CHANGES.md under a new Unreleased — since 2.2.0 section: an exception becoming a value is a changed answer.

🤖 Generated with Claude Code