refactor(dummies): contextualize replay hints in generation failures

Dummies.UnitTests/CompositionTests.cs

@@ -104,6 +104,38 @@ public void CombineWrapsComposerFailures() {
         Check.That(caught.InnerException).IsInstanceOf<InvalidOperationException>();
     }
 
+    [Fact(DisplayName = "A composer failure over ambient generators reports the Any.Reproducibly replay hint.")]
+    public void CombineOverAmbientGeneratorsReportsReproduciblyHint() {
+        IAny<string> generator = Any.Combine<int, int, string>(
+            Any.Int32().Between(1, 3),
+            Any.Int32().Between(4, 6),
+            (first, second) => throw new InvalidOperationException($"rejected {first}/{second}"));
+
+        AnyGenerationException caught = Assert.Throws<AnyGenerationException>(
+            () => Any.Reproducibly(31415, () => generator.Generate(), _ => { }));
+
+        Check.That(caught.Seed).IsEqualTo(31415);
+        Check.That(caught.Message).Contains("Any.Reproducibly(31415");
+        Check.That(caught.Message).Not.Contains("Any.WithSeed(");
+    }
+
+    [Fact(DisplayName = "A composer failure over an Any.WithSeed(...) context reports the WithSeed replay hint, not the inapplicable Any.Reproducibly instruction.")]
+    public void CombineOverFixedContextReportsWithSeedHint() {
+        AnyContext seeded = Any.WithSeed(4242);
+
+        IAny<string> generator = Any.Combine<int, int, string>(
+            seeded.Int32().Between(1, 3),
+            seeded.Int32().Between(4, 6),
+            (first, second) => throw new InvalidOperationException($"rejected {first}/{second}"));
+
+        AnyGenerationException caught = Assert.Throws<AnyGenerationException>(() => generator.Generate());
+
+        Check.That(caught.Seed).IsEqualTo(4242);
+        Check.That(caught.Message).Contains("Combine(...)");
+        Check.That(caught.Message).Contains("Any.WithSeed(4242)");
+        Check.That(caught.Message).Not.Contains("Any.Reproducibly(");
+    }
+
     [Fact(DisplayName = "Combine composes four through eight parts, passing every constrained part to the lambda.")]
     public void CombineSupportsHigherArities() {
         IAny<int> part = Any.Int32().Between(1, 9);

Dummies.UnitTests/ContinuousExclusionNudgeTests.cs

@@ -71,7 +71,7 @@ public void DoubleExclusionInsideNarrowRange() {
         }
     }
 
