django-data-shape 0.13.0__tar.gz → 0.14.0__tar.gz

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/CHANGELOG.md

@@ -7,6 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-09-03
+
+### Added
+
+- **`Paired` fills the second key of a many-to-many, and the edge count stays
+  exact.** Two fan-outs on one through table are refused because a fan-out is a
+  partition computed from the row index alone, so two of them partition the same
+  rows without either seeing the other -- nothing enumerates the pairs and a
+  collision is a matter of the seed. `person=Paired("company", Zipf())` is the
+  half that looks: `company` partitions the rows as any fan-out does, and within
+  each of its groups `person` takes that many **distinct** partners. A duplicate
+  pair is impossible by construction rather than removed afterwards, so nothing
+  is deduplicated and the build never reports an achieved count against a
+  requested one. The design notes for this milestone had given that up; they
+  were wrong, and the rule that cardinality is declared survives M2M.
+  - **What binds is the busiest group, not the product.** Every row of one
+    group needs a different partner, so the constraint is
+    `largest group <= partners` rather than `rows <= groups x partners` -- and a
+    heavy tail puts a large share of every edge on one group, `Zipf(1.2)` over
+    five thousand of them putting 21% on the top one. A declaration that looks
+    sparse against the product can still be impossible, and it cannot be known
+    until the partition is resolved: this is the one structural refusal that
+    waits for the build rather than firing where the shape is written.
+  - **The second side is derived and approximate, and the numbers are
+    published.** Both marginals plus the edge count is over-determined, and
+    fixing all three is a constraint satisfaction problem that cannot stream
+    into `COPY`. Measured against exact weighted sampling over 200,000 edges,
+    the busiest partner comes out 1.09 times as busy, the 99th percentile about
+    30% high, and about 7% fewer partners are touched.
+  - **Partners are allocated across weight bands and strided within one**, so
+    nothing is ever drawn and asked whether it is taken. Rejection sampling
+    degenerates exactly where the shape is most interesting -- 245 probes per
+    row on that world -- and the usual fix, sampling the ones to leave out when
+    a group wants more than half, is ten times faster and **a different sampling
+    rule**, so a group one row over the halfway mark would get a materially
+    different membership from one row under. The band count is **derived from
+    the declared weights** rather than chosen, which systematic allocation is
+    what makes possible: it converges as bands get finer where largest-remainder
+    runs away, so "enough" is a limit rather than a number somebody tuned.
+
+- **`FanOutPlan.group_of`** answers which parent a row belongs to, which a
+  pairing needs to choose partners inside this row's group.
+
+- **`Projection(..., through=Model)` says which model a derived join runs on.**
+  An abstract base carrying `created_by`/`updated_by` to `User` -- a pattern most
+  Django schemas have -- makes **any two models in the schema joinable**, so the
+  derivation had candidates everywhere and could settle nothing: not for one
+  pair but for every pair, which put the derived form out of reach for a whole
+  application and left `sql=` as the only route to this feature's own motivating
+  example. The refusal now names `through=` first, and names a model that can
+  actually resolve the join rather than the first one alphabetically -- an audit
+  model is reached by two edges from each side, so it is a real candidate and
+  never a usable answer. Where every candidate is reached more than once,
+  `through=` cannot narrow anything and the refusal says so instead of
+  suggesting it.
+
+### Changed
+
+- **The two-fan-out refusal names the declaration that replaces it.** Its remedy
+  used to be a statement of your own, because nothing else could keep the
+  constraint. It now names `Paired` first and keeps `Projection(columns=, sql=)`
+  as the escape hatch for an edge set that has to be a particular one.
+
+### Fixed
+
+- **A rounded `Uniform` can size a fan-out.**
+  `FanOut(Uniform(1, 10, places=0))` was refused with "needs numeric fan-out
+  sizes, but produced `Decimal('3')`" -- which reads as a contradiction, and was
+  one keyword away from `FanOut(Uniform(1, 10))`, the spelling this package's own
+  docstring recommends and two of its refusals suggest. `places=0` is the natural
+  way to say that a fan-out size is a count. The guard was
+  `isinstance(weight, (int, float))` while the next line already did
+  `float(weight)`, so it was stricter than the arithmetic it protected. It is now
+  the numeric tower plus `Decimal`, which `numbers.Real` deliberately excludes,
+  and `Fraction` and numpy scalars come along with it. `bool` stays refused. The
+  message also names a remedy now, which it was alone in not doing.
+
+- **`columns=` accepts the column an `INSERT` actually lists.** The refusal that
+  sends a reader there says "the select's columns are what the insert lists", and
+  what an insert lists for a foreign key is `event_id` -- which was then refused
+  as "no field named event_id". That is a contradiction rather than a correction,
+  and the surrounding documentation reinforced the wrong reading. Both spellings
+  are accepted and resolve to the same column, the messages say so, and the same
+  dict is read for `statistics=` so the two cannot disagree about what a column
+  is called.
+
 ## [0.13.0] — 2026-09-03
 
 ### Added
