Domain-specific mutation operators via universalmutator (complementing cargo-mutants)

[Troublor]

Motivation

Our mutation-testing gate uses cargo-mutants, which ships a fixed, curated set of structural operators (replace function body with a default, flip binary/relational/logical/bit operators, a few literals). It has no plugin API, so it is structurally blind to the mutations that matter most for a state-commitment system — endianness, field-element chunk widths, codec configuration, canonicalization, and the trie's level/bit-width arithmetic.

universalmutator is regex-rule based (regex ==> replacement), language-agnostic, and auto-discards mutants that don't compile or compile identically. That makes it a good vehicle for a complementary, domain-specific mutation layer: cargo-mutants guards generic code structure; universalmutator guards SALT semantics.

This issue catalogs candidate domain operators to prototype. The selection filter throughout: "what soundness or determinism invariant would a surviving mutant here violate?" We deliberately skip operators that overlap with cargo-mutants (generic arithmetic/relational/logical), and skip the resize load-factor / growth-multiplier (configurable by design, not consensus-critical).

A. Trie-structure operators (highest leverage)

The SALT trie's correctness reduces to "right level-base and right bit-width?" — pure integer arithmetic over a STARTING_NODE_ID[level] table and three distinct bit-widths (TRIE_WIDTH_BITS = 8, MIN_BUCKET_SIZE_BITS = 8, BUCKET_SLOT_BITS = 40). A wrong constant produces a plausible, compiling, wrong structure — exactly what mutation testing exists to catch. See salt/src/trie/node_utils.rs and salt/src/constant.rs.

A1. Level-index off-by-one (the base table) — the sharpest family:

STARTING_NODE_ID\[level \+ 1\] ==> STARTING_NODE_ID[level]
STARTING_NODE_ID\[level - 1\]  ==> STARTING_NODE_ID[level]
MAIN_TRIE_LEVELS - 1           ==> MAIN_TRIE_LEVELS
MAX_SUBTREE_LEVELS - 1         ==> MAX_SUBTREE_LEVELS - 2

Expected kills: test_get_child_node, test_get_parent_node (inverse relationship), test_bucket_root_node_id, test_subtree_leaf_for_key.

A2. Bit-width constant confusion (the 24/40/8 split) — swap one named width for another real one; invisible to any generic tool:

<< BUCKET_SLOT_BITS      ==> << BUCKET_ID_BITS
>> MIN_BUCKET_SIZE_BITS   ==> >> BUCKET_SLOT_BITS
<< BUCKET_SLOT_BITS       ==> << (BUCKET_SLOT_BITS - 1)

Expected kills: test_subtree_leaf_for_key, test_vc_position_in_parent (max-bucket case).

A3. Fanout shift direction / amount (the << 8 / >> 8 that is the 256-way branching):

\(parent_relative_position << TRIE_WIDTH_BITS\) ==> (parent_relative_position >> TRIE_WIDTH_BITS)
relative_position >> TRIE_WIDTH_BITS            ==> relative_position << TRIE_WIDTH_BITS
<< TRIE_WIDTH_BITS                              ==> << (TRIE_WIDTH_BITS + 1)

Expected kills: get_child_node/get_parent_node inverse test.

A4. Segment granularity (256 slots per leaf):

>> MIN_BUCKET_SIZE_BITS ==> >> (MIN_BUCKET_SIZE_BITS + 1)
% TRIE_WIDTH            ==> % (TRIE_WIDTH - 1)

Expected kills: test_subtree_leaf_for_key_segment_boundaries, test_subtree_leaf_start_key, test_vc_position_in_parent.

A5. Ceil-division rounding in the subtree-root climb — subtree_root_level does (capacity + MIN_BUCKET_SIZE - 1) >> BITS; dropping the - 1 turns ceil into floor, wrong at exact powers of 256. The subtlest one, and a perfect target because the rounding correction is invisible to the eye:

\(capacity \+ MIN_BUCKET_SIZE as u64 - 1\) ==> (capacity + MIN_BUCKET_SIZE as u64)
capacity > MIN_BUCKET_SIZE as u64          ==> capacity >= MIN_BUCKET_SIZE as u64
level -= 1                                  ==> level += 1

Expected kills: test_subtree_root_level (257→3, 65536→3, 65537→2 boundary cases).

Validation loop: get_child_node/get_parent_node are tested as exact inverses over a parent × child-index matrix, so most A1–A4 mutants should die there. Any survivor points to a coverage gap in that inverse test.

B. Endianness / byte-order

Explicit byte packing in the hasher and codecs; wrong endianness silently breaks determinism and cross-platform reproducibility, and no generic operator flips it.

