CxODEV-1884: carry a diagnostic message on the structured_error contract

Backport of the 4.2.0 change to the 3.8 line, which consuming services
pin. Identical patch: the five touched files were byte-identical between
v3.8.0 and master.

StructuredErrorException supported only code and reason, so callers that
need both a short, stable reason and a detailed explanation had nowhere to
put the detail and had to fold it into reason. That defeats matching on
reason downstream, and leaves consumers with no separate diagnostic field.

Add StructuredError.Message, populated from the exception. No Message
property is added to the exception itself -- it already has one by virtue
of being an Exception, and the new constructors set it via base(). The
mapping only emits message when it differs from reason, so payloads from
existing call sites are byte-identical and the field is omitted entirely
(NullValueHandling.Ignore), keeping the shape at version 1.

message trails referenceError in the new constructors rather than
following reason. Overload resolution cannot pick between
(code, reason, referenceError, message) and the existing
(code, reason, referenceError, innerException) when the fourth argument is
an untyped null -- and (code, reason, message, null), a message with no
drill-down URI, is the common case. Placing the nullable parameter third
leaves only (code, reason, referenceError, null) ambiguous, which the
three-argument constructor already expresses.

Both execution managers had a hand-copied exception-to-payload mapping and
the test mirrored rather than called it, so a new field could pass tests
while being silently dropped by the type-poll path. Extract the mapping
into StructuredError.FromException and point all three at it.

Released as 3.8.1 rather than a 3.8.0-suffixed build: under semver a
hyphenated suffix is a pre-release and sorts before 3.8.0, so consumers on
3.8.0 would never be offered it as an upgrade.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ognjenkatic

src/ConductorSharp.Client/ConductorSharp.Client.csproj

@@ -6,7 +6,7 @@
 		<Authors>Codaxy</Authors>
 		<Company>Codaxy</Company>
 		<PackageId>ConductorSharp.Client</PackageId>
-		<Version>3.8.0</Version>
+		<Version>3.8.1</Version>
 		<Description>Client library for Netflix Conductor, with some additional quality of life features.</Description>
 		<RepositoryUrl>https://github.com/codaxy/conductor-sharp</RepositoryUrl>
 		<PackageTags>netflix;conductor</PackageTags>

src/ConductorSharp.Engine/ConductorSharp.Engine.csproj

@@ -6,7 +6,7 @@
     <Authors>Codaxy</Authors>
 	<Company>Codaxy</Company>
 	<PackageId>ConductorSharp.Engine</PackageId>
-	<Version>3.8.0</Version>
+	<Version>3.8.1</Version>
     <Description>Client library for Netflix Conductor, with some additional quality of life features.</Description>
 	<RepositoryUrl>https://github.com/codaxy/conductor-sharp</RepositoryUrl>
 	<PackageTags>netflix;conductor</PackageTags>

src/ConductorSharp.Engine/Exceptions/StructuredErrorException.cs

@@ -5,17 +5,22 @@ namespace ConductorSharp.Engine.Exceptions
     /// <summary>
     /// Thrown by a worker to attach a structured, sanitized error classification to the failed task's output.
     /// When caught by the execution manager, the <see cref="Code"/>/<see cref="Reason"/>/<see cref="ReferenceError"/>
-    /// are serialized under the <c>structured_error</c> output key (see
+    /// and the diagnostic message are serialized under the <c>structured_error</c> output key (see
     /// <see cref="ConductorSharp.Engine.Util.StructuredErrorSerializer"/>), in addition to the plain
     /// <c>error_message</c>, so downstream consumers can read a stable classification without parsing free-text
     /// reasons. Plain exceptions are unaffected and keep producing only <c>error_message</c>.
     /// </summary>