@@ -881,7 +967,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   into `COPY FROM STDIN`, which psycopg 2 cannot do without materialising them
   first.
 
-[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/Artui/django-data-shape/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/Artui/django-data-shape/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/Artui/django-data-shape/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/Artui/django-data-shape/compare/v0.10.0...v0.11.0

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.13.0
+Version: 0.14.0
 Summary: A realistically shaped test database from Django models: declare cardinality, skew and fan-out, load by COPY, and make the query planner believe it.
 Project-URL: Homepage, https://github.com/Artui/django-data-shape
 Project-URL: Repository, https://github.com/Artui/django-data-shape

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/django_data_shape/__init__.py

@@ -39,6 +39,7 @@ from django_data_shape.keys.md5_keys import Md5Keys
 from django_data_shape.keys.sequential_keys import SequentialKeys
 from django_data_shape.keys.sql_keys import SqlKeys
 from django_data_shape.keys.uuid_keys import UuidKeys
+from django_data_shape.paired import Paired
 from django_data_shape.projection import Projection
 from django_data_shape.require_clone_strategy import require_clone_strategy
 from django_data_shape.scale_protocol import ScaleProtocol
@@ -79,6 +80,7 @@ __all__ = [
     "KeyFunction",
     "Md5Keys",
     "KeyStrategy",
+    "Paired",
     "PerParent",
     "Projection",
     "ScaleProtocol",

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/django_data_shape/build.py

@@ -21,10 +21,13 @@ from django_data_shape.generate_rows import generate_rows
 from django_data_shape.invalid_shape import InvalidShape
 from django_data_shape.keys.disjoint import Disjoint
 from django_data_shape.order_tables import order_tables
+from django_data_shape.paired import Paired
+from django_data_shape.paired_plan import PairedPlan
 from django_data_shape.projection import Projection
 from django_data_shape.refuse_queries import refuse_queries
 from django_data_shape.require_postgres import require_postgres
 from django_data_shape.resolve_fan_out import resolve_fan_out
+from django_data_shape.resolve_paired import resolve_paired
 from django_data_shape.shape import Shape
 from django_data_shape.shape_not_empty import ShapeNotEmpty
 from django_data_shape.table import Table
@@ -115,8 +118,8 @@ def build(
             if isinstance(table, Projection):
                 loaded = _project(connection, table, shape.seed)
             else:
-                plans = _resolve(connection, table, shape.seed)
-                loaded = _load(connection, table, shape.seed, plans)
+                plans, pairings = _resolve(connection, table, shape.seed)
+                loaded = _load(connection, table, shape.seed, plans, pairings)
             _reset_sequence(connection, table.model)
             _analyze(connection, table.db_table)
             results.append(TableResult(table=table.db_table, rows=loaded))
@@ -163,11 +166,21 @@ def _project(connection: Any, projection: Projection, seed: int) -> int:
     return inserted
 
 
-def _resolve(connection: Any, table: Table, seed: int) -> dict[str, FanOutPlan]:
-    """Partition each declared relation over the parent keys that exist."""
+def _resolve(
+    connection: Any, table: Table, seed: int
+) -> tuple[dict[str, FanOutPlan], dict[str, PairedPlan]]:
+    """Partition each declared relation over the parent keys that exist.
+
+    Fan-outs first and pairings second, because a pairing chooses partners
+    *inside* the groups a fan-out produced -- so the partition it reads has to
+    exist before it can be resolved. That ordering is the mechanism rather than
+    a detail of this function: it is what makes an edge table one pass.
+    """
     parent_fields = table.parent_fields()
     plans: dict[str, FanOutPlan] = {}
     for name, field in table.relations():
+        if isinstance(table.fields[name], Paired):
+            continue
         plans[name] = resolve_fan_out(
             cast("FanOut", table.fields[name]),
             cast("type[Model]", field.related_model),
@@ -178,7 +191,22 @@ def _resolve(connection: Any, table: Table, seed: int) -> dict[str, FanOutPlan]:
             connection,
             parent_fields.get(name, ()),
         )
-    return plans
+    pairings: dict[str, PairedPlan] = {}
+    for name, field in table.relations():
+        declared = table.fields[name]
+        if not isinstance(declared, Paired):
+            continue
+        pairings[name] = resolve_paired(
+            declared,
+            cast("type[Model]", field.related_model),
+            plans[declared.relation],
+            table.rows,
+            seed,
+            table.db_table,
+            name,
+            connection,
+        )
+    return plans, pairings
 
 
 def _require_empty(connection: Any, table: Table | Projection) -> None:
@@ -228,7 +256,13 @@ def _require_empty(connection: Any, table: Table | Projection) -> None:
 # API reached through Django's cursor wrapper, and it appears on no Django base
 # class, so annotating the real wrapper type would mean asserting the checker
 # out of the way on every line that uses it.
-def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]) -> int:
+def _load(
+    connection: Any,
+    table: Table,
+    seed: int,
+    plans: dict[str, FanOutPlan],
+    pairings: dict[str, PairedPlan],
+) -> int:
     """Stream generated rows into the table, by the fastest route the backend has.
 
     Each declared value is passed through its field's ``get_db_prep_save``
@@ -254,7 +288,7 @@ def _load(connection: Any, table: Table, seed: int, plans: dict[str, FanOutPlan]
     prepare = [pk_field.get_db_prep_save] + [field.get_db_prep_save for _, field in table.columns()]
     rows = (
         tuple(prep(value, connection) for prep, value in zip(prepare, row, strict=True))
-        for row in generate_rows(table, seed, plans)
+        for row in generate_rows(table, seed, plans, pairings)
     )
 
     # The guard is built here rather than inside each route because it belongs

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/django_data_shape/check_constraints.py

@@ -163,8 +163,12 @@ def _check_independent_fan_outs(
     That is why this is otherwise a refusal and not a wider capacity
     calculation: no arithmetic over the two marginals decides it, because the
     failure is that nothing enumerates the combinations at all. Deduplicated edges are a
-    different algorithm rather than a bigger loop, and until they arrive the
-    thing that works is a statement --
+    different algorithm rather than a bigger loop. **That algorithm now exists**
+    as :class:`~django_data_shape.paired.Paired`, which is the remedy this
+    refusal names: one side stays a fan-out and the other takes distinct
+    partners inside its groups, so a duplicate pair is impossible rather than
+    removed. A statement of your own is still the answer for an edge set that
+    has to be a particular one --
     :class:`~django_data_shape.projection.Projection` with ``columns=`` and
     ``sql=`` fills the table from a select that can deduplicate.
     """
@@ -191,10 +195,11 @@ def _check_independent_fan_outs(
         "pairs come out together is an artefact of that index, and two rows sharing a pair is a "
         "matter of the seed. The combinations do fit, which is why the pigeonhole arithmetic "
         "lets this through -- what is missing is anything that enumerates them, and the load "
-        "then fails inside COPY at a row number that moves when the seed does. A deduplicated "
-        f"edge table is filled by a statement rather than by two draws: Projection({where}, "
-        "columns=(...), sql=...) selects the pairs already distinct, which is the form that "
-        "keeps this constraint today."
+        "then fails inside COPY at a row number that moves when the seed does. An edge table "
+        f"declares one side and pairs the other: {fanned[1]}=Paired({fanned[0]!r}, Zipf()) takes "
+        f"distinct partners inside each {fanned[0]} group, so no pair can repeat and the edge "
+        "count is still exactly the row count. An edge set that has to be a particular one is "
+        f"filled by a statement instead -- Projection({where}, columns=(...), sql=...)."
     )
 
 

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/django_data_shape/fan_out_plan.py

@@ -101,6 +101,15 @@ class FanOutPlan:
         end = self._starts[index + 1] if index + 1 < len(self._starts) else self._rows
         return slot - start, end - start
 
+    def group_of(self, row: int) -> int:
+        """Which parent this row belongs to, as an index into the parent keys.
+
+        Public because a paired column needs it: the partner is chosen inside
+        this row's group, so "which group" and "where in it" are both asked of
+        the partition rather than recomputed beside it.
+        """
+        return self._slot(row)
+
     def _slot(self, row: int) -> int:
         """Which parent owns this child row, as an index into ``keys``."""
         slot = (row * self._stride) % self._rows

{django_data_shape-0.13.0 → django_data_shape-0.14.0}/django_data_shape/generate_rows.py

@@ -10,6 +10,8 @@ from django_data_shape.derivations.derivation import Derivation
 from django_data_shape.derivations.scope import Scope
 from django_data_shape.distributions.distribution import Distribution
 from django_data_shape.fan_out_plan import FanOutPlan
+from django_data_shape.paired import Paired
+from django_data_shape.paired_plan import PairedPlan
 from django_data_shape.table import Table
 from django_data_shape.utils import draw, field_stream
 
@@ -20,7 +22,10 @@ _Source = Callable[[int, list[object]], object]
 
 
 def generate_rows(
-    table: Table, seed: int, plans: Mapping[str, FanOutPlan] | None = None
+    table: Table,
+    seed: int,
+    plans: Mapping[str, FanOutPlan] | None = None,
+    pairings: Mapping[str, PairedPlan] | None = None,
 ) -> Iterator[tuple[Any, ...]]:
     """Yield one tuple per row: the primary key, then each declared column.
 
@@ -54,6 +59,7 @@ def generate_rows(
     nothing but peak RSS.
     """
     plans = plans or {}
+    pairings = pairings or {}
     keys = table.keys
     key_stream = field_stream(seed, table.db_table, ":key")
     columns = table.columns()
@@ -64,7 +70,7 @@ def generate_rows(
     # of column this is, and where each of its sources comes from, are decided
     # once rather than a million times.
     steps: list[_Step] = [
-        (slot_of[name], _producer(table, seed, plans, name))
+        (slot_of[name], _producer(table, seed, plans, pairings, name))
         for name, _field in columns
         if name not in table.computation_order()
     ]
@@ -81,12 +87,23 @@ def generate_rows(
 
 
 def _producer(
-    table: Table, seed: int, plans: Mapping[str, FanOutPlan], name: str
+    table: Table,
+    seed: int,
+    plans: Mapping[str, FanOutPlan],
+    pairings: Mapping[str, PairedPlan],
+    name: str,
 ) -> Callable[[int, list[object]], object]:
     """The step for a column that depends on nothing already in the row."""
     plan = plans.get(name)
     if plan is not None:
         return partial(_from_plan, plan)
+    pairing = pairings.get(name)
+    if pairing is not None:
+        # Two questions of the fan-out this pairs with -- which group, and where
+        # in it -- and one of the pairing. All three are O(1) because both are
+        # partitions of the row range rather than per-row draws.
+        declared = cast("Paired", table.fields[name])
+        return partial(_from_pairing, plans[declared.relation], pairing)
     distribution = cast("Distribution", table.fields[name])
     return partial(_from_distribution, distribution, field_stream(seed, table.db_table, name))
 
@@ -149,6 +166,11 @@ def _from_plan(plan: FanOutPlan, row: int, values: list[object]) -> object:
     return plan.key_for(row)
 
 
+def _from_pairing(plan: FanOutPlan, pairing: PairedPlan, row: int, values: list[object]) -> object:
+    position, _size = plan.group_position(row)
+    return pairing.partner_for(plan.group_of(row), position)
+
+
 def _from_derivation(
     derivation: Derivation,
     stream: int,

django_data_shape-0.14.0/django_data_shape/paired.py

@@ -0,0 +1,82 @@
+"""The other end of a many-to-many edge, distinct within its partner's group."""
+
+from __future__ import annotations
+
+from django_data_shape.distributions.distribution import Distribution
+from django_data_shape.invalid_shape import InvalidShape
+
+
+class Paired:
+    """A relation filled with the opposite end of an edge, never repeating a pair.
+
+    The declaration a through table needs, and the reason two
+    :class:`~django_data_shape.fan_out.FanOut` declarations are refused beside
+    one another. Two fan-outs partition the same rows without either seeing the
+    other, so nothing enumerates the pairs and whether two rows collide is a
+    matter of the seed. ``Paired`` is the half that looks:
+
+    .. code-block:: python
+
+        Table(
+            Membership,
+            rows=50_000,
+            company=FanOut(Zipf()),
+            person=Paired("company", Zipf()),
+            role=Constant("member"),
+        )
+
+    ``company`` partitions the rows as any fan-out does -- that is the **declared**
+    degree distribution, and it is exact. Within each of its groups, ``person``
+    takes that many **distinct** partners, so a duplicate pair is impossible by
+    construction rather than removed afterwards: the same company implies a
+    different person, and a different company implies a different pair. The edge
+    count is therefore exactly ``rows``, which is the rule this package holds to
+    everywhere else and which a deduplicating generator would have given up.
+
+    ``relation`` names the fan-out this one is paired with, spelled the way
+    :class:`~django_data_shape.derivations.per_parent.PerParent` names the
+    relation it groups by, and for the same reason: a table with three foreign
+    keys should not make a reader guess which one the grouping is over.
+
+    ``weights`` decides which partners are popular. It is a
+    :class:`~django_data_shape.distributions.distribution.Distribution` over the
+    partner table the same way a fan-out's ``sizes`` is over the parent table,
+    so ``Zipf()`` gives the realistic heavy tail and a flat one gives the
+    uniform shape this package exists to argue against.
+
+    **The second side's marginal is derived, not declared, and that is on
+    purpose.** Both marginals plus the edge count is over-determined: fixing all
+    three is a constraint satisfaction problem, and a CSP cannot stream into
+    ``COPY``. So the edge count and one side's distribution are declared and the
+    other side follows -- and what follows *approximates* ``weights`` rather than
+    reproducing it. Measured against exact weighted sampling without
+    replacement, the busiest partner comes out about 1.1 times as busy, the 99th
+    percentile about 30% high, and about 7% fewer partners are touched at all.
+    Those numbers are in the documentation rather than only here, because a
+    derived shape nobody quotes is a shape nobody can check.
+    """
+
+    def __init__(self, relation: str, weights: Distribution) -> None:
+        if not isinstance(relation, str) or not relation:
+            raise InvalidShape(
+                f"Paired needs the name of the fan-out it is paired with, got {relation!r}. "
+                "A table with more than one foreign key cannot be left to guess which one the "
+                "pairing is over."
+            )
+        self._relation = relation
+        self._weights = weights
+
+    @property
+    def relation(self) -> str:
+        return self._relation
+
+    @property
+    def weights(self) -> Distribution:
+        return self._weights
+
+    def canonical(self) -> object:
+        """The fan-out it pairs with and the weights over partners. See ``Canonical``."""
+        return (self._relation, self._weights)
+
+    def __repr__(self) -> str:
+        return f"Paired({self._relation!r}, {self._weights!r})"

django_data_shape-0.14.0/django_data_shape/paired_plan.py

@@ -0,0 +1,145 @@
+"""Which partner each row of an edge table points at, answered per row."""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+from django_data_shape.utils import draw
+
+
+class PairedPlan:
+    """Distinct partners inside every group, chosen once and read per row.
+
+    The construction, in one sentence: **partners are allocated across weight
+    bands and then strided within a band**, so nothing is ever drawn and asked
+    "is this one taken".
+
+    That is what separates this from the obvious approach. Choosing partners one
+    at a time and rejecting duplicates degenerates exactly where the shape is
+    most interesting -- a group needing most of the partner table probes almost
+    every slot, measured at 245 probes per row on 200,000 edges -- and the usual
+    fix, sampling the ones to *leave out* when a group wants more than half, is
+    ten times faster and **a different sampling rule**, so a group one row over
+    the halfway mark would get a materially different membership from one row
+    under. A cliff at an arbitrary size that no declaration mentions is the kind
+    of thing this package exists to refuse, so neither is what runs here.
+
+    **Allocation across bands is systematic, not largest-remainder**, and that
+    distinction is the whole reason the band count can be derived. Largest
+    remainder is deterministic: the same heavy bands win the fractional top-up
+    in every group, so a band holding one partner is included in nearly every
+    group and its degree runs away -- measured at nearly three times what exact
+    weighted sampling gives, and it never settles as bands get finer. Systematic
+    allocation lays the bands' shares end to end, takes one offset per group and
+    counts the integer points each band's interval covers: the expected count
+    per band is its share, the total is the group's size by construction, and
+    the answer *converges* as bands get finer instead of running away. Because
+    it converges, "enough bands" is a limit rather than an optimum, and a band
+    rule can be stated in weight ratios rather than in a number somebody tuned.
+
+    **What it is, honestly.** The result approximates exact weighted sampling
+    without replacement rather than reproducing it: the busiest partner comes
+    out about 1.1 times as busy, the 99th percentile about 30% high, and about
+    7% fewer partners are touched. It is an approximation with **no tuning
+    parameter**, which is the bar the alternatives failed, and the side it
+    approximates is derived rather than declared -- so nothing here promises a
+    marginal and then misses it.
+    """
+
+    def __init__(
+        self,
+        keys: list[int],
+        sizes: list[int],
+        weights: list[float],
+        bands: list[int],
+        stream: int,
+    ) -> None:
+        self._keys = keys
+        self._sizes = sizes
+        # Three purposes, three streams, rather than one stream and an offset:
+        # an offset is an arithmetic relationship between draws that are
+        # supposed to be independent.
+        self._offsets = stream
+        self._strides = stream ^ 0x9E3779B97F4A7C15
+        self._starts = stream ^ 0xC2B2AE3D27D4EB4F
+        self._members: dict[int, list[int]] = defaultdict(list)
+        for index, band in enumerate(bands):
+            self._members[band].append(index)
+        self._bands = sorted(self._members)
+        self._mass = {band: sum(weights[i] for i in self._members[band]) for band in self._bands}
+        self._total = sum(self._mass.values())
+        # One list per group, built once. The whole partition is O(rows), and a
+        # row reads its own slot -- the alternative, recomputing a group's
+        # partners per row, would be O(rows x group size).
+        self._chosen: list[list[int]] = [self._for_group(g, s) for g, s in enumerate(sizes)]
+
+    def partner_for(self, group: int, position: int) -> int:
+        """The key for the ``position``-th row of ``group``."""
+        return self._keys[self._chosen[group][position]]
+
+    def sizes(self) -> list[int]:
+        """How many rows each group holds, which is the fan-out's own partition."""
+        return list(self._sizes)
+
+    def _for_group(self, group: int, size: int) -> list[int]:
+        chosen: list[int] = []
+        for band, wanted in self._allocate(group, size):
+            people = self._members[band]
+            modulus = len(people)
+            # A distinct draw index per (group, band), and per purpose. Mixing
+            # them arithmetically -- `group * 31 + band` -- collides as soon as
+            # there are more than 31 bands, and two groups sharing a stride is
+            # a correlation nothing in the declaration asked for and nothing in
+            # the output announces.
+            slot = group * len(self._bands) + self._bands.index(band)
+            stride = _stride(modulus, draw(self._strides, slot))
+            start = int(draw(self._starts, slot) * modulus)
+            # A stride coprime with the band size visits every member before
+            # repeating, so `wanted <= modulus` picks are distinct without any
+            # membership test at all.
+            chosen.extend(people[(start + step * stride) % modulus] for step in range(wanted))
+        return chosen
+
+    def _allocate(self, group: int, size: int) -> list[tuple[int, int]]:
+        """How many partners this group takes from each band. Sums to ``size``.
+
+        Systematic: the shares are laid end to end and one offset per group
+        counts the integer points each band covers. A band asked for more than
+        it holds spills into the next with room, which is the only step here
+        that is not purely statistical and is what keeps the total exact when a
+        group is large enough to exhaust the heavy bands.
+        """
+        offset = draw(self._offsets, group)
+        running = 0.0
+        previous = 0
+        wanted: dict[int, int] = {}
+        for band in self._bands:
+            running += size * self._mass[band] / self._total
+            boundary = math.floor(running - offset) + 1
+            wanted[band] = max(0, boundary - previous)
+            previous = boundary
+        spill = 0
+        for band in self._bands:
+            capacity = len(self._members[band])
+            if wanted[band] > capacity:
+                spill += wanted[band] - capacity
+                wanted[band] = capacity
+        for band in self._bands:
+            if not spill:
+                break
+            room = len(self._members[band]) - wanted[band]
+            taken = min(room, spill)
+            wanted[band] += taken
+            spill -= taken
+        return [(band, count) for band, count in wanted.items() if count]
+
+
+def _stride(modulus: int, drawn: float) -> int:
+    """A step coprime with ``modulus``, so stepping by it is a bijection."""
+    if modulus <= 2:
+        return 1
+    stride = 1 + int(drawn * (modulus - 1))
+    while math.gcd(stride, modulus) != 1:
+        stride = stride % (modulus - 1) + 1
+    return stride