Problem
Dummies' determinism machinery is correctly implemented at the hard level (late-bound source resolution; correct AsyncLocal/ExecutionContext scope and restore). But the contract has undocumented edges, and its ADR anchor was lost: it was decided in ADR-0006, now Superseded by ADR-0026 and originally scoped to FirstClassErrors.Testing. ADR-0026's decision is about rebasing Testing, not about Dummies' own ambient-source contract. A future maintainer asking "why AsyncLocal and not a parameter? why is a raced System.Random acceptable?" finds the reasoning only in a superseded record.
The undocumented edges:
- Concurrency inside a seeded scope. An
AsyncLocal copies the reference, so Task.Run/Parallel.ForEach children inside a Reproducibly body share one SeededRandom. Their draw order becomes scheduler-dependent (so the reported seed no longer replays the run), and System.Random is not thread-safe — netstandard2.0 has no thread-safe alternative, and a raced Random on .NET Framework can degrade to returning zeros. The docs cover parallelism across tests but say nothing about parallelism within a body.
- Cross-version / cross-runtime seed stability. The package says "any run is reproducible from a reported seed" with no qualification. Across library versions, any change to draw order or count silently changes every sequence; ADR-0025 already acknowledges consumers may rely on generated shapes. Across runtimes the common surface should agree (legacy
Random algorithm) but this is untested (see the net472/cross-TFM issue).
- Replay fidelity of an unwrapped run. Outside
Reproducibly, the first draw in a logical flow pins the seed; draws made before the failing block in the same flow consume from the same sequence, so replaying "just the body" can diverge.
Impact
The crown-jewel guarantee is anchored only in XML docs and a superseded ADR, and its real limits (concurrency, versioning) are invisible to users and to a maintainer auditing the design.
Direction
- Document the edges where users look: on
Reproducibly ("a seeded run is single-logical-flow; concurrent draws inside the body are neither replayable nor thread-safe"); a cross-version stability policy in the README (promise stability within a package version, disclaim it across versions — the mature stance, as FsCheck and AutoFixture both adopted); and one sentence in the user guide that replay fidelity starts at the scope boundary.
- Draft one Proposed ADR — e.g. "Dummies supplies arbitrary values from an ambient, seedable, execution-context-local source with opt-in reproducibility" — carrying ADR-0006's rationale forward, scoped to Dummies, and settling these edges plus the closed
IHasRandomSource seam in one place. Per repo convention, an agent drafts as Proposed; @reefact accepts.
Acceptance criteria
Reproducibly's XML docs and the user guide state the single-logical-flow restriction.
- The README/package description carries the cross-version seed-stability policy.
- A
Proposed ADR records the seedable-source contract for Dummies (rationale, alternatives, the concurrency and cross-version decisions), indexed and linked.
- No behavioral change is required by this issue (the seed-report and exhaustion-message behaviors are tracked separately).
Context
Surfaced by the 2026-07-20 architecture & design audit of the standalone Dummies library (doc/handwritten/for-maintainers/audit/2026-07-20-dummies-architecture-and-design-audit.md, §4.5/§5/§7.3; branch claude/dummies-architecture-audit-cru5aq).
Filed from the Claude Code session that produced the 2026-07-20 Dummies architecture & design audit: https://claude.ai/code/session_01GvrWFVoG74xiys3oyEft1G
Problem
Dummies' determinism machinery is correctly implemented at the hard level (late-bound source resolution; correct
AsyncLocal/ExecutionContextscope and restore). But the contract has undocumented edges, and its ADR anchor was lost: it was decided in ADR-0006, now Superseded by ADR-0026 and originally scoped toFirstClassErrors.Testing. ADR-0026's decision is about rebasing Testing, not about Dummies' own ambient-source contract. A future maintainer asking "whyAsyncLocaland not a parameter? why is a racedSystem.Randomacceptable?" finds the reasoning only in a superseded record.The undocumented edges:
AsyncLocalcopies the reference, soTask.Run/Parallel.ForEachchildren inside aReproduciblybody share oneSeededRandom. Their draw order becomes scheduler-dependent (so the reported seed no longer replays the run), andSystem.Randomis not thread-safe — netstandard2.0 has no thread-safe alternative, and a racedRandomon .NET Framework can degrade to returning zeros. The docs cover parallelism across tests but say nothing about parallelism within a body.Randomalgorithm) but this is untested (see the net472/cross-TFM issue).Reproducibly, the first draw in a logical flow pins the seed; draws made before the failing block in the same flow consume from the same sequence, so replaying "just the body" can diverge.Impact
The crown-jewel guarantee is anchored only in XML docs and a superseded ADR, and its real limits (concurrency, versioning) are invisible to users and to a maintainer auditing the design.
Direction
Reproducibly("a seeded run is single-logical-flow; concurrent draws inside the body are neither replayable nor thread-safe"); a cross-version stability policy in the README (promise stability within a package version, disclaim it across versions — the mature stance, as FsCheck and AutoFixture both adopted); and one sentence in the user guide that replay fidelity starts at the scope boundary.IHasRandomSourceseam in one place. Per repo convention, an agent drafts asProposed;@reefactaccepts.Acceptance criteria
Reproducibly's XML docs and the user guide state the single-logical-flow restriction.ProposedADR records the seedable-source contract for Dummies (rationale, alternatives, the concurrency and cross-version decisions), indexed and linked.Context
Surfaced by the 2026-07-20 architecture & design audit of the standalone
Dummieslibrary (doc/handwritten/for-maintainers/audit/2026-07-20-dummies-architecture-and-design-audit.md, §4.5/§5/§7.3; branchclaude/dummies-architecture-audit-cru5aq).Filed from the Claude Code session that produced the 2026-07-20 Dummies architecture & design audit: https://claude.ai/code/session_01GvrWFVoG74xiys3oyEft1G