fix: enforce non-null successful result values

Author: KSemenenko

AGENTS.md

@@ -9,6 +9,7 @@ If I tell you to remember something, you do the same, update
 
 
 ## Rules to follow
+- A successful `Result<T>` must always carry a non-null `Value`, matching its `MemberNotNullWhen` annotations. Reject null success payloads at the owning result setter/factory, including nullable type arguments and initializer overrides. Use non-generic `Result.Succeed()` for a success without a payload; never preserve a successful null value to accommodate a consumer null guard.
 - Communication Orleans integration uses native generated Orleans serialization and its typed surrogates only. Do not add Newtonsoft.Json, JSON grain-storage adapters/converters, or automatic JSON storage registrations. Applications own their storage-provider serialization.
 - For failure logging, use Warning with failure details when there is no exception, and Error with the original stack trace when an exception is supplied.
 - For automatic Result failure telemetry, record the error and original exception immediately in the failure/catch path; never retain an exception reference in Result or Problem for later diagnostics.

Directory.Build.props

@@ -27,8 +27,8 @@
         <RepositoryUrl>https://github.com/managedcode/Communication</RepositoryUrl>
         <PackageProjectUrl>https://github.com/managedcode/Communication</PackageProjectUrl>
         <Product>Managed Code - Communication</Product>
-        <Version>10.3.5</Version>
-        <PackageVersion>10.3.5</PackageVersion>
+        <Version>10.3.6</Version>
+        <PackageVersion>10.3.6</PackageVersion>
 
     </PropertyGroup>
     <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">

ManagedCode.Communication.Tests/AspNetCore/Extensions/ControllerExtensionsTests.cs

@@ -215,18 +215,11 @@ public void ToActionResult_WithComplexObject_ReturnsCorrectValue()
     }
 
     [Test]
-    public void ToHttpResult_WithNullValue_HandlesGracefully()
+    public void ToHttpResult_WithNullTypedSuccess_RejectsInvalidPayload()
     {
-        // Arrange
         string? nullValue = null;
-        var result = Result<string?>.Succeed(nullValue);
-
-        // Act
-        var httpResult = result.ToHttpResult();
 
-        // Assert
-        httpResult.ShouldNotBeNull();
-        httpResult.GetType().Name.ShouldContain("Ok");
+        Should.Throw<ArgumentNullException>(() => Result<string?>.Succeed(nullValue).ToHttpResult());
     }
 
     [Test]

ManagedCode.Communication.Tests/Results/ResultSuccessValueContractTests.cs

@@ -0,0 +1,65 @@
+using System;
+using System.Text.Json;
+using Shouldly;
+
+namespace ManagedCode.Communication.Tests.Results;
+
+public class ResultSuccessValueContractTests
+{
+    private const string Payload = "payload";
+    private const string Failure = "missing";
+    private const string ValueParameter = "value";
+    private const string NullSuccessJson = "{\"isSuccess\":true,\"value\":null}";
+
+    [Test]
+    public void Succeed_WithNullReference_RejectsNullPayload()
+    {
+        Should.Throw<ArgumentNullException>(() => Result<string>.Succeed((string)null!))
+            .ParamName.ShouldBe(ValueParameter);
+    }
+
+    [Test]
+    public void Succeed_WithNullableNull_RejectsNullPayload()
+    {
+        Should.Throw<ArgumentNullException>(() => Result<string?>.Succeed((string?)null));
+        Should.Throw<ArgumentNullException>(() => Result<int?>.Succeed((int?)null));
+    }
+
+    [Test]
+    public void Succeed_WithDefaultReference_RejectsNullPayload()
+    {
+        Should.Throw<ArgumentNullException>(() => Result<string>.Succeed());
+    }
+
+    [Test]
+    public void Succeed_WithDefaultValueType_PreservesValidDefault()
+    {
+        var result = Result<int>.Succeed();
+        result.IsSuccess.ShouldBeTrue();
+        result.Value.ShouldBe(0);
+    }
+
+    [Test]
+    public void Initializer_WithNullSuccessPayload_RejectsOverride()
+    {
+        var success = Result<string>.Succeed(Payload);
+        Should.Throw<ArgumentNullException>(() => { _ = success with { Value = null }; });
+        success.IsSuccess.ShouldBeTrue();
+        success.Value.ShouldBe(Payload);
+    }
+
+    [Test]
+    public void Failure_WithNullPayload_PreservesFailure()
+    {
+        var result = Result<string>.FailNotFound(Failure) with { Value = null };
+        result.IsFailed.ShouldBeTrue();
+        result.Value.ShouldBeNull();
+        result.Problem.ShouldNotBeNull();
+    }
+
+    [Test]
+    public void Deserialize_WithNullSuccessPayload_RejectsInvalidResult()
+    {
+        Should.Throw<ArgumentNullException>(() => JsonSerializer.Deserialize<Result<string>>(NullSuccessJson));
+    }
+}

