Uses mutation testing to systematically identify gaps in test vector\ncoverage, then generates new test vectors that close those gaps.\nMeasures effectiveness by comparing mutation kill rates before and after.
\nuv run trailmark fails, run:\nuv tool install trailmark\n- At least one implementation of the target algorithm in a\nlanguage with mutation testing support\n- A test harness that consumes test vectors and exercises\nthe implementation\n- A mutation testing framework for the target language\n\n---\n\n## Rationalizations to Reject\n\n| Rationalization | Why It's Wrong | Required Action |\n|-----------------|----------------|-----------------|\n| \"We have enough test vectors\" | Mutation testing proves otherwise | Run the baseline first |\n| \"The implementation's own tests are sufficient\" | Own tests often share blind spots with the impl | Cross-impl vectors catch different bugs |\n| \"FFI crates can be mutation tested at the binding layer\" | Mutations to wrappers don't affect the underlying impl | Mutate the actual implementation language |\n| \"Timeouts mean the mutation was caught\" | Timeouts are ambiguous — could be killed or alive | Resolve timeouts before drawing conclusions |\n| \"All mutants are equivalent\" | Most aren't — verify by reading the mutation | Classify each escaped mutant individually |\n| \"Checking valid vectors is enough\" | Permissive mutations survive without negative assertions | Assert rejection for every invalid vector |\n| \"Manual analysis is fine\" | Manual analysis misses what tooling catches | Install and run the tools |\n\n---\n\n## Workflow Overview\n\nPhase 1: Discovery → Find implementations to test\n↓\nPhase 2: Harness → Write/adapt test vector harness for each impl\n↓\nPhase 3: Baseline → Run mutation testing with existing vectors\n↓\nPhase 4: Escape Analysis → Classify escaped mutants by code path\n↓\nPhase 5: Vector Gen → Create test vectors targeting escapes\n↓\nPhase 6: Validation → Re-run mutation testing, compare before/after\n↓\nOutput: Coverage Report + New Test Vectors
\n\n---\n\n## Phase 1: Discovery\n\nFind implementations of the target algorithm. Look for:\n\n1. **Pure implementations** in high-level languages (Go, Rust, Python)\n — these are the best mutation testing targets\n2. **FFI wrapper crates** — identify these early so you don't waste\n time mutating wrapper glue code\n3. **Reference implementations** — useful for cross-verification but\n may not be the best mutation targets\n\nFor each implementation, note:\n- Language and mutation testing framework\n- Whether it's pure code or FFI wrappers\n- Existing test suite size and coverage\n- Which API surface the test vectors will exercise\n\n### Implementation Type Classification\n\n| Type | Mutation Value | Example |\n|------|---------------|---------|\n| Pure implementation | High | zkcrypto/bls12_381 (Rust), gnark-crypto (Go) |\n| FFI bindings to C/asm | Low at binding layer | blst Rust crate |\n| C/C++ implementation | High (use Mull) | blst C library |\n| Generated code | Medium (mutations may be equivalent) | gnark-crypto generated field arithmetic |\n\n**Key insight:** If an implementation delegates to another language\nvia FFI, you must mutate the *underlying* implementation, not the\nbindings. For C/C++ underneath Rust/Go/Python, use Mull or similar.\n\n---\n\n## Phase 2: Harness\n\nFor each implementation, create a test harness that:\n\n1. Reads test vectors from JSON files (Wycheproof format recommended)\n2. Exercises the implementation's API for each vector\n3. Asserts **both acceptance and rejection**:\n - Valid vectors: deserialization succeeds, output matches expected\n - Invalid vectors: deserialization fails or verification rejects\n4. Adds **roundtrip assertions** for valid deserialization vectors:\n `serialize(deserialize(bytes)) == bytes`\n5. Reports pass/fail per vector with test IDs\n\n**Critical:** A harness that only checks valid vectors will miss all\npermissive mutations (e.g., `&` → `|` in validation). See\n[references/lessons-learned.md](references/lessons-learned.md) §7.\n\nThe harness must be runnable by the mutation testing framework.\nFor most frameworks this means:\n- **Go:** A `_test.go` file in the same package as the implementation\n- **Rust:** An integration test in `tests/` or inline `#[test]` functions\n- **Python:** A pytest test file\n- **C/C++:** A test binary linked against the implementation\n\n### Harness Placement\n\nThe harness must live *inside the implementation's package* so the\nmutation framework can see it. This usually means:\n\n```bash\n# Go: add test file to the package being mutated\ncp wycheproof_test.go /path/to/impl/package/\n\n# Rust: add integration test\ncp wycheproof.rs /path/to/crate/tests/\n\n# Python: add test to the test directory\ncp test_wycheproof.py /path/to/package/tests/\nIf the implementation already has test vectors:
\nRun mutation testing with existing test vectors only.
\nSee references/mutation-frameworks.md\nfor language-specific setup.
\n| Language | \nFramework | \nCommand | \n
|---|---|---|
| Go | \ngremlins | \ngremlins unleash ./path/to/package | \n
| Rust | \ncargo-mutants | \ncargo mutants -j N --timeout T | \n
| Python | \nmutmut | \nmutmut run --paths-to-mutate src/ | \n
| C/C++ | \nMull | \nmull-runner -test-framework=GoogleTest binary | \n
Always use parallel execution for large codebases:
\ncargo mutants -j 8 (Rust, 8 parallel workers)gremlins unleash --timeout-coefficient 3 (Go, increase timeouts)mutmut run --runner \"pytest -x -q\" (Python, fail-fast)Capture these metrics per implementation:
\n| Metric | \nDescription | \n
|---|---|
| Total mutants | \nNumber of mutations generated | \n
| Killed | \nMutants caught by tests | \n
| Survived/Lived | \nMutants NOT caught (these are the targets) | \n
| Not covered | \nCode paths no test reaches at all | \n
| Timed out | \nAmbiguous — resolve before comparing | \n
| Efficacy % | \nKilled / (Killed + Survived) | \n
| Coverage % | \n(Total - Not covered) / Total | \n
Save the full mutation log for Phase 4 analysis.
\nClassify each escaped (survived + not covered) mutant using the\nTrailmark call graph for reachability and blast radius analysis.
\nThis phase MUST use the genotoxic skill's triage methodology.\nThe call graph transforms mutation results from a flat list of\nsurvived mutants into an actionable, prioritized set of vector\ntargets.
\nBuild a Trailmark code graph for each implementation before\ntriaging mutations:
\n# Go\nuv run trailmark analyze --language go --summary {targetDir}\n\n# Rust\nuv run trailmark analyze --language rust --summary {targetDir}\nThe graph provides:
\nMutation frameworks test the entire package. Filter results to\nonly the files/functions that test vectors should exercise:
\n# Go (gremlins)\ngrep -E \"(LIVED|NOT COVERED)\" baseline.log \\\n | grep -E \" at (relevant|files)\" \\\n | sort\n\n# Rust (cargo-mutants)\ncat mutants.out/missed.txt | grep \"src/relevant\"\nFor each escaped mutant, map it to its containing function in the\ncall graph and apply the genotoxic triage criteria:
\n| Graph Signal | \nClassification | \nAction | \n
|---|---|---|
| No callers in graph | \nFalse Positive | \nDead code, skip | \n
| Only test callers | \nFalse Positive | \nTest infrastructure | \n
| Logging/display/formatting | \nFalse Positive | \nCosmetic | \n
| Cross-package callers but NOT COVERED | \nCross-Package Gap | \nSee below | \n
| Reachable from public API, low CC | \nMissing Vector | \nDesign targeted vector | \n
| Reachable from public API, high CC (>10) | \nFuzzing Target | \nBoth vector + fuzz harness | \n
| Validation/error-handling path | \nNegative Vector | \nCraft invalid input that triggers path | \n
| Optimization path (GLV, SIMD, batch) | \nEdge-Case Vector | \nInput that triggers optimization threshold | \n
\\|→^ after left shift (e.g. (t<<1) \\| carry) | \nEquivalent Mutant | \nSkip — bit 0 always 0, OR=XOR | \n
ct_eq &→\\| on Montgomery limbs | \nAPI-Unreachable | \nNeeds library-internal tests, not vectors | \n
| Equivalent mutation (behavior unchanged) | \nFalse Positive | \nSkip | \n
Critical pitfall: Mutation frameworks often only run tests\nwithin the same package as the mutation. For Go (gremlins) and\nRust (cargo-mutants), this means:
\nhash_to_curve/g2.go only runs tests in the\nhash_to_curve package, NOT tests in the parent bls12381\npackage that imports itTo resolve cross-package gaps:
\n--test-pkg ./... (if supported)Using the call graph, rank surviving mutants by impact:
\n| Priority | \nCriteria | \nExample | \n
|---|---|---|
| P0 — Critical | \nMutant weakens validation/equality/authentication | \nct_eq: & → \\| makes equality permissive | \n
| P1 — High | \nMutant in deserialization flag parsing | \nfrom_compressed: & → \\| accepts invalid flags | \n
| P2 — Medium | \nMutant in field arithmetic internals | \nFp::square: \\| → ^ corrupts computation | \n
| P3 — Low | \nMutant in optimization path | \nphi endomorphism: only affects performance path | \n
| Skip | \nFormatting, display, equivalent mutation | \nDebug::fmt return value replacement | \n
Group escaped mutants by the code path they represent and the\ntype of test vector needed:
\nDeserialization flag validation (P1):\n - g1.rs:339,363-365,384 — from_compressed_unchecked flags\n → Need: valid-point-wrong-flag vectors\n\nField arithmetic (P2):\n - fp.rs:371-376,406,635-643 — subtract_p, neg, square\n → Need: field arithmetic KATs with edge-case values\n\nOptimization thresholds (P3):\n - g1.go:68, g2.go:75 — GLV vs windowed multiplication\n → Need: scalar multiplication with large scalars\n\nCross-package (framework limitation):\n - hash_to_curve/g2.go:242-278 — isogeny, sgn0\n → Document as false positive or add sub-package test\nEach group becomes a target for new test vectors in Phase 5.
\nFor each escaped code path group, design test vectors that\nforce execution through that path.
\n| Code Path Type | \nVector Strategy | \n
|---|---|
| Point deserialization | \nMalformed points: wrong length, invalid field elements, off-curve, wrong subgroup, identity point | \n
| Signature verification | \nValid sig + all single-bit corruptions of sig, pk, msg | \n
| Hash-to-curve | \nKnown answer tests (KATs) with edge-case inputs: empty, single byte, max length | \n
| Aggregate operations | \n1 signer, many signers, duplicate signers, mixed valid/invalid | \n
| Error handling | \nEvery error path should have a vector that triggers it | \n
| Arithmetic edge cases | \nZero, one, field modulus - 1, points at infinity | \n
| Serialization flags | \nEvery valid flag combination + every invalid flag combination | \n
| Roundtrip integrity | \nFor every valid deser vector, assert serialize(deserialize(b)) == b | \n
| Carry/reduction faults | \nReimplement at reduced limb widths, inject faults, extract distinguishing inputs | \n
Each negative vector should have exactly one defect with\neverything else valid — this isolates which validation check is\nbeing tested. See references/vector-patterns.md\nfor per-flag construction examples.
\nWhen mutation testing only applies local operator swaps, deeper\narchitectural bugs (carry propagation, reduction overflow) go\nuntested. To close this gap, reimplement the target algorithm\nat reduced limb widths (8, 16, 25, 32 bits) and deliberately\ninject faults — then generate vectors that catch them.
\nSee references/fault-simulation.md\nfor the full methodology: limb-width selection, fault injection\ncatalog, vector extraction, and validation workflow.
\nEvery new test vector MUST be verified against at least two\nindependent implementations before being added to the suite:
\nUse Wycheproof JSON format (algorithm, testGroups[].tests[]\nwith tcId, comment, result, flags). See\nreferences/vector-patterns.md\nfor the full schema.
Wycheproof contributions: Use Wycheproof's vectorgen tool rather\nthan formatting vector files directly. Supply the generated changes as an\nenvelope. The vectorgen tool can add, update, or replace vectors while\nhandling tcId assignment, test counts, canonical formatting, and schema\nvalidation. Go-based generators can avoid the vectorgen CLI tool and instead\ncall the programmatic github.com/c2sp/wycheproof/vectorgen API.
See references/lessons-learned.md\n§14 and the upstream\nvectorgen guide\nfor the current workflow and commands.
\nRe-run mutation testing with the new test vectors included.
\nTip: Use per-file mutation testing for fast iteration during\nvector development (see references/lessons-learned.md §12).\nOnly run full-crate tests for the final comparison.
\n| Metric | \nBaseline | \nWith New Vectors | \nDelta | \n
|---|---|---|---|
| Killed | \nX | \nY | \nY - X | \n
| Survived | \nA | \nB | \nA - B (should decrease) | \n
| Not Covered | \nC | \nD | \nC - D (should decrease) | \n
| Efficacy % | \nE% | \nF% | \nF - E | \n
Vectors have both retroactive value (killing mutants in\nexisting code) and proactive value (catching bugs in future\nimplementations). Generate both kinds — boundary-condition vectors\nmay not improve kill rates in mature libraries but will catch bugs\nin new implementations. See\nreferences/lessons-learned.md §13.
\nRetroactive (measurable): previously survived/uncovered mutants\nbecome killed, no regressions.
\nIf kill rates don't change: the implementation's own tests\nlikely already cover those paths. The vectors still add\ncross-implementation verification value. Document which case\napplies.
\nWrite VECTOR_FORGE_REPORT.md covering: target algorithm,\nimplementations tested, baseline results, escape analysis,\nnew vectors generated, after results, before/after delta, and\nconclusions. See\nreferences/report-template.md\nfor the full template.
Before delivering:
\nVECTOR_FORGE_REPORT.md| Skill | \nRelationship | \n
|---|---|
| genotoxic (required for Phase 4) | \nProvides graph-informed triage — call graph cuts actionable mutants by 30-50% | \n
| mutation-testing (mewt/muton) | \nUse for Solidity; Vector Forge is language-agnostic | \n
| property-based-testing | \nBetter than hand-crafted vectors for bitwise mutations in field arithmetic | \n
| testing-handbook-skills (fuzzing) | \nFunctions with CC > 10 and surviving mutants need both vectors and fuzz harnesses | \n