+    /// <remarks>
+    /// There is deliberately no <c>Message</c> property here: the diagnostic message is carried by the inherited
+    /// <see cref="Exception.Message"/>, which the message-taking constructors set. When no message is supplied it
+    /// falls back to <see cref="Reason"/>, matching the behaviour of the original constructors.
+    /// </remarks>
     public class StructuredErrorException : Exception
     {
         /// <summary>Stable, opaque classification code. Consumers map this to a failure response.</summary>
         public string Code { get; }
 
-        /// <summary>Human-readable, sanitized reason. Safe to surface across a layer boundary.</summary>
+        /// <summary>Short, stable, sanitized reason. Safe to surface across a layer boundary.</summary>
         public string Reason { get; }
 
         /// <summary>Optional URI pointing at the entity where the failure originated (drill-down link).</summary>
@@ -36,5 +41,35 @@ public StructuredErrorException(string code, string reason, string referenceErro
             Reason = reason;
             ReferenceError = referenceError;
         }
+
+        /// <summary>
+        /// Declares a diagnostic <paramref name="message"/> distinct from the short, stable
+        /// <paramref name="reason"/>. Pass <c>null</c> for <paramref name="message"/> to fall back to the reason,
+        /// and <c>null</c> for <paramref name="referenceError"/> when there is no entity to drill down into.
+        /// </summary>
+        /// <remarks>
+        /// <paramref name="message"/> trails <paramref name="referenceError"/> rather than following
+        /// <paramref name="reason"/> (the TMF field order) on purpose. Overload resolution cannot choose between
+        /// this constructor and the <see cref="Exception"/> one when the fourth argument is an untyped <c>null</c>,
+        /// so the nullable parameter is placed third, where it is typed the same either way. The only call this
+        /// leaves ambiguous is <c>(code, reason, referenceError, null)</c> — a declared-but-null inner exception,
+        /// which the three-argument constructor already expresses. Disambiguate with a named argument if needed.
+        /// </remarks>
+        public StructuredErrorException(string code, string reason, string referenceError, string message)
+            : base(message ?? reason)
+        {
+            Code = code;
+            Reason = reason;
+            ReferenceError = referenceError;
+        }
+
+        /// <inheritdoc cref="StructuredErrorException(string, string, string, string)"/>
+        public StructuredErrorException(string code, string reason, string referenceError, string message, Exception innerException)
+            : base(message ?? reason, innerException)
+        {
+            Code = code;
+            Reason = reason;
+            ReferenceError = referenceError;
+        }
     }
 }

src/ConductorSharp.Engine/ExecutionManager.cs

@@ -247,19 +247,9 @@ await _taskManager.UpdateAsync(
                     pollResponse.WorkflowInstanceId
                 );
 
-                var errorMessage = new ErrorOutput { ErrorMessage = exception.Message };
-
                 // A worker may throw a StructuredErrorException to attach a sanitized, stable classification to the
                 // failed task's output. Plain exceptions keep producing only error_message, preserving backward compatibility.
-                if (exception is StructuredErrorException structuredException)
-                {
-                    errorMessage.StructuredError = new StructuredError
-                    {
-                        Code = structuredException.Code,
-                        Reason = structuredException.Reason,
-                        ReferenceError = structuredException.ReferenceError
-                    };
-                }
+                var errorMessage = new ErrorOutput { ErrorMessage = exception.Message, StructuredError = StructuredError.FromException(exception) };
 
                 // TODO: We should verify that this is alright, it is possible that when executed concurrently,
                 // the updates caused by LogAsync will be discarded because the call of UpdateAsync(TaskResult...)

src/ConductorSharp.Engine/Model/StructuredError.cs

@@ -1,3 +1,6 @@
+using System;
+using ConductorSharp.Engine.Exceptions;
+
 namespace ConductorSharp.Engine.Model
 {
     /// <summary>
@@ -12,13 +15,43 @@ public class StructuredError
         /// <summary>Stable, opaque classification code (e.g. an implementation-defined code, or <c>UNCLASSIFIED</c>).</summary>
         public string Code { get; set; }
 
-        /// <summary>Human-readable, sanitized reason.</summary>
+        /// <summary>Short, stable, sanitized reason. Consumers may key off this text, so keep it terse.</summary>
         public string Reason { get; set; }
 
+        /// <summary>
+        /// Optional diagnostic detail, longer and more specific than <see cref="Reason"/> — the explanation an
+        /// operator needs, kept out of <see cref="Reason"/> so that stays short and stable. Null when the producer
+        /// supplied nothing distinct from the reason, in which case it is omitted from serialized output
+        /// (NullValueHandling.Ignore) and the payload is unchanged from before this field existed.
+        /// </summary>
+        public string Message { get; set; }
+
         /// <summary>Optional URI pointing at the entity where the failure originated (drill-down link).</summary>
         public string ReferenceError { get; set; }
 
         /// <summary>Payload shape version marker. Defaults to <see cref="CurrentVersion"/>.</summary>
         public int Version { get; set; } = CurrentVersion;
+
+        /// <summary>
+        /// Maps a thrown exception onto the payload, returning <c>null</c> for anything that is not a
+        /// <see cref="StructuredErrorException"/> so plain exceptions keep producing only <c>error_message</c>.
+        /// This is the single exception-to-payload mapping: both execution managers and the contract tests call it,
+        /// so the two poll strategies cannot drift apart as the shape evolves.
+        /// </summary>
+        public static StructuredError FromException(Exception exception)
+        {
+            if (exception is not StructuredErrorException structuredException)
+                return null;
+
+            return new StructuredError
+            {
+                Code = structuredException.Code,
+                Reason = structuredException.Reason,
+                // Exception.Message falls back to Reason when the thrower supplied no distinct detail, so only
+                // carry it when it actually adds something. Existing call sites keep their exact payload.
+                Message = structuredException.Message == structuredException.Reason ? null : structuredException.Message,
+                ReferenceError = structuredException.ReferenceError
+            };
+        }
     }
 }