to_le_bytes   ==> to_be_bytes
to_be_bytes   ==> to_le_bytes
from_le_bytes ==> from_be_bytes
from_be_bytes ==> from_le_bytes

Expected kills: salt/src/state/hasher.rs pinned-output tests, salt/tests/proof_fixture_codec.rs.

C. Field-element / chunk width (the 31-vs-32 hazard)

Classic commitment bug: a value is 32 bytes but a field element only safely holds 31. Scope the bare 31/32 rules to specific files.

\.chunks\(32\)  ==> .chunks(31)
\.chunks\(31\)  ==> .chunks(32)
>> 8            ==> >> 4
& 0xff          ==> & 0x7f

Expected kills: trie chunking / scalar-encoding tests.

D. Serialization codec config

The legacy() codec choice is the wire format; swapping it should break the byte-for-byte fixture test.

\.legacy\(\)         ==> .standard()
with_fixint_encoding ==> with_varint_encoding
with_little_endian   ==> with_big_endian

Expected kills: salt/tests/proof_fixture_codec.rs.

E. Canonicalization removal (sort / dedup)

The proof path sorts/dedups to reach canonical form. Deleting those calls is a soundness mutation (duplicates / unordered elements should be rejected or change the root). Line deletion is not in cargo-mutants' repertoire.

^(\s*).*\.sort(_unstable)?\(\);        ==> \1
^(\s*).*\.dedup(_by)?\([^)]*\);        ==> \1
sort_by\(([^)]*)a\.cmp\(&?b\)([^)]*)\) ==> sort_by(\1b.cmp(&a)\2)

Expected kills: salt/src/proof/prover.rs sort/dedup canonicalization tests.

F. Hash-diffusion ops

Rotates / xors in hash mixing, which cargo-mutants won't touch. Keep xor→or file-scoped to the hasher.

rotate_left   ==> rotate_right
rotate_right  ==> rotate_left
wrapping_add  ==> wrapping_sub
\^             ==> |

Expected kills: salt/src/state/ahash/fallback.rs, salt/src/state/hasher.rs pinned-hash tests.

Explicitly out of scope

• Generic arithmetic / relational / logical / function-body operators — already covered by the cargo-mutants gate; duplicating them just muddies which tool is authoritative.
• Bucket resize load-factor (BUCKET_RESIZE_LOAD_FACTOR_PCT) and growth multiplier (BUCKET_RESIZE_MULTIPLIER) — configurable by design, not consensus-critical.

Proposed next steps

