Skip to content

[T-002c] core.seeding: hierarchical derive_seed() with stable hashing and golden values #17

Closed

Description

@CodewithJha

Task T-002c · Milestone M1 — Foundation · Size XS · Priority P0 · Epic #1

Implements FR-REP-002 · NFR-REP-001

Branch feat/t-002c-core-seeding-hierarchical-derive-seed — one task = one branch = one PR (doc 32 §6)

Summary

Implement the seed derivation tree of doc 21 §3 / ADR-0014: derive_seed(root, *path) and make_rng(root, *path) -> np.random.Generator, reproducible across processes and platforms.

Context / motivation

Reproducibility (bit-identical kinematic2d replays, common random numbers across strategies in experiments) depends entirely on deterministic, collision-resistant seed derivation. Python's hash() is salted per process and must never be used.

Scope

In scope

  • stable_hash(part: str | int) -> int = first 4 bytes of SHA-256 of the UTF-8 repr, big-endian.
  • derive_seed(root: int, *path: str | int) -> int using np.random.SeedSequence(root, spawn_key=tuple(stable_hash(p) for p in path)).generate_state(1, np.uint64)[0] & (2**63 - 1).
  • make_rng(root, *path) → np.random.Generator(np.random.PCG64(derive_seed(...))).
  • random_campaign_seed(rng) for user-less seeds (63-bit).

Implementation guidance

  • File backend/src/roboprobe/core/seeding.py.
  • Canonical stream keys (document as constants with docstrings, they are identifiers not tunables): "strategy", "run", "analysis", "rep", sub-streams "sensor", "perception", "localization", "simulator".
  • Golden values: commit a small table of (root, path) → seed in the test; these values become part of the reproducibility contract (changing them is a breaking change, doc 33 §6).
  • Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff PLR2004); public APIs typed (mypy strict) and documented.

Acceptance criteria

  • Golden values identical on Linux/macOS/Windows CI runners and across two separate processes.
  • Different paths give different seeds (no collisions over 100 000 random paths in a property test).
  • Result always fits in 63 bits.
  • 100 % coverage.
  • Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
  • Docs, config reference and CHANGELOG Unreleased updated where behaviour, keys or interfaces changed.
  • Definition of Done (doc 32 §3) satisfied.

Tests required

  • tests/unit/core/test_seeding.py with golden table.
  • Hypothesis property test for range and determinism.
  • Subprocess test comparing values from a fresh interpreter.

Dependencies

Blocked by: #12 (T-001)

Blocks: #45 (T-031a), #46 (T-031b), #106 (T-101a), #108 (T-102a)

Parallelization notes

Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:

  • backend/src/roboprobe/core/seeding.py
  • backend/tests/unit/core/test_seeding.py

Independent single file.

Definition of Done

Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-002c (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.

References

Design docs: doc 21 §3 · ADR-0014 · doc 33 §6

Requirements: FR-REP-002 · NFR-REP-001 (traceability: doc 28)

External:

Activity

  1. added this to the M1 — Foundation milestone on Nov 19, 2026
  2. added
    area:coreDomain core, plugin registry, shared types
    priority:P0Critical path / blocks others
    taskChild task of a milestone epic
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:coreDomain core, plugin registry, shared typesgood first issueGood for newcomersmilestone:M1M1 — Foundationpriority:P0Critical path / blocks otherssize:XS< 2 hourstaskChild task of a milestone epictype:featureNew functionality

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions