function
shard_key
beam_agents.keys.shard_key
shard_key(key: 'bytes', n: 'int', *, payload: 'bytes') -> 'bytes'Docstring
Return the physical shard key key + b"#" + <index> for payload.
The index is int.from_bytes(sha256(payload).digest()[:8]) % n — a pure
function of (payload, n). It depends on nothing else: not process or
worker identity, not element order, not the wall clock, and never on
Python's hash(), which is salted per process by PYTHONHASHSEED and
would hand the same element to different shards on different workers. That
determinism is what preserves (key, seq) replay-cache identity and
byte-identical intent_ids across a bundle retry.
n = 1 still appends #0: the shape of a sharded key never depends on
the shard count, so unshard_key works uniformly. n < 1 raises
ValueError.
Note the convention's one ambiguity (mirrored in :func:unshard_key): a
logical key that itself ends in #<digits> is indistinguishable from
an already-sharded key, so such keys should not be sharded.