refactor: wire sample_hidden_graph RNG through RNGRoot

[shaypal5]

Summary

• Change sample_hidden_graph() to accept an RNGRoot instance instead of a bare int seed, aligning it with the cross-component RNG convention established in PR refactor: pipeline RNG convention + warnings.warn #34
• Old seed: int interface preserved with DeprecationWarning for backward compatibility
• All callers (generator.py, spike_category_signal.py) and tests updated

Closes #9

Test plan

• All 740 tests pass (pytest -x -q)
• ruff check . clean
• ruff format --check . clean
• Determinism preserved: same seed → same graph (existing test_same_seed_same_graph)
• Deprecation warnings tested: test_deprecated_int_seed_warns, test_deprecated_seed_kwarg_warns

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refactors leadforge.structure.sampler.sample_hidden_graph() to take an RNGRoot so the hidden-graph sampler follows the project-wide RNGRoot substream convention for reproducible, cross-component randomness (Issue #9 / PR #34 alignment).

Changes:

• Update sample_hidden_graph() to accept RNGRoot as the primary input and seed NumPy via a named child stream (hidden_graph).
• Preserve the old seed/int usage paths with DeprecationWarning for backward compatibility.
• Update all in-repo call sites (Generator + script) and test suite callers to pass RNGRoot(...), and add warning tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
leadforge/structure/sampler.py	Changes sample_hidden_graph API to accept RNGRoot, adds deprecation warnings for legacy seed usage.
leadforge/api/generator.py	Updates generator to call sample_hidden_graph(RNGRoot(config.seed)).
scripts/spike_category_signal.py	Updates script pipeline to call sample_hidden_graph(RNGRoot(config.seed)).
tests/structure/test_sampler.py	Updates tests to pass RNGRoot, adds deprecation warning assertions.
tests/simulation/test_population.py	Updates population tests to pass RNGRoot(seed) into sampler.
tests/simulation/test_engine.py	Updates engine tests to pass RNGRoot(seed) into sampler.
tests/render/test_snapshot_windowed.py	Updates snapshot determinism tests to pass RNGRoot(seed).
tests/render/test_render.py	Updates render determinism/snapshot tests to pass RNGRoot(seed).
.agent-plan.md	Documents the sampler RNG refactor checklist for PR tracking.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

This run includes unresolved review comments on PR #35 in repository https://github.com/leadforge-dev/leadforge

For each unresolved review comment, recommend one of: resolve as irrelevant, accept and implement
the recommended solution, open a separate issue and resolve as out-of-scope for this PR, accept and
implement a different solution, or resolve as already treated by the code.

After I reply with my decision per item, implement the accepted actions, resolve the corresponding
PR comments, and push all of these changes in a single commit.

# Copilot Comments

## COPILOT-1
Location: leadforge/structure/sampler.py:53
URL: https://github.com/leadforge-dev/leadforge/pull/35#discussion_r3172327963
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The docstring’s `Raises:` section no longer documents input-validation errors, but `sample_hidden_graph()` can raise `TypeError` (missing/invalid `rng_root`) and `ValueError`/`TypeError` from `RNGRoot` construction when using deprecated seed paths. Consider documenting these exceptions so callers know what to expect.

## COPILOT-2
Location: leadforge/structure/sampler.py
URL: https://github.com/leadforge-dev/leadforge/pull/35#discussion_r3172327983
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The backward-compat branch will override an explicitly provided RNGRoot if `seed` is also passed (e.g., `sample_hidden_graph(RNGRoot(1), seed=2)`), which is surprising and can lead to silently using the wrong RNG. Consider rejecting ambiguous calls (both `rng_root` and `seed`/int provided) with a `TypeError` rather than picking one branch.

## COPILOT-3
Location: leadforge/structure/sampler.py
URL: https://github.com/leadforge-dev/leadforge/pull/35#discussion_r3172327991
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    `isinstance(rng_root, int)` will treat `True`/`False` as ints, emit a DeprecationWarning, and then fail inside `RNGRoot(True)` with a `TypeError`. It would be cleaner to special-case `bool` (and generally validate `rng_root` is an `RNGRoot`) so callers get a direct, non-deprecated type error without an unrelated deprecation warning.

## COPILOT-4
Location: leadforge/structure/sampler.py
URL: https://github.com/leadforge-dev/leadforge/pull/35#discussion_r3172327996
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    If `rng_root` is neither an `int`/`None` nor an `RNGRoot` instance (e.g. a `np.random.Generator`), the function will currently reach `rng_root.child(...)` and raise an `AttributeError`. Consider adding an explicit `isinstance(rng_root, RNGRoot)` check and raising `TypeError` with a clear message to keep the public API predictable.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 25205057986 attempt 1
Comment timestamp: 2026-05-01T06:27:46.091036+00:00
PR head commit: 7783db9cd29fc680d4d07dec799a27f035ef8c06