Skip to content

test: goldens that grow a lineage and draw a clone size - #52

Merged
MuteJester merged 2 commits into
masterfrom
engine/lineage-portability
Nov 5, 2026
Merged

MuteJester merged 2 commits into
masterfrom
engine/lineage-portability

Conversation

@MuteJester

Copy link
Copy Markdown
Owner

determinism.rs promises: "one seed and one determinism version give one
answer, on every platform the library builds on."
This PR tests the second
half of that sentence for the clonal paths, where it has never been tested.

The gap

The cross-platform check — test_output_matches_the_committed_golden, the only
thing in the suite that compares platforms at all — can only cover code the
fixtures run. No fixture grew a lineage or drew a clone size. That is
exactly where the engine's transcendental arithmetic lives:

site functions decides
lineage/poisson.rs:26 exp every offspring count, so the whole topology
lineage/affinity.rs:209,221 exp every affinity, and under selection the genealogy
lineage/clone_size.rs:33 ln, sqrt, cos lognormal clone sizes (Box–Muller)
lineage/clone_size.rs:43,46 powf power-law clone sizes
lineage/clone_size.rs:52 exp lognormal clone sizes

Rust documents the precision of all of these as platform-dependent. Nothing
rounds the difference away afterwards — a clone size is x.round() of a powf
(clone_size.rs:47), so one ulp is a different integer, not a different
last digit, and lineage_affinity is exported at full f64 precision.

A fixed SplitMix stream makes the draws identical everywhere. It says nothing
about what those draws are then turned into.

The symptom was in plain sight: determinism versions 3 and 4 both passed
through tests/support/golden.py moving nothing but the determinism_version
column. The fixtures could not see the model they were stamping.

golden.py's own docstring already names the principle — "the cross-platform
claim is only made about code the fixtures run"
— and records an earlier
instance of the same gap, when no fixture drew a substitution and changing the
replacement-base model for every substitution pass moved no golden byte.

The experiment

Four fixtures, deliberately small, chosen to reach all five sites:

fixture reaches sensitivity
clonal_lineage poisson.rs exp 10 rows, lineage_abundance varies
clonal_lineage_selected affinity.rs exp 12 rows, lineage_affinity at full f64 — 0.8564151774836135
clonal_power_law clone_size.rs powf duplicate_count 4, 1, 1, 1
clonal_lognormal clone_size.rs ln/sqrt/cos/exp duplicate_count 4, 1, 15, 5

Each was checked to vary rather than sit constant: a fixture whose column holds
one value throughout would pass on every platform while testing none of this.
lineage_affinity is the sharpest probe available — sixteen significant digits
of exp(-beta · distance), compared byte for byte.

CI runs ubuntu, macos and windows, so merging this is not what matters —
running it is.

Reading the result

  • Green on all 13. The guarantee holds for these paths on these platforms,
    and from here on it is checked rather than asserted: the next change to the
    growth or clone-size arithmetic cannot move a platform silently.
  • Red on macos or windows. The library's headline promise is false for
    lineage output and every clonal dataset's reproducibility claim is
    platform-local. What to do then — pin an audited portable implementation,
    commit canonical tables, or narrow the documented promise — is a decision, and
    deliberately not bundled here.

This is also why it was kept out of #50 and #51 even though both touched this
arithmetic: a finding about portability should not arrive as a red run on a
defect fix.

What this does not establish

Four fixtures, three operating systems, one architecture. It does not cover
aarch64, a different libm, a different Rust version, or the parameter space of
each law. Inputs sitting next to a rounding threshold — a clone size landing on
.5, an affinity near underflow — are untested. Finite goldens support a
policy; they do not prove it.

Also here

The three inventory declarations from #51 are swept. Their changes are in the
baseline now, so they explain nothing and would excuse the next edit to the same
names. That audit runs only on a pull request and only with --declarations, so
master always looks green and the sweep has no signal telling you it is owed.

Gates

pytest 5877 passed / 17 skipped; performance 9 passed serial; cargo 1742 passed
across 6 suites; ruff clean; inventory gate clean with --declarations.

The three entries explained edits from the affinity-translation branch,
which is now in master, so they explain nothing and would excuse the
next edit to the same names. The gate only runs this audit on a pull
request and only with --declarations, so master always looks green and
the sweep has no signal telling you it is owed.
The cross-platform claim is only made about code the fixtures run, and
until now no fixture grew a lineage or drew a clone size. That is
precisely where the engine's transcendental arithmetic is:

  lineage/poisson.rs:26          exp     every offspring count
  lineage/affinity.rs:209,221    exp     every affinity
  lineage/clone_size.rs:33       ln, sqrt, cos   lognormal sizes
  lineage/clone_size.rs:43,46    powf    power-law sizes
  lineage/clone_size.rs:52       exp     lognormal sizes

Rust documents the precision of all of these as platform-dependent, and
nothing rounds the difference away afterwards: a clone size is
`x.round()` of a `powf`, so one ulp is a different integer, and
`lineage_affinity` is exported at full f64 precision.

A fixed SplitMix stream makes the draws identical everywhere. It says
nothing about what those draws are then turned into, which is the half of
the promise in determinism.rs -- "one seed and one determinism version
give one answer, on every platform the library builds on" -- that had no
test at all.

The symptom was in plain sight: determinism versions 3 and 4 both passed
through this file moving nothing but the determinism_version column. The
fixtures could not see the model they were stamping.

Four fixtures, kept deliberately small, chosen to reach all five sites:
a neutral lineage (10 rows, varying lineage_abundance); a selected one
(12 rows, lineage_affinity at sixteen significant digits, e.g.
0.8564151774836135, which is the sharpest probe available); a power-law
repertoire (duplicate_count 4, 1, 1, 1); and a lognormal one
(4, 1, 15, 5), which reaches Box-Muller's ln, sqrt and cos where powf
alone does not.

Each was checked to vary rather than sit constant -- a fixture whose
column is the same value throughout would pass on every platform while
testing none of this.

This answers nothing by itself. CI runs ubuntu, macos and windows, so
pushing it is the experiment. Green means the guarantee holds for these
paths on these platforms and is checked from here on rather than
asserted. Red on one of them means the headline promise is false for
lineage output, and what to do about it -- pin an audited portable
implementation, commit canonical tables, or narrow the documented
promise -- is a decision, not a cleanup.

Four fixtures on three operating systems and one architecture is not a
proof. It does not cover aarch64, another libm, or inputs sitting next to
a rounding threshold.
@MuteJester
MuteJester merged commit 059ebfd into master Nov 5, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant