[v0.5] ADR: seed and RNG-stream contract across generation stages

[DougManuel]

Part of the post-v0.4.0 development plan (development/post-v040-development-plan.md, Phase 2, Task 5). Design doc first; implementation gated on ADR approval.

Problem

Three seed regimes coexist:

1. Legacy path: global set.seed(seed) at R/create_mock_data.R:325-327, generators receive seed = NULL.
2. v0.4 path: seed for baseline, seed + 1L for post-processing at R/create_mock_data.R:88-90 — the comment itself calls it a pragmatic split.
3. simstudy backend: its own seed handling.

Plus: the v0.4→legacy fallback switches RNG streams for the same seed with only a verbose-gated message (#33 item 11).

Practical collision risk of seed/seed + 1 is low (Mersenne-Twister seed scrambling), but the contract is undefined: what exactly does a user's seed guarantee, across paths and versions?

ADR must decide

1. Stream-derivation scheme — candidates: (a) status quo documented; (b) L'Ecuyer-CMRG sub-streams via parallel::nextRNGStream() per stage (and per variable?); (c) hash-derived per-stage seeds. Recommendation in plan: (b), stage-level.
2. Scope of the guarantee — same seed + same spec + same version ⇒ identical output; explicitly not stable across minor versions when NEWS says so.
3. Migration policy — any change breaks seeded output. Coordinate with the formula evaluator (see companion v0.5 issue) so v0.5 contains exactly one seeded-output break, with one NEWS migration note (precedent: v0.3→v0.4 divergence already documented).
4. Whether the fallback stream-switch message becomes always-on (resolves Follow-ups from PR #32 review: loader validation, strict-mode semantics, doc polish #33 item 11).

Acceptance

• development/adr/v05-seed-contract.md merged after maintainer review.
• Pinned-value regression tests specified (fulfils Add seed reproducibility tests across mock-data generators #22).
• Blocks: correlated-variables work (future issue) — do not start that before this lands.

Relates to #22, #33.

[DougManuel]

ADR accepted and committed to dev (f59197f): development/adr/v05-seed-contract.md.

Decision: full-bundle contract — L'Ecuyer-CMRG stage sub-streams via parallel::nextRNGStream() (base R, no new dependency), unified save/restore isolation across the native/simstudy/legacy paths, RNG-kind pinning confined to the generation scope, and an always-on fallback stream-switch message (resolves #33 item 11). Co-released with #39 so v0.5 carries exactly one seeded-output break.

Key finding during drafting: the three paths differ on two axes, not just the seed/seed+1 split — the legacy path (validate = FALSE) clobbers the caller's global RNG via a bare set.seed(), while the native/simstudy paths already save/restore. The contract unifies this.

Next: an implementation plan (development/plans/), ADR-gated per the post-v0.4.0 plan. Fulfils #22 (adds tests/testthat/test-seed-contract.R). No implementation code written yet.