Add a bitwise mutation operator

[martinus]

Adds one new operator to scripts/mutate/mutate.py: bitwise, which mutates ^ and |. Every operator can be asked for on its own.

scripts/mutate/mutate.py --operators bitwise      # ^ and | alone, four minutes
scripts/mutate/mutate.py --operators deletions    # unchanged

Why

^ appears 36 times in the header and | 20, and the token table mutates neither. & stays out for the same reason -> and :: do — it is three operators sharing a spelling (bitwise and, address-of, and the reference declarator in auto& x) and only a parser can tell them apart. ^ and | have one meaning each, so they cost nothing to be sure about.

In a header made of masks and fingerprints, with a hash that is essentially XOR and multiply, this lands hard. Swept over the whole header:

operator	mutants	time	killed	by a test	survivors
tokens	841	~47 min	not re-measured
bitwise	76	4 min	99%	87%	1
deletions	665	14 min	94%	30%	37

87% killed by a test is the number worth comparing — deletions kills 94% but only 30% by a test, and the compiler telling you a mutant does not build says much less about the suite.

The single survivor is the pleasing part:

return Bucket::dist_inc | (static_cast<dist_and_fingerprint_type>(hash) & Bucket::fingerprint_mask);

| → ^ is the same function, because the two operands share no bits — precisely what static_assert(Bucket::fingerprint_mask < Bucket::dist_inc) two lines above guarantees. An equivalent mutant certified by an assertion already in the file. That is the mechanism worth remembering rather than the percentage: a surviving bitwise mutant usually means the operands are provably disjoint.

bitwise is in the default alongside tokens, so --diff — the everyday mode — actually runs it. Being independently selectable and being excluded from the default were two separate decisions and only the first had an argument behind it; without this, a change to a masking line comes back clean with ^ and | never tried. It costs 76 mutants on 841.

A reordering operator was tried and removed

I originally proposed statement transposition too, on the strength of bugs/invariants.txt saying outright that "a sweep cannot express pop_back before repointing instead of after". Built and measured, it killed 45% of what it generated and left ~100 survivors. Triaging every one of them produced no test worth writing: essentially all are two statements that never touched the same state — member-copy chains, the run of HASH_STATICCAST macros, blocks of declarations. The handful that do touch shared state either check out as equivalent on reading, or are already filed in #198 from the deletions sweep.

The reason is structural: reaching the orderings in invariants.txt means moving a statement out of its enclosing block, which adjacent-swapping cannot do. So it is worth building only alongside something that can. CLAUDE.md keeps the measurement and says plainly that there is nothing left in the tree to go and look at.

Review pass

Four review agents went over the diff; their agreed findings are applied in the second commit.

• --help contradicted itself. The module docstring is argparse's description, and it described two operators directly above an option listing three.
• A test that could not catch what it was named for. test_every_named_operator_is_one_the_runner_dispatches asserted the OPERATORS tuple against a copy of itself. The failure its own comment described — a name parse_operators accepts that nothing dispatches on, which sweeps nothing and reports a clean run — was exactly the one it could not catch, since adding the name and updating the literal is a single edit. It now reads main() and checks each name is actually dispatched on; the default is checked the same way instead of being restated.
• A docstring claim that was false. It said the two tables "share no spelling". They share || — as a consumer, which is the whole point of it being there, since matching the | inside it would turn a || b into a &| b.
• bitwise_sites() gives the operator a name so "this table and no words or numbers" is written once rather than at every call site.
• The measurements now say which commit they describe, the way the optimization dead-ends section already does.

Efficiency was measured rather than guessed: the words_and_numbers=False path costs 4 ms once per run against a 4-minute sweep, and the bitwise scan is still cheaper in absolute terms than the tokens scan (17.6 ms vs 30.0 ms). Nothing to fix.

One finding deliberately not taken: folding both tables into one with per-row category tags would remove the duplicated || consumer row and the words_and_numbers flag. It touches ~25 lines of pre-existing table for a fourth subset that, on the evidence above, is not coming.

Tests

scripts/test_mutate.py goes 155 → 164, all hermetic, suite still ~0.5s.

🤖 Generated with Claude Code