Module metashift 

Galois LFSR-based deterministic permutation (MetaShift / Shuffle).

Provides bijective, deterministic, O(1)-space permutations of integer ranges. Given a range [0, N), the LFSR visits every value exactly once before cycling, in a pseudo-random order determined by the feedback polynomial.

This is useful for:

• Generating all values in a range without repetition or memory
• Shuffling sequences without materializing them
• Deterministic reordering across distributed workers (via bank selection)

The core algorithm is a Galois-configuration LFSR. The Shuffle Polydat node wraps it with range normalization and rejection sampling.

The feedback polynomial is exposed explicitly as a Const arg so the macro can auto-emit the JIT-eligible compiled_u64 / jit_constants hooks (Setup-derived state would disable the macro’s auto-JIT emission, and the override path can’t capture per-instance constants). Callers compute feedback via feedback_for_width_and_bank or feedback_for_size.

Structs

LfsrStep

Single Galois LFSR step as a Polydat node.

Shuffle

Deterministic, bijective permutation of a bounded integer range.

Functions

feedback_for_size

Convenience: derive a bank-0 feedback polynomial directly from a shuffle size. Callers building a Shuffle node from an outer “size” parameter use this rather than tracking width / bank manually.

feedback_for_width

Return the default (bank 0) feedback polynomial for a given width.

feedback_for_width_and_bank

Return the feedback polynomial for a given register width and bank.

width_for_period

Return the minimum register width needed to represent period values.