Minimize diagnostics validator public surface

Author: sfmskywalker

src/Elsa/Diagnostics/Persistence/EXTENSION_POINTS.md

@@ -37,10 +37,18 @@ that needs fan-out must place it behind one implementation instead of resolving
   aggregate bridge; contribution-style `IEnumerable<T>` resolution is not supported.
 - **Data rule:** the contract accepts no diagnostic payload, identifier, tenant, or free-form label.
 
-The public surface is intentionally limited to the contracts and models required for concrete
-adapter assemblies to compose the shared drain. Provider packages stay in the concrete adapter
-projects. A separate `.Core` project would add another public package and dependency layer without
-creating an independent domain contract, so this narrow helper-boundary exception is deliberate.
+The adapter extension surface is intentionally limited to the contracts and models required for
+concrete adapter assemblies to compose the shared drain. Provider packages stay in the concrete
+adapter projects. A separate `.Core` project would add another public package and dependency layer
+without creating an independent domain contract, so this narrow helper-boundary exception is
+deliberate.
+
+`DiagnosticsPersistenceObserverRegistrationValidator` is the constitution-mandated
+first-party implementation required by §2.23.3; it is not an adapter extension contract. Its public
+constructor accepts only `IServiceCollection`, and its public validation method owns observer
+conflict detection and the actionable result. An internal Options adapter delegates .NET
+`ValidateOnStart` into that implementation without creating another public implementation or
+extension seam.
 
 ## Implementable contributor interfaces
 

src/Elsa/Diagnostics/Persistence/Extensions/DiagnosticsPersistenceObserverRegistrationValidator.cs

@@ -1,23 +1,58 @@
+using Elsa.Diagnostics.Persistence.Observability;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
 
 namespace Elsa.Diagnostics.Persistence.Extensions;
 
-public sealed class DiagnosticsPersistenceObserverRegistrationOptions;
+/// <summary>
+/// Validates that diagnostics persistence composition selects at most one observer implementation.
+/// </summary>
+public sealed class DiagnosticsPersistenceObserverRegistrationValidator(IServiceCollection services)
+{
+    /// <summary>Returns a failed result that names every conflicting registration, or success.</summary>
+    public ValidateOptionsResult Validate()
+    {
+        var observers = services
+            .Where(descriptor => descriptor.ServiceType == typeof(IDiagnosticsPersistenceObserver))
+            .ToArray();
+        if (observers.Length <= 1)
+            return ValidateOptionsResult.Success;
+
+        var selection = DiagnosticsPersistenceRegistration.FindObserverSelection(services);
+        var implementations = observers
+            .Select(descriptor => DescribeObserverDescriptor(descriptor, selection))
+            .ToArray();
+        var message =
+            $"Diagnostics replacement contract '{typeof(IDiagnosticsPersistenceObserver).FullName}' has conflicting " +
+            $"registrations: {string.Join(", ", implementations)}. Select one observer explicitly through " +
+            $"'{nameof(DiagnosticsPersistenceRegistration.ReplaceDiagnosticsStore)}'.";
+        return ValidateOptionsResult.Fail(message);
+    }
+
+    private static string DescribeObserverDescriptor(
+        ServiceDescriptor descriptor,
+        (ServiceDescriptor ContractDescriptor, Type ImplementationType)? selection)
+    {
+        if (selection is { } selected && ReferenceEquals(descriptor, selected.ContractDescriptor))
+            return selected.ImplementationType.ToString();
+
+        if (descriptor.ImplementationType is { } implementationType)
+            return implementationType.ToString();
 
-public sealed record DiagnosticsPersistenceObserverRegistrationState(IServiceCollection Services);
+        if (descriptor.ImplementationInstance is { } implementationInstance)
+            return implementationInstance.GetType().ToString();
 
-public sealed class DiagnosticsPersistenceObserverRegistrationValidator(
-    DiagnosticsPersistenceObserverRegistrationState state)
+        return $"factory registration for '{typeof(IDiagnosticsPersistenceObserver).FullName}'";
+    }
+}
+
+internal sealed class DiagnosticsPersistenceObserverRegistrationOptions;
+
+internal sealed class DiagnosticsPersistenceObserverRegistrationOptionsAdapter(
+    DiagnosticsPersistenceObserverRegistrationValidator validator)
     : IValidateOptions<DiagnosticsPersistenceObserverRegistrationOptions>
 {
     public ValidateOptionsResult Validate(
         string? name,
-        DiagnosticsPersistenceObserverRegistrationOptions options)
-    {
-        var message = DiagnosticsPersistenceRegistration.GetObserverConflictMessage(state.Services);
-        return message is null
-            ? ValidateOptionsResult.Success
-            : ValidateOptionsResult.Fail(message);
-    }
+        DiagnosticsPersistenceObserverRegistrationOptions options) => validator.Validate();
 }

src/Elsa/Diagnostics/Persistence/Extensions/DiagnosticsPersistenceRegistration.cs

