src/aamcq/utils/seeding.py

"""Deterministic seed derivation."""

from __future__ import annotations

import hashlib


def item_seed(item_id: str, master_seed: int = 0, purpose: str = "") -> int:
    """Derive a 32-bit seed from (item_id, master_seed, purpose).

    Stable across runs and across machines — we rely on SHA-256, not Python's
    string hash randomization.
    """
    blob = f"{master_seed}|{item_id}|{purpose}".encode("utf-8")
    digest = hashlib.sha256(blob).digest()
    return int.from_bytes(digest[:4], "big", signed=False)