src/ConductorSharp.Engine/TypePollSpreadingExecutionManager.cs

@@ -256,19 +256,9 @@ await _taskManager.UpdateAsync(
                     pollResponse.WorkflowInstanceId
                 );
 
-                var errorMessage = new ErrorOutput { ErrorMessage = exception.Message };
-
                 // A worker may throw a StructuredErrorException to attach a sanitized, stable classification to the
                 // failed task's output. Plain exceptions keep producing only error_message, preserving backward compatibility.
-                if (exception is StructuredErrorException structuredException)
-                {
-                    errorMessage.StructuredError = new StructuredError
-                    {
-                        Code = structuredException.Code,
-                        Reason = structuredException.Reason,
-                        ReferenceError = structuredException.ReferenceError
-                    };
-                }
+                var errorMessage = new ErrorOutput { ErrorMessage = exception.Message, StructuredError = StructuredError.FromException(exception) };
 
                 // TODO: We should verify that this is alright, it is possible that when executed concurrently,
                 // the updates caused by LogAsync will be discarded because the call of UpdateAsync(TaskResult...)

src/ConductorSharp.KafkaCancellationNotifier/ConductorSharp.KafkaCancellationNotifier.csproj

@@ -4,7 +4,7 @@
     <TargetFramework>net6.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>3.8.0</Version>
+    <Version>3.8.1</Version>
     <Authors>Codaxy</Authors>
     <Company>Codaxy</Company>
   </PropertyGroup>

src/ConductorSharp.Patterns/ConductorSharp.Patterns.csproj

@@ -7,7 +7,7 @@
     <GeneratePackageOnBuild>False</GeneratePackageOnBuild>
     <Authors>Codaxy</Authors>
     <Company>Codaxy</Company>
-    <Version>3.8.0</Version>
+    <Version>3.8.1</Version>
   </PropertyGroup>
 
 	<ItemGroup>

test/ConductorSharp.Engine.Tests/Unit/StructuredErrorTests.cs

@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using System.Linq;
 using ConductorSharp.Client;
 using ConductorSharp.Client.Util;
 using ConductorSharp.Engine.Exceptions;
