docs: make the integration path hard to get wrong; fix what the review found behind it

[vlsi]

Why

Reviewing a fresh integration of this generator (uber/NullAway#1781) turned up seven misses, and six were ones the README could have prevented. They are the same misses every integration rediscovers:

• The seed was never wired. RNG_SEED and GITHUB_PR_NUMBER were documented only in a JSDoc comment, and the README's workflow example set neither, so a workflow copied from it draws a fresh matrix on every push. A failure on an exotic row then vanishes on the next commit, and nobody can tell whether the fix worked or the row simply did not come up again.
• The os axis was left unweighted while allAxisValues('os') guaranteed all three, so most rows landed on the runners that cost 2x and 10x.
• Nothing was said about caching. gradle/actions/setup-gradle hashes the matrix into its cache key, so a randomized matrix stops hitting the matrix-level restore key and writes a new entry per job per run.
• An axis was added that never reached the tests: the JDK vendor changed JAVA_HOME, while the test tasks kept taking their JVM from a toolchain. Seven job names, one set of bytes.
• Only the environment went on axes. The project's own options — where pgjdbc gets most of its value — were not considered.

The seventh was a library gap: pgjdbc guards its coverage row with a hand-written if (!include.some(v => v.collectCoverage)) throw, because its failOnUnsatisfiableFilters is deliberately off. The README points at pgjdbc's matrix.mjs as the current usage, so the workaround propagates without the reason.

Then six rounds of cross review found four defects behind that gap, three in the fix itself. They are in this branch because it made each symptom fatal.

What

A tagged requirement is load-bearing, so the budget reserves a row for it. generateRows throws when a {filter, tag} requirement cannot be satisfied, whether or not failOnUnsatisfiableFilters(true) is set: the tag marks a row a later job keys on, so dropping it leaves a matrix that looks complete while that job never runs. Phase 1 holds a row for each open tagged requirement rather than anchoring them first — anchoring satisfied them and cost them their variety, because the anchor is the row that carries the packing bonus, and on one fixture the tagged row went from a varied partner on 90 of 300 seeds to none. The bonus outweighs every untagged match with one tagged match, but only while the reserve is short.

A filter that pins 0, false or '' is now honored. Axis.pickValue tested its filter for truth, so such a pin was ignored during generation and held only when the draw agreed — 9 of 40 seeds threw at a budget with room to spare. Axis.candidateValues answers which values a filter admits; pickValue keeps its throw for direct callers, and _generateCandidate returns null, so an unsatisfiable filter of any shape reports through generateRows. The coverage fill asks for its rows with warnings off, so a fill filter admitting no value is checked before that phase rather than truncating the matrix in silence. Diagnostics name what they are about: a filter written as predicates used to render as {}.

Requirements that share rows are still packed greedily, so a budget below one row per tagged requirement can strand one even where a packing exists. That budget is tested, documented, and named in the error, which counts rows pinned before the call.

The README gains five sections and a checklist: reproducibility and the seed, choosing axes (including the rule that an axis must reach the code under test, and that a project's own configuration belongs on axes), ruling out combinations that do not exist (imply versus exclude, and why a filter matches the axis value as declared), job count and cost, and caching. Every heading that was there before is unchanged, so existing anchors still resolve.

The review corrected four claims in those sections: weights lean the fill rather than setting a rate; failOnUnsatisfiableFilters does not catch a misshaped constraint filter; a misshaped filter is a no-op in exclude and in an imply antecedent but a purge in a consequent; and generateRows does return rows pinned before the call even past the budget.

examples/matrix.mjs gains an assertions axis and weights on os.

How to verify

npm test

63 tests. Eleven are new, and each fails when its own hunk is reverted and only then.

for s in $(seq 1 60); do RNG_SEED=$s MATRIX_JOBS=5 node examples/matrix.mjs; done | grep -c "os: 'ubuntu-latest'"

Prints 175 of 300 rows at the example's weight: 4, which is the figure the cost section quotes. Set the weight to 1, 40 and 1000 and it prints 97, 180 and 180.

Open

The version. This turns warnings into throws and changes the matrix for anyone with a falsy pin, and git tag shows the project does use major bumps. It is set to 2.5.0 here; 3.0.0 is the safer reading, and it is your call.