Prep for release

Author: jeskew

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 3.0.x - 2026-08-28
+
+### Breaking
+- The `System.Random` subclass formerly named `Antithesis.SDK.Random` is now named `Antithesis.SDK.AntithesisRandom`.
+This allows us to more closely align with other Antithesis SDKs that include a `Random` class for providing simple
+Antithesis sourced entropy (see New section below).
+
+### Bug Fixes
+- Fixed the bug truncating strings containing non-ASCII characters when writing to `FFISink`.
+
+### New
+- Added `Assert.Raw`, a low-level assertion entry point for third-party frameworks that supply their own catalog metadata.
+- Added `Antithesis.SDK.Random` with `GetRandom()` to source entropy directly from the Antithesis platform and
+`RandomChoice<T>(IReadOnlyList<T>)` to randomly pick an element of a list.
+
+## 2.0.4 - 2026-04-22
+
+### Breaking
+- In order to improve performance, "numeric guidance" Assert methods no longer write when the difference between its two
+operands does not change (i.e. they only write the first occurrence of a given difference):
+AlwaysGreaterThan(OrEqualTo), AlwaysLessThan(OrEqualTo), SometimesGreaterThan(OrEqualTo), SometimesLessThan(OrEqualTo). 
+This is only breaking if you rely on ANTITHESIS_SDK_LOCAL_OUTPUT when testing locally.
+
+### Bug Fixes
+- None
+
+### New
+- None
+
+## 1.0.31 - 2025-06-10
+
+First official release.

README.md

@@ -1,11 +1,14 @@
 # Antithesis .NET SDK
 