@@ -12,26 +13,19 @@ namespace ConductorSharp.Engine.Tests.Unit
 {
     public class StructuredErrorTests
     {
-        // Mirrors the execution-manager catch block: builds the ErrorOutput (setting StructuredError for a
-        // StructuredErrorException) and serializes it. TryParse below asserts this output round-trips through the
-        // shared serializer, pinning the property-derived key/shape to StructuredErrorSerializer.OutputKey.
+        // Mirrors the execution-manager catch block. It calls StructuredError.FromException — the same mapping both
+        // ExecutionManager and TypePollSpreadingExecutionManager use — rather than reimplementing it, so a field
+        // added to the payload cannot pass here while being dropped by one of the managers.
         private static IDictionary<string, object> SerializeCatchOutput(System.Exception exception)
         {
-            var output = new ErrorOutput { ErrorMessage = exception.Message };
-
-            if (exception is StructuredErrorException structuredException)
-            {
-                output.StructuredError = new StructuredError
-                {
-                    Code = structuredException.Code,
-                    Reason = structuredException.Reason,
-                    ReferenceError = structuredException.ReferenceError
-                };
-            }
+            var output = new ErrorOutput { ErrorMessage = exception.Message, StructuredError = StructuredError.FromException(exception) };
 
             return SerializationHelper.ObjectToDictionary(output, ConductorConstants.IoJsonSerializerSettings);
         }
 
+        private static JToken StructuredErrorOf(IDictionary<string, object> dict) =>
+            JObject.Parse(JsonConvert.SerializeObject(dict))[StructuredErrorSerializer.OutputKey];
+
         [Fact]
         public void StructuredErrorException_produces_snake_case_structured_error()
         {
@@ -42,7 +36,7 @@ public void StructuredErrorException_produces_snake_case_structured_error()
             Assert.True(dict.ContainsKey("error_message"));
             Assert.True(dict.ContainsKey(StructuredErrorSerializer.OutputKey));
 
-            var structured = JObject.Parse(JsonConvert.SerializeObject(dict))["structured_error"];
+            var structured = StructuredErrorOf(dict);
             Assert.Equal("RESOURCE_UNAVAILABLE", (string)structured["code"]);
             Assert.Equal("No port available", (string)structured["reason"]);
             Assert.Equal("https://rom/resourceOrder/42", (string)structured["reference_error"]);
@@ -60,13 +54,90 @@ public void PlainException_output_is_backward_compatible()
             Assert.Single(dict);
         }
 
+        [Fact]
+        public void Message_is_carried_under_snake_case_message_key()
+        {
+            var exception = new StructuredErrorException(
+                "ORDER_ITEM_VALIDATION",
+                "Characteristic not in specification",
+                "https://som/serviceOrder/7",
+                "Service characteristic 'tenantId1' not found in service specification 'NaaSSvc-B2B_Internet'."
+            );
+
+            var structured = StructuredErrorOf(SerializeCatchOutput(exception));
+
+            Assert.Equal("ORDER_ITEM_VALIDATION", (string)structured["code"]);
+            Assert.Equal("Characteristic not in specification", (string)structured["reason"]);
+            Assert.Equal(
+                "Service characteristic 'tenantId1' not found in service specification 'NaaSSvc-B2B_Internet'.",
+                (string)structured["message"]
+            );
+            Assert.Equal("https://som/serviceOrder/7", (string)structured["reference_error"]);
+        }
+
+        [Fact]
+        public void Message_reaches_error_message_and_reason_for_incompletion()
+        {
+            // error_message is set from Exception.Message, which the message-taking constructor overrides. The same
+            // value is what the execution manager sends as TaskResult.ReasonForIncompletion (the Conductor UI banner).
+            var exception = new StructuredErrorException("CODE", "Short reason", null, "Long diagnostic detail");
+
+            Assert.Equal("Long diagnostic detail", exception.Message);
+            Assert.Equal("Long diagnostic detail", (string)SerializeCatchOutput(exception)["error_message"]);
+        }
+
+        [Fact]
+        public void Message_is_omitted_when_no_message_was_supplied()
+        {
+            // Guards the backward-compatibility promise: pre-existing call sites must keep their exact payload.
+            var structured = StructuredErrorOf(
+                SerializeCatchOutput(new StructuredErrorException("CODE", "Short reason", "https://rom/resourceOrder/1"))
+            );
+
+            Assert.Null(structured["message"]);
+            Assert.Equal(
+                new[] { "code", "reason", "reference_error", "version" },
+                ((JObject)structured).Properties().Select(p => p.Name).OrderBy(n => n)
+            );
+        }
+
+        [Fact]
+        public void Message_is_omitted_when_it_only_repeats_the_reason()
+        {
+            var exception = new StructuredErrorException("CODE", "Same text", null, "Same text");
+
+            Assert.Null(StructuredErrorOf(SerializeCatchOutput(exception))["message"]);
+        }
+
+        [Fact]
+        public void Message_survives_the_round_trip()
+        {
+            var dict = SerializeCatchOutput(
+                new StructuredErrorException("CODE", "Short reason", "https://rom/resourceOrder/9", "Long diagnostic detail")
+            );
+
+            Assert.True(StructuredErrorSerializer.TryParse(dict, out var parsed));
+            Assert.Equal("CODE", parsed.Code);
+            Assert.Equal("Short reason", parsed.Reason);
+            Assert.Equal("Long diagnostic detail", parsed.Message);
+            Assert.Equal("https://rom/resourceOrder/9", parsed.ReferenceError);
+        }
+
+        [Fact]
+        public void FromException_returns_null_for_a_plain_exception()
+        {
+            Assert.Null(StructuredError.FromException(new System.InvalidOperationException("boom")));
+        }
+
         [Fact]
         public void RoundTrip_helper_output_is_parsed_back()
         {
+            // The signal-sender producer: no exception to catch, so the payload is rendered from the model directly.
             var error = new StructuredError
             {
                 Code = "UNCLASSIFIED",
                 Reason = "generic failure",
+                Message = "workflow 1a2b / task 3c4d failed: connection refused",
                 ReferenceError = "https://rom/resourceOrder/7"
             };
 
@@ -75,6 +146,7 @@ public void RoundTrip_helper_output_is_parsed_back()
             Assert.True(StructuredErrorSerializer.TryParse(outputData, out var parsed));
             Assert.Equal(error.Code, parsed.Code);
             Assert.Equal(error.Reason, parsed.Reason);
+            Assert.Equal(error.Message, parsed.Message);
             Assert.Equal(error.ReferenceError, parsed.ReferenceError);
             Assert.Equal(error.Version, parsed.Version);
         }
@@ -123,5 +195,17 @@ public void TryParse_returns_false_when_code_missing()
 
             Assert.False(StructuredErrorSerializer.TryParse(dict, out _));
         }
+
+        [Fact]
+        public void TryParse_tolerates_a_message_only_payload_by_degrading()
+        {
+            // A message without a code is still unstructured: the caller must fall back to the generic path.
+            var dict = new Dictionary<string, object>
+            {
+                [StructuredErrorSerializer.OutputKey] = new Dictionary<string, object> { ["message"] = "detail but no code" }
+            };
+
+            Assert.False(StructuredErrorSerializer.TryParse(dict, out _));
+        }
     }
 }