@@ -103,6 +103,15 @@ public static IServiceCollection AddDiagnosticsPersistenceObservability(this ISe
             .Select(item => item.Selection! with { Descriptor = item.Descriptor })
             .SingleOrDefault();
 
+    internal static (ServiceDescriptor ContractDescriptor, Type ImplementationType)? FindObserverSelection(
+        IServiceCollection services)
+    {
+        var selection = FindSelection<IDiagnosticsPersistenceObserver>(services);
+        return selection is null
+            ? null
+            : (selection.ContractDescriptor, selection.ImplementationType);
+    }
+
     private static void ValidateLifetime(ServiceLifetime lifetime)
     {
         if (!Enum.IsDefined(lifetime))
@@ -111,55 +120,21 @@ private static void ValidateLifetime(ServiceLifetime lifetime)
 
     private static void RejectObserverConflicts(IServiceCollection services)
     {
-        var message = GetObserverConflictMessage(services);
-        if (message is not null)
-            throw new InvalidOperationException(message);
-    }
-
-    internal static string? GetObserverConflictMessage(IServiceCollection services)
-    {
-        var observers = services
-            .Where(descriptor => descriptor.ServiceType == typeof(IDiagnosticsPersistenceObserver))
-            .ToArray();
-        if (observers.Length <= 1)
-            return null;
-
-        var selection = FindSelection<IDiagnosticsPersistenceObserver>(services);
-        var implementations = observers
-            .Select(descriptor => DescribeObserverDescriptor(descriptor, selection))
-            .ToArray();
-        return
-            $"Diagnostics replacement contract '{typeof(IDiagnosticsPersistenceObserver).FullName}' has conflicting " +
-            $"registrations: {string.Join(", ", implementations)}. Select one observer explicitly through " +
-            $"'{nameof(ReplaceDiagnosticsStore)}'.";
-    }
-
-    private static string DescribeObserverDescriptor(
-        ServiceDescriptor descriptor,
-        DiagnosticsStoreSelection? selection)
-    {
-        if (selection is not null && ReferenceEquals(descriptor, selection.ContractDescriptor))
-            return selection.ImplementationType.ToString();
-
-        if (descriptor.ImplementationType is { } implementationType)
-            return implementationType.ToString();
-
-        if (descriptor.ImplementationInstance is { } implementationInstance)
-            return implementationInstance.GetType().ToString();
-
-        return $"factory registration for '{typeof(IDiagnosticsPersistenceObserver).FullName}'";
+        var result = new DiagnosticsPersistenceObserverRegistrationValidator(services).Validate();
+        if (result.Failed)
+            throw new InvalidOperationException(result.Failures.Single());
     }
 
     private static void AddObserverRegistrationValidation(IServiceCollection services)
     {
         if (services.Any(descriptor =>
-                descriptor.ServiceType == typeof(DiagnosticsPersistenceObserverRegistrationState)))
+                descriptor.ServiceType == typeof(DiagnosticsPersistenceObserverRegistrationValidator)))
             return;
 
-        services.AddSingleton(new DiagnosticsPersistenceObserverRegistrationState(services));
+        services.AddSingleton(new DiagnosticsPersistenceObserverRegistrationValidator(services));
         services.AddSingleton<
             IValidateOptions<DiagnosticsPersistenceObserverRegistrationOptions>,
-            DiagnosticsPersistenceObserverRegistrationValidator>();
+            DiagnosticsPersistenceObserverRegistrationOptionsAdapter>();
         services.AddOptions<DiagnosticsPersistenceObserverRegistrationOptions>().ValidateOnStart();
     }
 

tests/Elsa/Diagnostics/Persistence/Tests/DiagnosticsDocumentationTests.cs

@@ -19,7 +19,8 @@ public void Owning_extension_point_catalog_declares_public_seam_semantics_and_he
         Assert.Contains("conflict", catalog, StringComparison.OrdinalIgnoreCase);
         Assert.Contains("helper boundary", catalog, StringComparison.OrdinalIgnoreCase);
         Assert.Contains("DiagnosticsPersistenceObserverRegistrationValidator", catalog, StringComparison.Ordinal);
-        Assert.Contains("constitution-mandated first-party implementation", catalog, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("constitution-mandated", catalog, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("first-party implementation", catalog, StringComparison.OrdinalIgnoreCase);
         Assert.Contains("internal Options adapter", catalog, StringComparison.Ordinal);
         Assert.Contains("not an adapter extension contract", catalog, StringComparison.OrdinalIgnoreCase);
         Assert.Contains("## Overridable contracts", catalog, StringComparison.Ordinal);

tests/Elsa/Diagnostics/Persistence/Tests/DiagnosticsPersistenceObserverRegistrationValidatorTests.cs

@@ -36,6 +36,39 @@ public void Validate_WhenObserversConflict_FailsWithActionableDescriptions()
         Assert.Contains(nameof(DiagnosticsPersistenceRegistration.ReplaceDiagnosticsStore), message, StringComparison.Ordinal);
     }
 
+    [Fact]
+    public void Validate_WhenTrackedDefaultConflictsWithDirectObserver_DescribesSelectedImplementation()
+    {
+        var services = new ServiceCollection();
+        services.AddDiagnosticsPersistenceObservability();
+        services.AddSingleton<IDiagnosticsPersistenceObserver, SecondObserver>();
+        var validator = new DiagnosticsPersistenceObserverRegistrationValidator(services);
+
+        var result = validator.Validate();
+
+        Assert.True(result.Failed);
+        var message = Assert.Single(result.Failures);
+        Assert.Contains(typeof(DiagnosticsPersistenceCounters).FullName!, message, StringComparison.Ordinal);
+        Assert.Contains(typeof(SecondObserver).FullName!, message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Validate_WhenInstanceAndFactoryObserversConflict_DescribesBothRegistrationForms()
+    {
+        var observer = new FirstObserver();
+        var services = new ServiceCollection();
+        services.AddSingleton<IDiagnosticsPersistenceObserver>(observer);
+        services.AddSingleton<IDiagnosticsPersistenceObserver>(_ => new SecondObserver());
+        var validator = new DiagnosticsPersistenceObserverRegistrationValidator(services);
+
+        var result = validator.Validate();
+
+        Assert.True(result.Failed);
+        var message = Assert.Single(result.Failures);
+        Assert.Contains(observer.GetType().FullName!, message, StringComparison.Ordinal);
+        Assert.Contains("factory registration", message, StringComparison.Ordinal);
+    }
+
     private sealed class FirstObserver : TestObserver;
     private sealed class SecondObserver : TestObserver;