• Consolidate families A–F into a single file-scoped mutants/salt.rules (Rust isn't a first-class universalmutator language, so run with the generic ruleset + these custom rules).
• Run universalmutator over salt/src/trie/, salt/src/constant.rs, salt/src/state/, and salt/src/proof/; diff the survivor set.
• Triage survivors: each is either a missing test (add coverage) or an equivalent mutant (record with justification, mirroring the existing cargo-mutants suppression registry).
• Decide whether this runs as an occasional/manual analysis or graduates into a scheduled CI job alongside the sharded full cargo-mutants run.

[vincent-k2026]

First implementation step is up as #143: families A (trie), E (canon) and B (endian) as scoped rule packs under mutants/operators/, plus scripts/spec_mutation.sh (generation restricted to production lines so mutants never land in #[cfg(test)]; 3-way invalid/killed/survived classification; survivors reported as diffs and fail the run) and a dispatch-only Spec Mutation workflow.

Local generation across the three packs yields 59 mutants (50 trie / 3 canon / 6 endian), spot-checked to be exactly the intended semantic faults. C/D/F staged for after the first survivor triage, per the plan above. Note #142 (explicit-LE hasher reads) is what makes the endian pack bite on convert.rs.

Suggested next action once both PRs land: gh workflow run "Spec Mutation" and triage survivors — each is either a missing test or a documented equivalence.

[flyq]

Continuing from the maintenance side — a second batch of candidate operators, from the verifier and cross-crate surface rather than the prover-structural one A–F covers. Same selection filter throughout: "what soundness or determinism invariant would a surviving mutant here violate?"

Two properties of the current setup shape everything below, and I've folded them into the verdicts:

• The cryptographic core is outside the gate. Both layers are scoped to salt (test_package = ["salt"]; packs list files under salt/src/), so banderwagon and ipa-multipoint have zero mutation coverage. Family H targets them; its rules only run once the gate is extended, so I mark them KILLED* = killed by an existing pinned vector, but only after that extension.
• The oracle is self-referential. No test pins an absolute state root or bucket layout — the e2e/differential tests compare the code to itself (both sides mutated), and the proof tests are honest round-trips. So (a) a symmetric change to the canonical layout/transcript and (b) a relaxed verifier check both survive by construction; for those the kill is a new pinned vector or negative test, called out inline rather than as a regex.

Line numbers are against current main.

G. Verifier-relaxation operators (the proof-check path)

Deleting or weakening a check on the verification path is invisible to honest round-trips — prove→verify still passes — so these die only against forged input. #140 added good negative tests that kill several; the survivors are the negative-test gaps. Scope: salt/src/proof/*.rs.

G1. Root binding — the recomputed root must equal the claimed state_root:

state_root != trie_root ==> state_root == trie_root

Expected kills: test_check_rejects_tampered_root_commitment.

G2. IPA verdict — collapsing the failure branch accepts any forged opening (the soundness core):

Err\(ProofError::MultiPointProofFailed\) ==> Ok(())

Expected kills: test_verify_proof_rejects_tampered_kv_value.

G3. Commitment node-set "contains AND ONLY contains" — the one-directional weakening keeps the honest set valid while letting extra commitments through:

proof_node_ids != required_node_ids ==> !required_node_ids.is_subset(&proof_node_ids)

Expected kills: test_check_rejects_extra_parent_commitment kills the == / delete forms; the subset weakening likely survives — add a case that is valid plus one extra commitment.

G4. Witness "unknown ≠ absent" — an un-witnessed key must error, never read as proven-absent (salt_witness.rs:156):

None => Err\(SaltError::NotInWitness \{ what: "Key" \}\) ==> None => Ok(None)

Expected kills: test_witness_state_reader_security.

Known survivors with no single-line rule (the map_err/match arms span lines) — these are missing negative tests, not regexes: malformed MultiPointProof bytes (prover.rs:100), malformed metadata bytes (salt_witness.rs:202), and the "key claimed but not found" lookup arm (witness.rs:251). None has an adversarial test today.

H. Cross-crate crypto-core operators (banderwagon + ipa-multipoint)

The largest family, and the whole point of Observation 1: none of these run today. KILLED* = an existing pinned vector catches it once the gate covers the crate; SURVIVES = a gap even then.

H1. Group-equality discrimination — the sharpest gap; equality is never asserted false for two distinct valid points, so even the constant folds through:

\(x1 \* y2\) == \(x2 \* y1\) ==> true

Expected kills: none today — test_eq_failsafe only compares (0,0) to itself. (Verified locally: with the body replaced by true, all 14 banderwagon tests pass — 14/14, 0 failed.) Add an assert_ne! between two distinct valid Elements (and a (x,y) vs (x,-y) inequality).

H2. Subgroup / Legendre gate (SOUNDNESS) — rejects exceptional / small-order points:

subgroup_check\(&point\) ==> true
\.legendre\(\)\.is_qr\(\) ==> .legendre().is_qnr()
Fq::one\(\) - BandersnatchConfig::COEFF_A ==> Fq::one() + BandersnatchConfig::COEFF_A

Expected kills: check_infinity_does_not_pass_legendre, ser_der_roundtrip.

subgroup_check guards every compressed decode, including the witness path Element::from_bytes(bytes) at salt/src/proof/prover.rs:122. That call site has no adversarial bad-bytes test of its own (only the standalone SerdeCommitment path does), so the shared mutant is caught elsewhere but the path is unguarded — add a negative test through parents_commitments_serde. (Note: there is no compressed from_bytes_unchecked to swap to — the bypass is expressed by mutating subgroup_check.)

H3. Sign choice / canonical representative (quotient canonicality):

coordinate > -coordinate ==> coordinate < -coordinate
EdwardsAffine::new_unchecked\(-affine.x, -affine.y\) ==> EdwardsAffine::new_unchecked(-affine.x, affine.y)

Expected kills: fixed_test_vectors kills the sign flip; the (-x,-y)→(-x,y) representative is only incidentally covered (the dedicated test_batch_to_commitments is blind — both operands route through affine_to_canonical_bytes). Add an independent known-bytes vector for a negative-y point.

H4. Byte order — extends family B into these crates (arkworks-LE ↔ spec-BE, cross-client interop). Scope: banderwagon/{element.rs,lib.rs}, ipa-multipoint/{transcript.rs,crs.rs}:

^(\s*).*bytes\.reverse\(\);.*$ ==> \1
from_be_bytes_mod_order ==> from_le_bytes_mod_order
from_le_bytes_mod_order ==> from_be_bytes_mod_order

Expected kills: fixed_test_vectors, ser_der_roundtrip, consistent_group_to_field, the transcript/multiproof KATs — except lib.rs try_reduce_to_element, which has no test at all and survives.

H5. CRS binding integrity — distinct generators are the binding property (crs.rs:82):

^(\s*)CRS::assert_dedup\(.*\);.*$ ==> \1

Expected kills: none today — no colliding-seed test. Add one that forces a duplicate generator and asserts the panic.

H6. Fiat–Shamir transcript — the symmetric case (Observation 2): prover and verifier build the transcript with the same code, so a mutation makes both agree:

^(\s*)transcript\.domain_sep\(b"ipa"\);.*$ ==> \1
challenge_scalar\(b"w"\) ==> challenge_scalar(b"x")

Expected kills: only the pinned challenge/commitment vectors (test_ipa_consistency, multiproof_consistency, transcript test_vector_*). Under a differential oracle these all survive — a direct argument for keeping and expanding the pinned KATs.

H7. Fixed-base tables & bit-order arithmetic — the wNAF/committer math (salt_committer.rs) and challenge-bit order (ipa.rs):

element \+= element; ==> element += base;
x: -precom_table\[index \+ i \* \(half_win \+ 1\)\]\.x ==> x: precom_table[index + i * (half_win + 1)].x
^(\s*).*\.rev\(\)$ ==> \1

Expected kills: neg_one_scalar_mult, mul_index (committer, exact affine coords); test_ipa_consistency (the to_bits(...).rev() at ipa.rs:267).

I. Consensus-boundary comparisons the tests never reach

Not the generic relational sweep (cargo-mutants owns that) — only comparisons at consensus boundaries whose exact value no test hits, so > vs >= is silently free. Scope: salt/src/state/state.rs, salt/src/types.rs.

Verified locally: with all three mutations active, the full salt suite under the gate's default config passes clean — 202 passed, 0 failed. All three survive. (The test-bucket-resize env config, which the gate deliberately excludes, is too slow under NUM_DATA_BUCKETS=2 to conclude either way — but I2 is pure logic and unaffected by it, and no failures appeared in the portion that ran.)

I1. Resize trigger — tests insert 203 keys against a threshold of 204, so used == 204 never happens:

if used > metadata.capacity ==> if used >= metadata.capacity

Expected kills: none today — add a test at exactly capacity * threshold / 100.

I2. is_default metadata gate — widened, a non-default bucket (capacity 512) caches as absent → later reads return capacity 256 → wrong layout:

self.nonce == 0 && self.capacity == MIN_BUCKET_SIZE as u64 ==> self.nonce == 0 || self.capacity == MIN_BUCKET_SIZE as u64

Expected kills: none today — drive a nonce=0, capacity=512 bucket through the cache_read path and re-read capacity.

I3. Rehash data-loss guard — test capacities never equal the entry count, so the exactly-full boundary is unexercised:

if new_capacity < old_bucket.len\(\) ==> if new_capacity <= old_bucket.len()

Expected kills: none today — add an exactly-full rehash case.

J. Overflow-guard operators (overflow-checks = false)

The release profile disables overflow checks, so these "arithmetically-equivalent" simplifications are live faults on large inputs. #140 already kills them — listed so the pack does not re-file them as fresh candidates (they look like equivalents but aren't). Scope: salt/src/state/state.rs.

\(hashed_key % capacity\) + i ==> (hashed_key + i)
slot_id + capacity - first ==> slot_id - first

Expected kills: probe_and_rank_inverse_relationship (the u64::MAX case), probe_and_rank_wraparound.

K. Domain-offset / namespace operators

Distinct from family A (trie widths): the offsets and moduli that route keys into the correct namespace. Drop an offset and data collides with metadata storage. Scope: salt/src/state/hasher.rs, salt/src/types.rs.

% NUM_KV_BUCKETS as u64 + NUM_META_BUCKETS as u64 ==> % NUM_KV_BUCKETS as u64
% NUM_KV_BUCKETS as u64 ==> % NUM_BUCKETS as u64
bucket_id >> MIN_BUCKET_SIZE_BITS ==> bucket_id >> MIN_BUCKET_SIZE

Expected kills: test_bucket_id_range, test_bucket_id_known_values_are_pinned, bucket_metadata_key_mapping.

L. Delta-skip operators (wrong-root risk)

The guard that decides whether a commitment delta is emitted; skipping a real change silently produces a wrong root. Scope: salt/src/trie/trie.rs.

\(new_c != old_c\)\.then_some ==> (new_c == old_c).then_some

Expected kills: trie::trie::tests::expansion_and_contraction_small, trie::trie::tests::expansion_and_contraction_at_same_level.

Verified locally: under this mutation the full salt suite is 2 failed / 193 passed — killed by the two expansion_and_contraction_* tests (panics at trie.rs:1746/:1624). The interesting part is what does not catch it: the differential e2e (witness_replay_matches_full_store…) and the proof round-trips both pass — Observation 2 in action, both sides run the mutated code. Two consequences: (a) this operator is not a survivor, and (b) != ==> == is a comparison swap cargo-mutants already generates on this gated crate, so L is redundant — drop it from the new packs. The remaining value here is the insight: if those dedicated trie-delta unit tests didn't exist, the differential oracle alone would miss it, so keep them (and prefer an absolute-root oracle) rather than relying on e2e.

M. Concurrency-shape operators

The chunking arithmetic behind the parallel feature — the work-split must not drop or duplicate elements. Scope: ipa-multipoint/{ipa.rs,math_utils.rs,multiproof.rs}.

\.div_ceil\( ==> / (

Expected kills: the IPA/multiproof consistency tests (once the gate covers ipa-multipoint).

Deliberately excludes .reduce/.sum ordering: elliptic-curve point addition is abelian, so reduction-order mutants are genuinely equivalent (see out-of-scope).

N. Untrusted-count / value-bound findings (verifier DoS)

The verifier validates the key set of prover-supplied maps but not their values. get_subtree_levels returns the prover's levels value unchecked, and it flows into STARTING_NODE_ID[MAX_SUBTREE_LEVELS - levels as usize] (shape.rs:298); a forged levels > 5 (a u8 allows 255) underflows → out-of-bounds index → verifier panic. Similarly for slot in 0..capacity (salt_witness.rs:244) trusts an untrusted u64 bound. These aren't line-mutations — the check simply doesn't exist yet — so they belong in next steps: add a 1..=MAX_SUBTREE_LEVELS bound plus a forged-level negative test.

Explicitly out of scope (equivalent mutants — pre-suppress these)

A mature pack is defined as much by what it doesn't generate; each of these compiles and passes but is behavior-preserving, so it manufactures a false survivor:

• element.rs:410 COEFF_A ==> COEFF_D in subgroup_check — by the curve's Theorem 1, 1-a·x² and 1-d·x² share QR-ness for on-curve points, and only on-curve points reach here. The same swap at element.rs:217 (get_point_from_x) is NOT equivalent — keep that one.
• element.rs:361 > ==> >= in is_positive — only ever called on non-zero coordinates, so the == boundary never occurs (> ==> < is real).
• msm.rs:45,57 dropping the !scalar.is_zero() filter — zero-scalar terms are identity, harmless (inverting to is_zero() is real).
• platform.rs:7 DEFAULT_PRECOMP_WINDOW_SIZE and salt_committer.rs:163 inner_length (non-hugepage feature set) — result-invariant, perf/memory only.
• types.rs:239 + ==> | in SaltKey packing — slot < 2^40, high bits zero.
• state.rs:834 > ==> >= in the compaction rank comparison — rank is injective over distinct slots (> ==> < is real).
• hasher.rs:71 <= ==> < in the stack/heap dispatch — both branches emit the identical key‖nonce digest.
• prover.rs:420 the child_map lookup — unreachable defense-in-depth (the reachable miss is caught one layer up).
• .reduce/.sum reduction order over Element — abelian.
• Generic arithmetic / relational / logical / function-body operators — already owned by the cargo-mutants gate.

Proposed next steps

• Extend the mutation gate to banderwagon + ipa-multipoint — add them to cargo-mutants' package list, or point a scoped universalmutator pack at their sources. Unblocks all of family H.
• Add the missing soundness negative tests first (turns several H rows from SURVIVES → KILLED): assert_ne! on two distinct valid Elements (element.rs:47); off-subgroup bytes through parents_commitments_serde (prover.rs:122); a colliding-seed CRS test (crs.rs:82).
• Land families G, I, K as file-scoped universalmutator packs in the PR feat(mutation): domain-specific operator packs via universalmutator (#141) #143 style, with the out-of-scope equivalents pre-suppressed so the first survivor triage isn't polluted. (L is dropped — verified redundant with the existing cargo-mutants gate and already killed by the expansion_and_contraction_* tests.)
• Add a 1..=MAX_SUBTREE_LEVELS bound + forged-level negative test (family N) — a real verifier-DoS hardening, not just a mutation target.
• Fold J and M in as documentation of already-strong coverage, so we don't duplicate what test(salt): add mutation testing coverage #140 guards.