ManagedCode.Communication/ResultT/Result.cs

@@ -18,6 +18,8 @@ namespace ManagedCode.Communication;
 [DebuggerDisplay("IsSuccess: {IsSuccess}; Problem: {Problem?.Title}")]
 public partial struct Result<T> : IResult<T>, IResultFactory<Result<T>>, IResultValueFactory<Result<T>, T>
 {
+    private T? _value;
+
     /// <summary>
     ///     Initializes a new instance of the Result struct.
     /// </summary>
@@ -127,7 +129,19 @@ public bool TryGetProblem([MaybeNullWhen(false)] out Problem problem)
     /// </remarks>
     [JsonPropertyName(CommunicationJsonNames.Value)]
     [JsonPropertyOrder(2)]
-    public T? Value { get; init; }
+    public T? Value
+    {
+        get => _value;
+        init
+        {
+            if (IsSuccess)
+            {
+                ArgumentNullException.ThrowIfNull(value);
+            }
+
+            _value = value;
+        }
+    }
 
     [JsonInclude]
     [JsonPropertyName(CommunicationJsonNames.Problem)]

ManagedCode.Communication/ResultT/ResultT.Succeed.cs

@@ -6,13 +6,15 @@ namespace ManagedCode.Communication;
 public partial struct Result<T>
 {
     /// <summary>
-    ///     Creates a success carrying the default value.
+    ///     Creates a success carrying the default value when that value is non-null.
     /// </summary>
+    /// <exception cref="ArgumentNullException">The default value of T is null. Use non-generic Result for a success without a payload.</exception>
     public static Result<T> Succeed() => CreateSuccess(default!);
 
     /// <summary>
     ///     Creates a success carrying the value.
     /// </summary>
+    /// <exception cref="ArgumentNullException">The supplied value is null.</exception>
     public static Result<T> Succeed(T value) => CreateSuccess(value);
 
     /// <summary>

README.md

@@ -120,6 +120,12 @@ A failed untyped `Result` or a `Problem` can become a typed failure. A successfu
 value to supply to `Result<T>`; converting it to a typed result produces a failure. Create typed successes
 from their actual values.
 
+`Result<T>.IsSuccess` guarantees a non-null `Value`. Passing null to a typed success factory, or
+replacing a successful payload with null in an initializer, throws `ArgumentNullException`; a nullable
+C# type argument does not allow a successful null payload. `Result<int>.Succeed()` still carries zero,
+while `Result<string>.Succeed()` has no valid default payload and throws. For an operation with no
+data, return `Result.Succeed()`; for optional data, return a real value or an appropriate failure.
+
 `Result` and `Result<T>` are structs. Their state is fixed after construction, but referenced payloads and
 `Problem` objects remain mutable. Avoid changing a shared problem after returning or publishing it.
 `default(Result)` is not a successful result; use a factory to state the intended outcome.