Dummies: Define and document the contract of implicit generator conversions

[Reefact]

Problem

Concrete Dummies generators implicitly convert to their generated value type, which makes explicitly typed assignments concise:

string reference = Any.String().StartingWith("ORD-");

The same syntax is misleading in other C# contexts:

var reference = Any.String().StartingWith("ORD-"); // AnyString, not string

Calls through object, generic APIs or competing overloads can also box or pass the generator instead of triggering the conversion. The test suite already has to use explicitly typed locals around string.Join(params object[]) for this reason.

Impact

Users can accidentally retain a mutable-looking recipe where they expected a materialized value, generate more than once, or observe a generator's ToString() output in APIs accepting object. These failures are surprising because the implicit conversion makes generator and generated value appear interchangeable only in some language contexts.

Direction

Make the intended contract explicit before the public API stabilizes.

The preferred direction is to keep implicit conversions as assignment convenience while documenting .Generate() as the canonical, unambiguous materialization operation. The documentation should explain where conversions do and do not run and provide guidance for var, object, generic methods, collections and overload resolution.

An analyzer may be considered separately, but is not required by this issue.

Acceptance criteria

• The public documentation states whether implicit conversions are a stable part of the API.
• .Generate() is presented as the canonical form whenever the target type is not explicit.
• Documentation includes examples for explicitly typed assignment, var, object/boxing and generic APIs.
• Tests preserve the chosen behavior and cover the most misleading compiler-resolution cases.
• The decision is recorded before a stable 1.0 API is published.

Context

Surfaced during a focused review of the standalone Dummies library.

[Reefact]

Direction: remove the implicit conversions; make .Generate() the single materialization

After weighing the two options, I'm taking the opposite direction from the issue's stated preference ("keep + document"): I'm removing the implicit conversions on the concrete generators and making .Generate() the one, canonical way to materialize a value.

The deciding reason is not ergonomics but semantics. An implicit conversion is expected to be cheap, total, and referentially transparent. This one is none of those:

• it draws randomness (an effect), not a widening;
• it can throw (AnyGenerationException, ConflictingAnyConstraintException) at a site that reads like a plain assignment;
• it yields a different value every time it runs — EachConversionDrawsAFreshValue even enshrines this. Reading the "same" variable twice gives two values, which is a property no one expects from something typed as string.

That's an effectful, non-idempotent, throwing method call disguised behind =, which is exactly off-thesis for a library whose selling point is making intent legible.

The supporting points:

• The conversion fires only in one shape (explicitly-typed local/parameter) and silently misbehaves in the adjacent ones (var, object/boxing, params object[], generic inference, competing overloads) — as this issue documents. "Keep + document" documents a hazard instead of removing it; the hazard is accidental complexity we can simply delete, because…
• ….Generate() is already the canonical, uniform path: it flows through IAny<T>, powers As/Combine, behaves identically in every context, and is already the dominant idiom in the suite. The library loses no capability — only a shorthand that saves a .Generate() in one context.
• The cost is near-zero now: Dummies is pre-1.0, standalone, and consumed only by its own tests (ADR-0011 notes the API churns most in these early iterations). Removing a public operator surface after 1.0 would be a breaking change — this is the cheapest possible moment.

Honest counter-argument. The headline call site loses conciseness (string code = Any.String()… gains a .Generate()), and an analyzer could keep the shorthand while flagging the traps. I don't think it's worth it: that would be 28 operators plus a whole analyzer to maintain forever to preserve a one-call shorthand, versus one obvious way that cannot be misused. The analyzer the issue mentions as optional becomes moot once the operators are gone.

I'll record this in an ADR (drafted as Proposed) and update the docs and tests accordingly. Final call on accepting the ADR is the maintainer's.

---

Generated by Claude Code