-This package contains types for .NET applications to use to integrate with [Antithesis](https://antithesis.com).
-* The `Assert` class enables defining [test properties](https://antithesis.com/docs/properties_assertions/properties/)
-about your program or [workload](https://antithesis.com/docs/test_templates/first_test/).
-* The `Lifecycle` class contains methods used to inform Antithesis that particular test phases or milestones have been reached.
-* The `Random` class is a subclass of `System.Random` that encapsulates Antithesis's deterministic and reproducible
-random number generator.
+This package contains types for .NET applications to integrate with [Antithesis](https://antithesis.com).
+* The `Assert` class methods define [test properties](https://antithesis.com/docs/introduction/how_antithesis_works/#how-does-antithesis-identify-bugs/)
+about your software or [workload](https://antithesis.com/docs/product/writing_tests/test_templates/first_test/).
+* The `Random` class methods source entropy directly from the Antithesis platform: raw 64-bit values via `GetRandom()`
+and structured list picks via `RandomChoice()`.
+* The `AntithesisRandom` class is a subclass of `System.Random` that encapsulates Antithesis's steering choices,
+making it easy for .NET code that uses `System.Random` to be included in Antithesis-guided exploration.
+* The `Lifecycle` class methods inform the Antithesis environment that particular test phases or milestones have been
+reached.
 
 For general usage guidance see the [Antithesis .NET SDK Documentation](https://antithesis.com/docs/using_antithesis/sdk/dotnet/).
 

samples/HelloAntithesis/WebService/Program.cs

@@ -8,7 +8,7 @@
 
 var app = builder.Build();
 
-var random = Antithesis.SDK.Random.SharedFallbackToSystem;
+var random = Antithesis.SDK.AntithesisRandom.SharedFallbackToSystem;
 
 app.MapGet("/", async () =>
 {

src/Antithesis.SDK/AntithesisRandom.cs

@@ -0,0 +1,139 @@
+namespace Antithesis.SDK;
+
+using System.Diagnostics;
+
+// Methods adapted or inspired by:
+// https://github.com/dotnet/runtime/blob/v9.0.5/src/libraries/System.Private.CoreLib/src/System/Random.ImplBase.cs
+// https://github.com/dotnet/runtime/blob/v9.0.5/src/libraries/System.Private.CoreLib/src/System/Random.Xoshiro256StarStarImpl.cs
+
+/// <summary>
+/// AntithesisRandom is a subclass of <see cref="System.Random">System.Random</see> that encapsules Antithesis's
+/// deterministic and reproducible random number generator. Obtain an instance via
+/// <see cref="SharedFallbackToSystem"/>; for raw 64-bit draws, see <see cref="Random.GetRandom"/>.
+/// </summary>
+/// <remarks>
+/// Regarding the methods which have to be overriden with Sample when subclassing System.Random:
+/// <a href="https://learn.microsoft.com/en-us/dotnet/api/system.random.sample?view=net-9.0#notes-to-inheritors">Microsoft Learn</a>.
+/// We also chose to override NextBytes(Span&lt;Byte&gt;) because we used it for NextBytes(Byte[]) which had to be overridden.
+/// </remarks>
+public class AntithesisRandom : System.Random
+{
+    // Force the Sink's static constructor to write out SDK info in case this is the first use of the SDK.
+    static AntithesisRandom() => Sink.Touch();
+
+    /// <inheritdoc />
+    [Obsolete("Please use Antithesis.SDK.AntithesisRandom.SharedFallbackToSystem which explicitly defines its behavior when outside Antithesis.", true)]
+    new public static System.Random Shared => throw new NotSupportedException();
+
+    /// <summary>
+    /// Returns a Singleton of this class when executing within Antithesis; else, falls back to System.Random.Shared.
+    /// </summary>
+    public static System.Random SharedFallbackToSystem { get; } =
+        FFI.FileExists ? new AntithesisRandom(new FFIRandomUInt64Provider()) : System.Random.Shared;
+
+    internal AntithesisRandom(IRandomUInt64Provider randomUInt64) =>
+        _randomUInt64 = randomUInt64 ?? throw new ArgumentNullException(nameof(randomUInt64));
+
+    private readonly IRandomUInt64Provider _randomUInt64;
+
+    /// <inheritdoc />
+    protected override double Sample()
+    {
+        // Regarding converting the ulong to double between [0.0, 1.0) :
+        // https://github.com/dotnet/runtime/blob/cc803458ab4dabf020b462873be5bf56f1640b1e/src/libraries/System.Private.CoreLib/src/System/Random.Xoshiro256StarStarImpl.cs#L182
+        //
+        // As described in http://prng.di.unimi.it/:
+        // "A standard double (64-bit) floating-point number in IEEE floating point format has 52 bits of significand,
+        //  plus an implicit bit at the left of the significand. Thus, the representation can actually store numbers with
+        //  53 significant binary digits. Because of this fact, in C99 a 64-bit unsigned integer x should be converted to
+        //  a 64-bit double using the expression
+        //  (x >> 11) * 0x1.0p-53"
+        return (_randomUInt64.Next() >> 11) * (1.0 / (1ul << 53));
+    }
+
+    /// <inheritdoc />
+    public override int Next()
+    {
+        while (true)
+        {
+            // Regarding the loop :
+            // https://github.com/dotnet/runtime/blob/cc803458ab4dabf020b462873be5bf56f1640b1e/src/libraries/System.Private.CoreLib/src/System/Random.Xoshiro256StarStarImpl.cs#L76
+            //
+            // Get top 31 bits to get a value in the range [0, int.MaxValue], but try again
+            // if the value is actually int.MaxValue, as the method is defined to return a value
+            // in the range [0, int.MaxValue).
+            ulong result = _randomUInt64.Next() >> 33;
+
+            if (result != int.MaxValue)
+                return (int)result;
+        }
+    }
+
+    /// <inheritdoc />
+    public override int Next(int minValue, int maxValue)
+    {
+        if (minValue > maxValue)
+            throw new ArgumentOutOfRangeException(nameof(minValue));
+
+        if (minValue == maxValue)
+            return minValue;
+
+        return (int)NextUInt32((uint)(maxValue - minValue)) + minValue;
+    }
+
+    private uint NextUInt32(uint maxValue)
+    {
+        // Regarding this algorithm:
+        // https://github.com/dotnet/runtime/blob/cc803458ab4dabf020b462873be5bf56f1640b1e/src/libraries/System.Private.CoreLib/src/System/Random.ImplBase.cs#L36
+        //
+        // NextUInt32/64 algorithms based on https://arxiv.org/pdf/1805.10941.pdf and https://github.com/lemire/fastrange.
+
+        ulong randomProduct = (ulong)maxValue * (_randomUInt64.Next() >> 32);
+        uint lowPart = (uint)randomProduct;
+
+        if (lowPart < maxValue)
+        {
+            uint remainder = (0u - maxValue) % maxValue;
+
+            while (lowPart < remainder)
+            {
+                randomProduct = (ulong)maxValue * (_randomUInt64.Next() >> 32);
+                lowPart = (uint)randomProduct;
+            }
+        }
+
+        return (uint)(randomProduct >> 32);
+    }
+
+    /// <inheritdoc />
+    public override void NextBytes(byte[] buffer)
+    {
+        if (buffer == null)
+            throw new ArgumentNullException(nameof(buffer));
+
+        NextBytes((Span<byte>)buffer);
+    }
+
+    /// <inheritdoc />
+    public override void NextBytes(Span<byte> buffer)
+    {
+        while (buffer.Length >= sizeof(ulong))
+        {
+            ulong random = _randomUInt64.Next();
+            BitConverter.GetBytes(random).CopyTo(buffer);
+
+            buffer = buffer.Slice(sizeof(ulong));
+        }
+
+        if (!buffer.IsEmpty)
+        {
+            ulong random = _randomUInt64.Next();
+            byte[] bytes = BitConverter.GetBytes(random);
+
+            Debug.Assert(buffer.Length < bytes.Length);
+
+            for (int i = 0; i < buffer.Length && i < bytes.Length; i++)
+                buffer[i] = bytes[i];
+        }
+    }
+}

src/Antithesis.SDK/Assert.cs

@@ -99,6 +99,68 @@ private static void NoGuidanceHelper(AssertionMethodType methodType, bool condit
 
     #endregion
 
+    #region Raw
+
+    /// <summary>
+    /// A low-level method designed for use by third-party frameworks that produce Antithesis-style
+    /// assertions with caller-supplied catalog metadata; regular users should call the assertion
+    /// methods above instead.
+    /// <br/><br/>
+    /// Catalog entries (<c>hit</c> = false) are always written. Hit entries are written only for
+    /// the first passing and the first failing call per <c>id</c>.
+    /// </summary>
+    /// <param name="assertType">One of <c>"always"</c>, <c>"sometimes"</c>, or <c>"reachability"</c>.</param>
+    /// <param name="displayType">One of <c>"Always"</c>, <c>"AlwaysOrUnreachable"</c>, <c>"Sometimes"</c>, <c>"Reachable"</c>, or <c>"Unreachable"</c>.</param>
+    /// <param name="className">The name of the class containing the assertion.</param>
+    /// <param name="functionName">The name of the method containing the assertion.</param>
+    /// <param name="filePath">The path of the file containing the assertion.</param>
+    /// <param name="beginLine">The 1-indexed line number where the assertion begins.</param>
+    /// <param name="beginColumn">The 1-indexed column number where the assertion begins.</param>
+    /// <param name="id">The unique identifier of the assertion, used to aggregate assertions and gate emission.</param>
+    /// <param name="condition">The condition being asserted.</param>
+    /// <param name="message">The human-readable name of the corresponding test property.</param>
+    /// <param name="details">Optional additional details to provide greater context for assertion passes and failures.</param>
+    /// <param name="hit">Whether the assertion was evaluated (<c>true</c>) or is being cataloged (<c>false</c>).</param>
+    /// <param name="mustHit">Whether the corresponding test property fails if the assertion is never encountered.</param>
+    public static void Raw(
+        string assertType,
+        string displayType,
+        string className,
+        string functionName,
+        string filePath,
+        int beginLine,
+        int beginColumn,
+        string id,
+        bool condition,
+        string message,
+        JsonObject? details,
+        bool hit,
+        bool mustHit)
+    {
+        if (string.IsNullOrEmpty(id))
+            throw new ArgumentNullException(nameof(id));
+
+        if (Sink.IsNoop)
+            return;
+
+        if (hit && !AssertionTracker.ShouldWrite(id, condition))
+            return;
+
+        var location = new LocationInfo
+        {
+            ClassName = className,
+            MethodName = functionName,
+            FilePath = filePath,
+            BeginLine = beginLine,
+            BeginColumn = beginColumn
+        };
+
+        Sink.Write(AssertionInfo.ConstructForRawWrite(
+            assertType, displayType, id, message, location, mustHit, hit, condition, details));
+    }
+
+    #endregion
+
     #region Numeric Guidance
 
     /// <summary>

src/Antithesis.SDK/Internal/AssertionAndGuidanceTypes.cs

@@ -50,7 +50,7 @@ AssertionDisplayType.Always or
         AssertionDisplayType.Sometimes or
         AssertionDisplayType.Reachable =>
             true,
-        
+
         AssertionDisplayType.AlwaysOrUnreachable or
         AssertionDisplayType.Unreachable =>
             false,
@@ -61,6 +61,9 @@ AssertionDisplayType.AlwaysOrUnreachable or
 
 internal static class AssertionMethodTypeExtensions
 {
+    internal static string GetAssertTypeRaw(this AssertionMethodType methodType) =>
+        methodType.GetAssertType().ToString().ToLowerInvariant();
+
     internal static AssertionAssertType GetAssertType(this AssertionMethodType methodType) => methodType switch
     {
         AssertionMethodType.Always or
@@ -87,6 +90,9 @@ AssertionMethodType.Unreachable or
         _ => throw new NotImplementedException(methodType.ToString())
     };
 
+    internal static string GetDisplayTypeRaw(this AssertionMethodType methodType) =>
+        methodType.GetDisplayType().ToString();
+
     internal static AssertionDisplayType GetDisplayType(this AssertionMethodType methodType) => methodType switch
     {
         AssertionMethodType.Always or
@@ -128,7 +134,7 @@ AssertionMethodType.SometimesGreaterThanOrEqualTo or
         AssertionMethodType.SometimesLessThan or
         AssertionMethodType.SometimesLessThanOrEqualTo =>
             GuidanceType.Numeric,
-        
+
         AssertionMethodType.AlwaysSome or
         AssertionMethodType.SometimesAll =>
             GuidanceType.Boolean,