-    [Fact(DisplayName = "A range whose every representable value is excluded fails with a seeded AnyGenerationException, not by budget exhaustion.")]
+    [Fact(DisplayName = "A range whose every representable value is excluded fails with a seeded AnyGenerationException whose replay hint points at Any.WithSeed, not the inapplicable Any.Reproducibly.")]
     public void ExhaustedRangeThrowsSeededGenerationException() {
         Half min = (Half)1f;
         Half max = (Half)1.001f;   // exactly two representable Half values in [min, max]
@@ -81,7 +81,10 @@ public void ExhaustedRangeThrowsSeededGenerationException() {
 
         Check.That(thrown.Seed).IsEqualTo(207);
         Check.That(thrown.Message).Contains("207");
-        Check.That(thrown.Message).Contains("Any.Reproducibly(");
+        // The draw came from Any.WithSeed(207) — a fixed context that replays by itself — so the hint must name it,
+        // not the ambient Any.Reproducibly(...) instruction, which would not reproduce this run.
+        Check.That(thrown.Message).Contains("Any.WithSeed(207)");
+        Check.That(thrown.Message).Not.Contains("Any.Reproducibly(");
     }
 
     [Fact(DisplayName = "The nudge stays reproducible: the same seed yields the same value across runs.")]

Dummies/AnyDecimal.cs

@@ -162,9 +162,7 @@ public AnyDecimal DifferentFrom(decimal value) {
 
     /// <inheritdoc />
     public decimal Generate() {
-        SeededRandom current = _source.Current;
-
-        return _spec.Generate(current.Random, current.Seed);
+        return _spec.Generate(_source);
     }
 
 }

Dummies/AnyDerivation.cs

@@ -64,8 +64,8 @@ internal static T Invoke<T>(Func<T> invoke, RandomSource? source, string failure
         } catch (Exception exception) {
             int?   seed    = source?.Current.Seed;
             string message = $"Generation failed: {failure} ({exception.GetType().Name}: {exception.Message}).";
-            if (seed is not null) {
-                message += $" The arbitrary values were seeded with {seed}; reproduce this run with Any.Reproducibly({seed}, ...).";
+            if (source is not null) {
+                message += $" {source.ReplayHint(seed!.Value)}";
             }
 
             throw new AnyGenerationException(message, seed, exception);

Dummies/AnyDouble.cs

@@ -175,9 +175,7 @@ public AnyDouble DifferentFrom(double value) {
 
     /// <inheritdoc />
     public double Generate() {
-        SeededRandom current = _source.Current;
-
-        return _spec.Generate(current.Random, current.Seed);
+        return _spec.Generate(_source);
     }
 
 }

Dummies/AnyGenerationException.cs

@@ -37,9 +37,11 @@ internal AnyGenerationException(string message, int? seed) : base(message) {
     }
 
     /// <summary>
-    ///     The seed of the random context the failing generation drew from, when it is known — pass it to
-    ///     <c>Any.Reproducibly(seed, ...)</c> to replay the run. <c>null</c> when the failing generator does not draw
-    ///     from one of the library's random contexts.
+    ///     The seed of the random context the failing generation drew from, when it is known. Under the ambient context
+    ///     (<c>Any.Reproducibly(...)</c>) pass it to <c>Any.Reproducibly(seed, ...)</c> to replay the run; a value drawn
+    ///     from an <c>Any.WithSeed(seed)</c> context already replays deterministically on its own. The failure message
+    ///     states which of the two applies. <c>null</c> when the failing generator does not draw from one of the
+    ///     library's random contexts.
     /// </summary>
     public int? Seed { get; }
 

Dummies/AnyHalf.cs

@@ -193,9 +193,7 @@ public AnyHalf DifferentFrom(Half value) {
 
     /// <inheritdoc />
     public Half Generate() {
-        SeededRandom current = _source.Current;
-
-        return (Half)_spec.Generate(current.Random, current.Seed);
+        return (Half)_spec.Generate(_source);
     }
 
 }

Dummies/AnySingle.cs

@@ -186,9 +186,7 @@ public AnySingle DifferentFrom(float value) {
 
     /// <inheritdoc />
     public float Generate() {
-        SeededRandom current = _source.Current;
-
-        return (float)_spec.Generate(current.Random, current.Seed);
+        return (float)_spec.Generate(_source);
     }
 
 }

Dummies/CollectionState.cs

@@ -244,11 +244,8 @@ private int ExhaustionBudget(int target) {
     }
 
     private static AnyGenerationException Exhausted(RandomSource source, int reached, int target, string what) {
-        int?   seed    = source.Current.Seed;
-        string message = $"Could not generate a distinct collection of {Elements(target)}: {what} produced only {reached} distinct value(s) before the draw budget was exhausted. Loosen the count or widen the element generator's domain.";
-        if (seed is not null) {
-            message += $" The arbitrary values were seeded with {seed}; reproduce this run with Any.Reproducibly({seed}, ...).";
-        }
+        int    seed    = source.Current.Seed;
+        string message = $"Could not generate a distinct collection of {Elements(target)}: {what} produced only {reached} distinct value(s) before the draw budget was exhausted. Loosen the count or widen the element generator's domain. {source.ReplayHint(seed)}";
 
         return new AnyGenerationException(message, seed);
     }

Dummies/ContinuousIntervalSpec.cs

@@ -171,7 +171,10 @@ internal bool Contains(double value) {
     }
 
     /// <summary>Draws one value satisfying the whole specification.</summary>
-    internal double Generate(Random random, int seed) {
+    internal double Generate(RandomSource source) {
+        SeededRandom current = source.Current;
+        Random       random  = current.Random;
+
         if (_effectiveAllowed is not null) {
             return _effectiveAllowed[random.Next(_effectiveAllowed.Count)];
         }
@@ -191,8 +194,8 @@ internal double Generate(Random random, int seed) {
         double? free = NudgeToFree(candidate, ascending: true) ?? NudgeToFree(candidate, ascending: false);
         if (free is null) {
             throw new AnyGenerationException(
-                $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. The arbitrary values were seeded with {seed}; reproduce this run with Any.Reproducibly({seed}, ...).",
-                seed,
+                $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayHint(current.Seed)}",
+                current.Seed,
                 new InvalidOperationException("No representable value in range remains after applying the exclusions."));
         }
 

Dummies/DecimalIntervalSpec.cs

@@ -36,7 +36,7 @@
 
     #endregion
 
     private DecimalIntervalSpec(string  typeName, Func<decimal, string> render,
                                 decimal min,      string? minConstraint,
                                 decimal max,      string? maxConstraint,
                                 IReadOnlyList<decimal>? allowed, string? allowedConstraint,
@@ -134,7 +134,10 @@
     }
 
     /// <summary>Draws one value satisfying the whole specification.</summary>
-    internal decimal Generate(Random random, int seed) {
+    internal decimal Generate(RandomSource source) {
+        SeededRandom current = source.Current;
+        Random       random  = current.Random;
+
         if (_effectiveAllowed is not null) {
             return _effectiveAllowed[random.Next(_effectiveAllowed.Count)];
         }
@@ -165,8 +168,8 @@
             decimal next = Clamped(candidate + SmallestStep);
             if (next == candidate || budget-- == 0) {
                 throw new AnyGenerationException(
-                    $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. The arbitrary values were seeded with {seed}; reproduce this run with Any.Reproducibly({seed}, ...).",
-                    seed,
+                    $"Generation failed: no {_typeName} value near the drawn candidate satisfies the exclusions. {source.ReplayHint(current.Seed)}",
+                    current.Seed,
                     new InvalidOperationException("The exclusion nudge could not leave the excluded point within the allowed range."));
             }
 

Dummies/RandomSource.cs

@@ -7,11 +7,19 @@
 ///     time — which is what lets a recipe built outside an <c>Any.Reproducibly(...)</c> scope generate
 ///     deterministically inside one.
 /// </summary>
 internal abstract class RandomSource {
 
     /// <summary>The seeded pseudo-random generator to draw from right now.</summary>
     internal abstract SeededRandom Current { get; }
 
+    /// <summary>
+    ///     The reproduction guidance to append to a generation-failure message, phrased for this kind of source. The
+    ///     ambient source points at <c>Any.Reproducibly(seed, ...)</c>; a fixed <c>Any.WithSeed(...)</c> context replays
+    ///     deterministically on its own, so pinning the ambient source would not apply — naming the wrong instruction is
+    ///     exactly the misleading diagnostic this method exists to avoid.
+    /// </summary>
+    internal abstract string ReplayHint(int seed);
+
 }
 
 /// <summary>A pseudo-random generator that remembers the seed it was created from.</summary>
@@ -70,6 +78,10 @@
         }
     }
 
+    internal override string ReplayHint(int seed) {
+        return $"The arbitrary values were seeded with {seed}; reproduce this run with Any.Reproducibly({seed}, ...).";
+    }
+
     #region Nested types
 
     private sealed class SeedScope : IDisposable {
@@ -109,6 +121,10 @@
 
     internal override SeededRandom Current => _random;
 
+    internal override string ReplayHint(int seed) {
+        return $"The arbitrary values were drawn from Any.WithSeed({seed}), which already replays deterministically.";
+    }
+
 }
 
 /// <summary>
@@ -141,7 +157,7 @@
         ulong rangeSize = (ulong)(maxInclusive - minInclusive) + 1UL;
         ulong draw      = random.NextUInt64();
 
         // rangeSize is 0 only when the range spans the full ulong width, which int-derived bounds never do;
         // guard anyway so the helper stays correct if reused with wider bounds.
         if (rangeSize == 0UL) { return unchecked((long)draw); }