# vector-forge

Mutation-driven test vector generation. Finds implementations of a cryptographic algorithm or protocol, runs mutation testing to identify escaped mutants, then generates new test vectors that deliberately exercise the uncovered code paths. Compares before/after mutation kill rates to prove vector effectiveness. Use when generating cryptographic test vectors, measuring Wycheproof coverage gaps, finding escaped mutants via mutation testing, creating cross-implementation test suites, or improving test vector coverage for crypto primitives.

- **Kind:** skill
- **Source:** https://github.com/trailofbits/skills
- **Page:** https://forefy.com/skills/5c904959-70af-4ad8-accd-1ef97a7571f1
- **API (JSON + files):** https://forefy.com/api/asr/5c904959-70af-4ad8-accd-1ef97a7571f1

---

## SKILL.md

---
name: vector-forge
description: "Mutation-driven test vector generation. Finds implementations of a cryptographic algorithm or protocol, runs mutation testing to identify escaped mutants, then generates new test vectors that deliberately exercise the uncovered code paths. Compares before/after mutation kill rates to prove vector effectiveness. Use when generating cryptographic test vectors, measuring Wycheproof coverage gaps, finding escaped mutants via mutation testing, creating cross-implementation test suites, or improving test vector coverage for crypto primitives."
---

# Vector Forge

Uses mutation testing to systematically identify gaps in test vector
coverage, then generates new test vectors that close those gaps.
Measures effectiveness by comparing mutation kill rates before and after.

## When to Use

- Generating test vectors for cryptographic algorithms or protocols
- Evaluating how well existing test vectors cover an implementation
- Finding implementation code paths that no test vector exercises
- Creating Wycheproof-style cross-implementation test vectors
- Measuring the concrete coverage value of a test vector suite

## When NOT to Use

- No implementations exist yet (need code to mutate)
- Single trivial implementation with no edge cases
- Testing application logic rather than algorithm implementations
- The algorithm has no public test vectors to compare against

## Prerequisites

- **trailmark** installed — if `uv run trailmark` fails, run:
  ```bash
  uv tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)
  ```
- At least one implementation of the target algorithm in a
  language with mutation testing support
- A test harness that consumes test vectors and exercises
  the implementation
- A mutation testing framework for the target language

---

## Rationalizations to Reject

| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "We have enough test vectors" | Mutation testing proves otherwise | Run the baseline first |
| "The implementation's own tests are sufficient" | Own tests often share blind spots with the impl | Cross-impl vectors catch different bugs |
| "FFI crates can be mutation tested at the binding layer" | Mutations to wrappers don't affect the underlying impl | Mutate the actual implementation language |
| "Timeouts mean the mutation was caught" | Timeouts are ambiguous — could be killed or alive | Resolve timeouts before drawing conclusions |
| "All mutants are equivalent" | Most aren't — verify by reading the mutation | Classify each escaped mutant individually |
| "Checking valid vectors is enough" | Permissive mutations survive without negative assertions | Assert rejection for every invalid vector |
| "Manual analysis is fine" | Manual analysis misses what tooling catches | Install and run the tools |

---

## Workflow Overview

```
Phase 1: Discovery       → Find implementations to test
      ↓
Phase 2: Harness         → Write/adapt test vector harness for each impl
      ↓
Phase 3: Baseline        → Run mutation testing with existing vectors
      ↓
Phase 4: Escape Analysis → Classify escaped mutants by code path
      ↓
Phase 5: Vector Gen      → Create test vectors targeting escapes
      ↓
Phase 6: Validation      → Re-run mutation testing, compare before/after
      ↓
Output: Coverage Report + New Test Vectors
```

---

## Phase 1: Discovery

Find implementations of the target algorithm. Look for:

1. **Pure implementations** in high-level languages (Go, Rust, Python)
   — these are the best mutation testing targets
2. **FFI wrapper crates** — identify these early so you don't waste
   time mutating wrapper glue code
3. **Reference implementations** — useful for cross-verification but
   may not be the best mutation targets

For each implementation, note:
- Language and mutation testing framework
- Whether it's pure code or FFI wrappers
- Existing test suite size and coverage
- Which API surface the test vectors will exercise

### Implementation Type Classification

| Type | Mutation Value | Example |
|------|---------------|---------|
| Pure implementation | High | zkcrypto/bls12_381 (Rust), gnark-crypto (Go) |
| FFI bindings to C/asm | Low at binding layer | blst Rust crate |
| C/C++ implementation | High (use Mull) | blst C library |
| Generated code | Medium (mutations may be equivalent) | gnark-crypto generated field arithmetic |

**Key insight:** If an implementation delegates to another language
via FFI, you must mutate the *underlying* implementation, not the
bindings. For C/C++ underneath Rust/Go/Python, use Mull or similar.

---

## Phase 2: Harness

For each implementation, create a test harness that:

1. Reads test vectors from JSON files (Wycheproof format recommended)
2. Exercises the implementation's API for each vector
3. Asserts **both acceptance and rejection**:
   - Valid vectors: deserialization succeeds, output matches expected
   - Invalid vectors: deserialization fails or verification rejects
4. Adds **roundtrip assertions** for valid deserialization vectors:
   `serialize(deserialize(bytes)) == bytes`
5. Reports pass/fail per vector with test IDs

**Critical:** A harness that only checks valid vectors will miss all
permissive mutations (e.g., `&` → `|` in validation). See
[references/lessons-learned.md](references/lessons-learned.md) §7.

The harness must be runnable by the mutation testing framework.
For most frameworks this means:
- **Go:** A `_test.go` file in the same package as the implementation
- **Rust:** An integration test in `tests/` or inline `#[test]` functions
- **Python:** A pytest test file
- **C/C++:** A test binary linked against the implementation

### Harness Placement

The harness must live *inside the implementation's package* so the
mutation framework can see it. This usually means:

```bash
# Go: add test file to the package being mutated
cp wycheproof_test.go /path/to/impl/package/

# Rust: add integration test
cp wycheproof.rs /path/to/crate/tests/

# Python: add test to the test directory
cp test_wycheproof.py /path/to/package/tests/
```

### Handling Existing Vectors

If the implementation already has test vectors:
1. Run mutation testing with ONLY the existing vectors (baseline)
2. Run mutation testing with ONLY your new vectors
3. Run mutation testing with BOTH combined
4. The delta between (1) and (3) shows the new vectors' value

---

## Phase 3: Baseline

Run mutation testing with existing test vectors only.

### Framework Selection

See [references/mutation-frameworks.md](references/mutation-frameworks.md)
for language-specific setup.

| Language | Framework | Command |
|----------|-----------|---------|
| Go | gremlins | `gremlins unleash ./path/to/package` |
| Rust | cargo-mutants | `cargo mutants -j N --timeout T` |
| Python | mutmut | `mutmut run --paths-to-mutate src/` |
| C/C++ | Mull | `mull-runner -test-framework=GoogleTest binary` |

### Parallelism

Always use parallel execution for large codebases:
- `cargo mutants -j 8` (Rust, 8 parallel workers)
- `gremlins unleash --timeout-coefficient 3` (Go, increase timeouts)
- `mutmut run --runner "pytest -x -q"` (Python, fail-fast)

### Recording Baseline Results

Capture these metrics per implementation:

| Metric | Description |
|--------|-------------|
| Total mutants | Number of mutations generated |
| Killed | Mutants caught by tests |
| Survived/Lived | Mutants NOT caught (these are the targets) |
| Not covered | Code paths no test reaches at all |
| Timed out | Ambiguous — resolve before comparing |
| Efficacy % | Killed / (Killed + Survived) |
| Coverage % | (Total - Not covered) / Total |

Save the full mutation log for Phase 4 analysis.

---

## Phase 4: Escape Analysis (Graph-Informed Triage)

Classify each escaped (survived + not covered) mutant using the
Trailmark call graph for reachability and blast radius analysis.

**This phase MUST use the genotoxic skill's triage methodology.**
The call graph transforms mutation results from a flat list of
survived mutants into an actionable, prioritized set of vector
targets.

### Step 1: Build the Call Graph

Build a Trailmark code graph for each implementation before
triaging mutations:

```bash
# Go
uv run trailmark analyze --language go --summary {targetDir}

# Rust
uv run trailmark analyze --language rust --summary {targetDir}
```

The graph provides:
- **Caller chains** — trace from public API entry points to
  mutated functions to determine reachability
- **Cyclomatic complexity** — prioritize high-CC functions
- **Blast radius** — functions with many callers have wider
  impact if their mutations survive

### Step 2: Filter to Relevant Code

Mutation frameworks test the entire package. Filter results to
only the files/functions that test vectors should exercise:

```bash
# Go (gremlins)
grep -E "(LIVED|NOT COVERED)" baseline.log \
  | grep -E " at (relevant|files)" \
  | sort

# Rust (cargo-mutants)
cat mutants.out/missed.txt | grep "src/relevant"
```

### Step 3: Graph-Informed Classification

For each escaped mutant, map it to its containing function in the
call graph and apply the genotoxic triage criteria:

| Graph Signal | Classification | Action |
|--------------|----------------|--------|
| No callers in graph | **False Positive** | Dead code, skip |
| Only test callers | **False Positive** | Test infrastructure |
| Logging/display/formatting | **False Positive** | Cosmetic |
| Cross-package callers but NOT COVERED | **Cross-Package Gap** | See below |
| Reachable from public API, low CC | **Missing Vector** | Design targeted vector |
| Reachable from public API, high CC (>10) | **Fuzzing Target** | Both vector + fuzz harness |
| Validation/error-handling path | **Negative Vector** | Craft invalid input that triggers path |
| Optimization path (GLV, SIMD, batch) | **Edge-Case Vector** | Input that triggers optimization threshold |
| `\|`→`^` after left shift (e.g. `(t<<1) \| carry`) | **Equivalent Mutant** | Skip — bit 0 always 0, OR=XOR |
| ct_eq `&`→`\|` on Montgomery limbs | **API-Unreachable** | Needs library-internal tests, not vectors |
| Equivalent mutation (behavior unchanged) | **False Positive** | Skip |

### Step 4: Identify Cross-Package Test Gaps

**Critical pitfall:** Mutation frameworks often only run tests
within the same package as the mutation. For Go (gremlins) and
Rust (cargo-mutants), this means:

- A mutation in `hash_to_curve/g2.go` only runs tests in the
  `hash_to_curve` package, NOT tests in the parent `bls12381`
  package that imports it
- Functions that are fully exercised by cross-package tests
  will appear as NOT COVERED — these are **false positives**
- To confirm: check if the mutated function is called from a
  test in a *different* package that wouldn't be run

To resolve cross-package gaps:
1. Add a thin test in the sub-package that calls through the
   same code path as the cross-package test
2. Or run gremlins with `--test-pkg ./...` (if supported)
3. Or document as a framework limitation in the report

### Step 5: Prioritize by Security Impact

Using the call graph, rank surviving mutants by impact:

| Priority | Criteria | Example |
|----------|----------|---------|
| **P0 — Critical** | Mutant weakens validation/equality/authentication | `ct_eq`: `&` → `\|` makes equality permissive |
| **P1 — High** | Mutant in deserialization flag parsing | `from_compressed`: `&` → `\|` accepts invalid flags |
| **P2 — Medium** | Mutant in field arithmetic internals | `Fp::square`: `\|` → `^` corrupts computation |
| **P3 — Low** | Mutant in optimization path | `phi` endomorphism: only affects performance path |
| **Skip** | Formatting, display, equivalent mutation | `Debug::fmt` return value replacement |

### Step 6: Group by Vector Strategy

Group escaped mutants by the code path they represent and the
type of test vector needed:

```
Deserialization flag validation (P1):
  - g1.rs:339,363-365,384 — from_compressed_unchecked flags
  → Need: valid-point-wrong-flag vectors

Field arithmetic (P2):
  - fp.rs:371-376,406,635-643 — subtract_p, neg, square
  → Need: field arithmetic KATs with edge-case values

Optimization thresholds (P3):
  - g1.go:68, g2.go:75 — GLV vs windowed multiplication
  → Need: scalar multiplication with large scalars

Cross-package (framework limitation):
  - hash_to_curve/g2.go:242-278 — isogeny, sgn0
  → Document as false positive or add sub-package test
```

Each group becomes a target for new test vectors in Phase 5.

---

## Phase 5: Vector Generation

For each escaped code path group, design test vectors that
force execution through that path.

### Vector Design Patterns

| Code Path Type | Vector Strategy |
|----------------|----------------|
| Point deserialization | Malformed points: wrong length, invalid field elements, off-curve, wrong subgroup, identity point |
| Signature verification | Valid sig + all single-bit corruptions of sig, pk, msg |
| Hash-to-curve | Known answer tests (KATs) with edge-case inputs: empty, single byte, max length |
| Aggregate operations | 1 signer, many signers, duplicate signers, mixed valid/invalid |
| Error handling | Every error path should have a vector that triggers it |
| Arithmetic edge cases | Zero, one, field modulus - 1, points at infinity |
| Serialization flags | Every valid flag combination + every invalid flag combination |
| Roundtrip integrity | For every valid deser vector, assert `serialize(deserialize(b)) == b` |
| Carry/reduction faults | Reimplement at reduced limb widths, inject faults, extract distinguishing inputs |

### Single-Fault Negative Vectors

Each negative vector should have **exactly one defect** with
everything else valid — this isolates which validation check is
being tested. See [references/vector-patterns.md](references/vector-patterns.md)
for per-flag construction examples.

### Fault Simulation (Limb-Width Reimplementation)

When mutation testing only applies local operator swaps, deeper
architectural bugs (carry propagation, reduction overflow) go
untested. To close this gap, reimplement the target algorithm
at reduced limb widths (8, 16, 25, 32 bits) and deliberately
inject faults — then generate vectors that catch them.

See [references/fault-simulation.md](references/fault-simulation.md)
for the full methodology: limb-width selection, fault injection
catalog, vector extraction, and validation workflow.

### Cross-Implementation Verification

Every new test vector MUST be verified against at least two
independent implementations before being added to the suite:

1. Generate the vector using implementation A
2. Verify with implementation B (different codebase, ideally different language)
3. If B disagrees, investigate — one implementation has a bug

### Vector Format

Use Wycheproof JSON format (`algorithm`, `testGroups[].tests[]`
with `tcId`, `comment`, `result`, `flags`). See
[references/vector-patterns.md](references/vector-patterns.md)
for the full schema.

**Wycheproof contributions:** Use Wycheproof's `vectorgen` tool rather
than formatting vector files directly. Supply the generated changes as an
envelope. The `vectorgen` tool can add, update, or replace vectors while
handling `tcId` assignment, test counts, canonical formatting, and schema
validation. Go-based generators can avoid the `vectorgen` CLI tool and instead
call the programmatic `github.com/c2sp/wycheproof/vectorgen` API.

See [references/lessons-learned.md](references/lessons-learned.md)
§14 and the upstream
[vectorgen guide](https://github.com/C2SP/wycheproof/blob/main/doc/vectorgen.md)
for the current workflow and commands.

---

## Phase 6: Validation

Re-run mutation testing with the new test vectors included.

**Tip:** Use per-file mutation testing for fast iteration during
vector development (see [references/lessons-learned.md](references/lessons-learned.md) §12).
Only run full-crate tests for the final comparison.

### Before/After Comparison

| Metric | Baseline | With New Vectors | Delta |
|--------|----------|------------------|-------|
| Killed | X | Y | Y - X |
| Survived | A | B | A - B (should decrease) |
| Not Covered | C | D | C - D (should decrease) |
| Efficacy % | E% | F% | F - E |

### Success Criteria

Vectors have both **retroactive** value (killing mutants in
existing code) and **proactive** value (catching bugs in future
implementations). Generate both kinds — boundary-condition vectors
may not improve kill rates in mature libraries but will catch bugs
in new implementations. See
[references/lessons-learned.md](references/lessons-learned.md) §13.

**Retroactive (measurable):** previously survived/uncovered mutants
become killed, no regressions.

**If kill rates don't change:** the implementation's own tests
likely already cover those paths. The vectors still add
cross-implementation verification value. Document which case
applies.

---

## Output Format

Write `VECTOR_FORGE_REPORT.md` covering: target algorithm,
implementations tested, baseline results, escape analysis,
new vectors generated, after results, before/after delta, and
conclusions. See
[references/report-template.md](references/report-template.md)
for the full template.

---

## Quality Checklist

Before delivering:

- [ ] At least one pure implementation mutation-tested (not just FFI wrappers)
- [ ] Baseline run completed with existing vectors
- [ ] Trailmark call graph built for each implementation
- [ ] All escaped mutants triaged using graph-informed classification
- [ ] Cross-package false positives identified and documented
- [ ] Security-critical mutations (ct_eq, validation, auth) prioritized as P0/P1
- [ ] Fault simulation and mutation-derived vectors cross-verified against 2+ implementations
- [ ] After run completed with new vectors included
- [ ] Before/after delta computed and explained
- [ ] Report written to `VECTOR_FORGE_REPORT.md`
- [ ] New test vectors saved in standard format (Wycheproof JSON)

---

## Integration

| Skill | Relationship |
|-------|-------------|
| **genotoxic** (required for Phase 4) | Provides graph-informed triage — call graph cuts actionable mutants by 30-50% |
| **mutation-testing** (mewt/muton) | Use for Solidity; Vector Forge is language-agnostic |
| **property-based-testing** | Better than hand-crafted vectors for bitwise mutations in field arithmetic |
| **testing-handbook-skills** (fuzzing) | Functions with CC > 10 and surviving mutants need both vectors and fuzz harnesses |

---

## Supporting Documentation

- **[references/mutation-frameworks.md](references/mutation-frameworks.md)** -
  Language-specific mutation testing framework setup
- **[references/vector-patterns.md](references/vector-patterns.md)** -
  Common test vector patterns for cryptographic primitives
- **[references/fault-simulation.md](references/fault-simulation.md)** -
  Limb-width reimplementation for carry, reduction, and overflow faults
- **[references/report-template.md](references/report-template.md)** -
  Full markdown template for the Vector Forge report
- **[references/lessons-learned.md](references/lessons-learned.md)** -
  BLS12-381 case study: FFI kill rates, timeout masking, cross-package
  false positives, bitwise mutation gaps, and security-critical priorities

## agents

```

```

## agents/openai.yaml

```yaml
interface:
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"
```

## assets

```

```

## assets/trail-of-bits-mark.svg

```

```

## references

```

```

## references/fault-simulation.md

# Fault Simulation via Limb-Width Reimplementation

Generate test vectors that catch carry propagation, modular
reduction, and overflow bugs by reimplementing the target
algorithm at non-standard limb widths and deliberately injecting
architectural faults.

## Why Mutation Testing Misses These

Mutation testing frameworks apply local operator swaps (`+` → `-`,
`&` → `|`, `<` → `<=`). They cannot:

- Change the number of limbs in a multi-precision integer
- Alter carry propagation logic across limb boundaries
- Modify reduction strategies (Barrett vs Montgomery vs schoolbook)
- Introduce off-by-one errors in limb iteration bounds

These are exactly the bugs that cause real-world cryptographic
vulnerabilities (e.g., carry bugs in OpenSSL, Go's P-256).

## Methodology

### Step 1: Select Limb Widths

Reimplement the target operation at multiple limb widths to
exercise different carry propagation patterns:

| Limb Width | Why |
|-----------|-----|
| 8-bit | Maximum carries per operation, exposes propagation bugs |
| 16-bit | Intermediate carry frequency, different overflow boundary |
| 25-bit | Non-power-of-2 — exercises radix-2^25 representations (common in constant-time code) |
| 32-bit | Standard width, catches 64-bit-specific assumptions |
| 51-bit | Radix-2^51 (used in curve25519 implementations) |

Choose widths that differ from the production implementation.
If the production code uses 64-bit limbs, test at 8, 25, and
32 bits. If it uses radix-2^25.5 (like ref10), test at 8, 16,
and 32 bits.

### Step 2: Implement a Minimal Reference

You do NOT need a full cryptographic library. Implement only
the specific operation under test:

- **Field arithmetic:** add, subtract, multiply, square, reduce
- **Scalar arithmetic:** multiply, reduce mod group order
- **Point operations:** add, double, scalar multiply

The implementation must:
1. Produce correct results for known test vectors
2. Be simple enough to manually verify (schoolbook algorithms)
3. Use the chosen limb width throughout

### Step 3: Inject Faults

For each reimplementation, introduce ONE fault at a time from
this catalog:

| Fault Category | Specific Fault | What It Catches |
|---------------|----------------|-----------------|
| **Carry propagation** | Drop carry on limb N-1 → N | Missing final carry |
| **Carry propagation** | Off-by-one in carry shift | Carry to wrong bit position |
| **Carry propagation** | Skip carry in multiplication inner loop | Accumulator overflow |
| **Reduction** | Reduce modulo (p+1) instead of p | Wrong modulus |
| **Reduction** | Skip final conditional subtraction | Non-canonical output |
| **Reduction** | Off-by-one in reduction loop bound | Incomplete reduction |
| **Overflow** | Truncate intermediate to limb width before carry | Silent overflow |
| **Overflow** | Use signed instead of unsigned limbs | Sign extension corruption |
| **Boundary** | Return 0 for input = p-1 | Fence-post on modulus boundary |
| **Boundary** | Accept p as valid field element | Off-by-one in validation |

### Step 4: Extract Distinguishing Vectors

For each injected fault:

1. Run the faulted implementation against a broad input set
   (random values + boundary values from the edge-case table)
2. Find inputs where `faulted_output != correct_output`
3. These inputs become test vectors — any correct implementation
   must produce the correct output, and the faulted implementation
   must diverge

**Key insight:** The distinguishing inputs often cluster around
specific value patterns:

| Fault Type | Likely Distinguishing Inputs |
|-----------|----------------------------|
| Carry propagation | Values where limb N-1 is at max (all bits set) |
| Reduction | Values near the modulus: p-1, p-2, 2p-1 |
| Overflow | Products of large values: (p-1) * (p-1) |
| Boundary | Exact modulus, modulus ± 1, zero, one |

### Step 5: Validate Against Production

Run the extracted vectors against the production implementation:

1. If production passes → vector validates production correctness
   for that fault class
2. If production fails → you found a real bug (the production
   implementation has the same fault class)

Both outcomes are valuable. Outcome 2 is a finding.

## Example: Field Multiplication Carry Bug

Target: 256-bit prime field multiplication (4×64-bit limbs in
production).

Reimplementation: 8×32-bit limbs, schoolbook multiplication.

Injected fault: Drop carry from limb 3 → limb 4 in the
multiplication accumulator.

```
Input A: 0xFFFFFFFF_FFFFFFFF_FFFFFFFF_FFFFFFFF (limbs 0-3 maxed)
Input B: 0x00000000_00000000_00000000_00000002 (simple multiplier)

Correct:  A * B mod p = <correct value>
Faulted:  A * B mod p = <wrong value, carry lost at limb boundary>
```

The pair (A, B, correct_result) becomes a test vector. Any
implementation that drops the carry at that boundary will fail.

## Integration with Phase 5

Fault simulation vectors complement mutation-derived vectors:

| Source | Catches |
|--------|---------|
| Mutation testing escapes | Local operator bugs in existing code |
| Fault simulation | Architectural bugs in carry/reduce/overflow logic |

Run fault simulation AFTER mutation testing baseline (Phase 3)
but BEFORE the final validation run (Phase 6). Add fault
simulation vectors to the same test suite as mutation-derived
vectors for the combined before/after comparison.

## Limb-Width Selection Heuristic

For a production implementation with W-bit limbs and N limbs:

1. Always include 8-bit (maximum carry stress)
2. Include at least one non-power-of-2 width (25 or 51 bits)
3. Include a width that is exactly half of production (W/2)
4. If production uses a non-standard radix, include the nearest
   power-of-2 width

This ensures carry boundaries fall at different positions than
production, exposing width-specific assumptions.

## references/lessons-learned.md

# Lessons Learned (BLS12-381 Case Study)

Patterns observed during mutation testing of gnark-crypto (Go),
blst (Rust FFI), and zkcrypto/bls12_381 (Rust):

## 1. FFI Wrappers Have 0% Kill Rate

Mutating blst's Rust bindings produced 0 kills across 79 mutants.
The Rust layer is thin wrappers around C/assembly — mutations to
`PartialEq`, `miller_loop_n`, `finalverify` all survive because
the real logic is in C. **Always identify FFI crates in Phase 1
and skip them for Rust/Go mutation testing. Use Mull for the C layer.**

## 2. Timeouts Mask Surviving Mutants

Adding Wycheproof tests to gnark-crypto changed gremlins' timeout
calibration, converting 3,144 timeouts into 2,533 killed + 476
lived. The 476 LIVED mutants were previously hidden. **Always
resolve timeouts before comparing baselines. Increase timeout
coefficients (`--timeout-coefficient 3`) for the first run.**

## 3. Cross-Package NOT COVERED ≠ Dead Code

In gnark-crypto, `hash_to_curve/g2.go` functions appeared as NOT
COVERED even though `HashToG2()` in the parent package calls them.
Gremlins only runs same-package tests for each mutated file.
**Use the call graph to identify cross-package false positives
before generating vectors for NOT COVERED mutants.**

## 4. Comprehensive Test Suites Resist Vector Coverage

gnark-crypto's own test suite already kills every mutant that
Wycheproof vectors can reach. The 53 NOT COVERED BLS mutants are
identical between baseline and Wycheproof runs. **The value of
Wycheproof vectors for well-tested libraries is cross-implementation
semantic validation, not code coverage improvement.**

## 5. Bitwise Operator Mutations Reveal Precision Gaps

In zkcrypto, 164 mutants survived — mostly `&` → `|` and `|` → `^`
in field arithmetic (`Fp::square`, `Fp::neg`, `Scalar::ct_eq`).
These mutations corrupt specific bits in multi-precision arithmetic.
**Killing bitwise mutations requires test vectors that exercise
every limb of the field representation, not just the "happy path"
with small values.** Vectors needed:
- Field element = modulus - 1 (all limbs active)
- Field element with alternating 0/1 limb patterns
- Scalar values near the group order boundary

## 6. Security-Critical Mutations Need Priority

`Scalar::ct_eq` with `&` → `|` makes equality permissive — more
values compare as equal. This could cause signature verification
to accept invalid signatures. **Always prioritize mutations in
equality checks, validation logic, and authentication paths.**

## 7. Test Harnesses Must Assert Rejection, Not Just Acceptance

The initial zkcrypto Wycheproof harness only checked that valid
vectors deserialized successfully. It never checked that invalid
vectors were *rejected*. This meant all flag-permissive mutations
(`&` → `|` in `from_compressed_unchecked`) survived — the mutated
code accepted invalid flags, but no test asserted rejection.

Adding `else if result == "invalid" { assert!(deser.is_none()) }`
killed ALL P1 flag mutations in both G1 and G2. **Every test
harness needs both positive assertions (valid accepted) AND
negative assertions (invalid rejected). Without negative
assertions, permissive mutations are invisible.**

## 8. Roundtrip Assertions Catch Field Arithmetic Corruption

`compress(decompress(bytes)) == bytes` is a powerful generic
assertion that catches carry propagation, square root, negation,
and modular reduction bugs without knowing the internal field
representation. If `Fp::square` or `Fp::subtract_p` has a carry
bug, the recovered y-coordinate will be wrong, changing the sort
bit in the re-compressed encoding.

This killed 15 previously-missed fp.rs mutations. **Add roundtrip
assertions to every deserialization test that handles valid
vectors. It's cheap and catches deep arithmetic bugs.**

## 9. Equivalent Mutant Pattern: Shift-then-OR

In `Fp::square` and `Scalar::square`, the doubling step uses
`(t << 1) | (prev >> 63)`. The mutation `|` → `^` survives
because `(t << 1)` always clears bit 0 (left shift), and
`(prev >> 63)` only affects bit 0. Since `0 | x == 0 ^ x` for
any `x`, these mutations are provably equivalent — they cannot
change behavior regardless of input.

14 of the "survived" mutations across scalar.rs and fp.rs are
this pattern. **When triaging `|` → `^` mutations in shift-based
expressions, check if the OR'd bit position is always 0 after the
shift. If so, classify as equivalent and skip.**

## 10. Montgomery Representation Creates an API Testing Boundary

`Scalar::ct_eq` computes `limb[0].ct_eq & limb[1].ct_eq & ...`.
With `&` → `|`, it returns equal if ANY limb matches. To kill
this, you need two different scalars that share at least one
internal Montgomery limb value. But `Scalar::from_raw` applies
Montgomery reduction (multiply by R), spreading the value across
all limbs unpredictably.

You cannot construct Montgomery-limb-aware test values through the
public API. **Mutations in internal representation comparisons
(ct_eq on limb arrays) require library-internal property-based
tests, not external test vectors. Document these as "not reachable
via API" rather than wasting time on vector design.**

## 11. Single-Fault Negative Vectors Isolate Validation Checks

The most effective flag vectors had exactly ONE defect — e.g.,
a valid G2 point with only the compression flag cleared. This
isolates the specific flag check: if `from_compressed` accepts
the vector, that particular validation is broken.

Multi-fault vectors (wrong flag AND wrong length AND off-curve)
are less useful because multiple checks reject them — you can't
tell which check is doing the work. **Design negative vectors with
the minimum number of defects to target a single validation check.
Keep the rest of the encoding valid.**

## 12. Per-File Mutation Testing for Fast Iteration

Full-crate mutation testing takes 30+ minutes. Per-file runs
(`cargo mutants -f src/scalar.rs`) take 2-5 minutes. When
iterating on test design for a specific file's mutations, use
per-file mode for rapid feedback:

```bash
# Fast iteration loop:
# 1. Edit test
# 2. Run per-file mutation test
# 3. Check missed.txt
# 4. Repeat
cargo mutants -j 8 --timeout 120 -f src/scalar.rs
cat mutants.out/missed.txt
```

**Use per-file mode during Phase 5 (vector generation) and
Phase 6 (validation). Only run full-crate tests for the final
before/after comparison.**

## 13. Vectors Have Retroactive and Proactive Value

Mutation testing measures retroactive value: which vectors kill
mutants in existing implementations. But test vectors also have
proactive value: catching bugs in future implementations that
haven't been written yet.

Not-on-curve, wrong-subgroup, and field-boundary vectors killed
zero additional mutants in mature zkcrypto code — the library
already validates these cases. But a new BLS12-381 implementation
that skips a subgroup check or mishandles x ≈ p will fail these
vectors immediately.

**Generate boundary-condition vectors even when they don't improve
mutation kill rates. They're a net for the implementations that
will be written tomorrow, not just the ones that exist today.**

## 14. Use Wycheproof's Vector Tooling

Wycheproof no longer relies on the Python `reformat_json.py` workflow.
Its `vectorgen` tool accepts a small JSON envelope and adds, updates,
or replaces vector data while handling `tcId` assignment,
`numberOfTests`, canonical formatting, and schema validation.

**Use `vectorgen` instead of writing or reformatting complete vector
files by hand. Go-based generators may call the programmatic
`github.com/c2sp/wycheproof/vectorgen` API instead of invoking the
CLI. Follow the upstream
[vectorgen guide](https://github.com/C2SP/wycheproof/blob/main/doc/vectorgen.md)
for current requirements, commands, envelope shapes, and validation.**

## references/mutation-frameworks.md

# Mutation Testing Frameworks

Language-specific setup, execution, and output parsing for mutation testing.

## Contents

- Language detection
- Framework reference table
- Per-language setup and commands
- Parsing survived mutants
- Necessist (test statement removal)

---

## Installation Policy

**Every mutation testing framework listed below MUST be installed before
proceeding.** If a framework command is not found or fails to install:

1. Try the primary install method for the platform
2. Try the alternative install methods listed in the language section
3. If all methods fail, **report the error to the user** — do NOT fall
   back to "manual mutation analysis", "manual verification", or any
   other substitute that skips running the tool

Manual analysis is not a replacement for mutation testing. Mutation
testing tools systematically apply hundreds or thousands of mutations
that manual review cannot replicate. Skipping installation and doing
manual analysis produces false confidence with minimal actual coverage.

---

## Language Detection

Use file extensions to determine the target language, then select the
appropriate mutation framework:

| Extensions | Language | Framework |
|-----------|----------|-----------|
| `.py` | Python | pytest-gremlins or mutmut |
| `.js`, `.jsx`, `.ts`, `.tsx` | JavaScript/TypeScript | Stryker |
| `.rs` | Rust | cargo-mutants |
| `.go` | Go | gremlins or go-mutesting |
| `.java` | Java | PITest |
| `.c`, `.h`, `.cpp`, `.hpp`, `.cc` | C/C++ | Mull |
| `.cs` | C# | Stryker.NET |
| `.rb` | Ruby | mutant |
| `.php` | PHP | Infection |
| `.hs` | Haskell | MuCheck or Hedgehog |

---

## Python: pytest-gremlins (preferred) or mutmut

### pytest-gremlins

Faster alternative to mutmut. Uses mutation switching (no file I/O or
module reloads), coverage-guided test selection, and parallel execution.
Requires Python 3.11+.

**Install:**

```bash
uv add --dev pytest-gremlins
```

**Run:**

```bash
uv run pytest --gremlins
```

No configuration needed — it integrates directly with pytest.

**Parse survived mutants:** pytest-gremlins reports survived gremlins
in its test output. Each entry includes the file, line, mutation type,
and original/replacement values.

### mutmut

**Install:**

```bash
uv add --dev mutmut
```

**Configure** in `pyproject.toml`:

```toml
[tool.mutmut]
paths_to_mutate = "src/"
tests_dir = "tests/"
runner = "python -m pytest -x -q"
```

**Run:**

```bash
uv run mutmut run
uv run mutmut results
```

**Parse survived mutants:**

```bash
# List survived mutant IDs
uv run mutmut results | grep "Survived"

# Show specific mutant
uv run mutmut show <id>

# Export all results as JSON (mutmut 3.x+)
uv run mutmut junitxml > mutmut-results.xml
```

**Extract from results output:**
Each survived mutant line contains the file path, line number, and
mutation description. Parse with:

```bash
uv run mutmut results 2>&1 | grep "Survived" | \
  sed 's/.*Survived: //'
```

**macOS note:** If using rustworkx or other Rust extensions, set:

```bash
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
```

---

## JavaScript/TypeScript: Stryker

**Install:**
```bash
pnpm add -D @stryker-mutator/core
pnpm dlx stryker init
```

**Configure** `stryker.config.json`:
```json
{
  "mutate": ["src/**/*.ts", "!src/**/*.test.ts"],
  "testRunner": "vitest",
  "reporters": ["json", "clear-text"],
  "jsonReporter": { "fileName": "stryker-report.json" }
}
```

**Run:**
```bash
pnpm dlx stryker run
```

**Parse survived mutants:**
```bash
# JSON report at reports/mutation/stryker-report.json
# Filter survived:
cat reports/mutation/stryker-report.json | \
  jq '.files | to_entries[] | .value.mutants[] | select(.status == "Survived")'
```

**Output fields:** `mutatorName`, `replacement`, `location.start.line`,
`location.start.column`, `fileName`.

---

## Rust: cargo-mutants

**Install:**
```bash
cargo install cargo-mutants
```

**Run:**
```bash
cargo mutants --json
```

**Parse survived mutants:**
```bash
# Results in mutants.out/outcomes.json
cat mutants.out/outcomes.json | \
  jq '.[] | select(.outcome == "survived")'
```

**Output fields:** `scenario.function`, `scenario.file`, `scenario.line`,
`scenario.replacement`, `outcome`.

**Filtering by module:**
```bash
cargo mutants --file src/parser.rs --json
```

---

## Go: gremlins (preferred) or go-mutesting

### gremlins

Actively maintained mutation testing tool for Go. Works best on
small-to-medium Go modules (microservices, libraries).

**Install:**

```bash
# macOS
brew tap go-gremlins/tap && brew install gremlins

# Any platform with Go
go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
```

**Run:**

```bash
gremlins unleash .
```

**Parse results:** gremlins reports survived mutants to stdout with
file path, line number, and mutation type.

### go-mutesting

**Install:**

```bash
go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest
```

**Run:**

```bash
go-mutesting ./...
```

**Parse results:** go-mutesting prints survived mutants to stdout.
Each line contains the file, line number, and mutation operator.

### Alternative: native fuzzing (Go 1.18+)

```bash
go test -fuzz=FuzzTarget -fuzztime=60s ./pkg/...
```

---

## Java: PITest

**Configure** in `pom.xml`:
```xml
<plugin>
  <groupId>org.pitest</groupId>
  <artifactId>pitest-maven</artifactId>
  <configuration>
    <targetClasses>com.example.*</targetClasses>
    <outputFormats>XML,CSV</outputFormats>
  </configuration>
</plugin>
```

**Run:**
```bash
mvn org.pitest:pitest-maven:mutationCoverage
```

**Parse survived mutants:**
```bash
# Results in target/pit-reports/mutations.xml
# Filter SURVIVED status
grep 'status="SURVIVED"' target/pit-reports/*/mutations.xml
```

**Output fields:** `mutatedClass`, `mutatedMethod`, `lineNumber`,
`mutator`, `status`.

---

## C/C++: Mull

Mull is an LLVM-based mutation testing tool for C and C++. It works as a
compiler plugin — it instruments the compiled test binary with mutations,
then selectively activates them during test execution.

**Mull requires a specific LLVM version.** Check the Mull releases page
for the LLVM version supported by the latest release. The project must
compile with the matching Clang version.

### Install

Mull is distributed as prebuilt binaries on GitHub Releases. Each
binary targets a specific LLVM version — **you must match the Mull
binary's LLVM version to the Clang version installed on the system.**

**Step 1: Determine your Clang/LLVM version:**

```bash
clang --version
# Look for the major version number (e.g., 19, 20)
```

If Clang is not installed, install it first. On macOS, use
`brew install llvm@<version>`. On Ubuntu, use
`sudo apt-get install clang-<version>`.

**Step 2: Download the matching Mull binary.**

Go to the [Mull releases page](https://github.com/mull-project/mull/releases/latest)
and download the asset matching your LLVM version, platform, and
architecture. Asset naming convention:

```text
Mull-<LLVM_MAJOR>-<MULL_VERSION>-LLVM-<LLVM_FULL>-<OS>-<ARCH>.<ext>
```

Examples (Mull 0.29.0):

| Platform | LLVM | Asset |
| -------- | ---- | ----- |
| macOS arm64 | 19 | `Mull-19-0.29.0-LLVM-19.1.7-macOS-aarch64-*.zip` |
| macOS arm64 | 20 | `Mull-20-0.29.0-LLVM-20.1.8-macOS-aarch64-*.zip` |
| Ubuntu 24.04 amd64 | 19 | `Mull-19-0.29.0-LLVM-19.1.1-ubuntu-amd64-24.04.deb` |
| Ubuntu 24.04 amd64 | 20 | `Mull-20-0.29.0-LLVM-20.1.2-ubuntu-amd64-24.04.deb` |
| RHEL 9 amd64 | 20 | `Mull-20-0.29.0-LLVM-20.1.8-rhel-amd64-9.6.rpm` |

**Step 3: Install.**

**macOS:**

```bash
# 1. Install the matching LLVM/Clang version via Homebrew
#    Check Mull releases for which LLVM versions are available
brew install llvm@18  # or llvm@19, llvm@20

# 2. Download the matching Mull binary
gh release download --repo mull-project/mull \
  --pattern 'Mull-18-*-macOS-aarch64-*.zip'  # match LLVM version
unzip Mull-18-*.zip

# 3. Install binaries to a known location
sudo mkdir -p /usr/local/bin /usr/local/lib
sudo cp usr/local/bin/mull-runner-* /usr/local/bin/
sudo cp usr/local/bin/mull-reporter-* /usr/local/bin/
sudo cp usr/local/lib/mull-ir-frontend-* /usr/local/lib/

# 4. Verify
mull-runner-18 --version
/opt/homebrew/opt/llvm@18/bin/clang --version
```

**Important macOS notes:**
- The Mull binary's LLVM version must **exactly match** the installed
  Clang. Using `brew install llvm@18` with `Mull-19-*` will not work.
- Use the Homebrew Clang, not Apple's system Clang (which is a
  different LLVM version and lacks plugin support).
- Set `ulimit -n 1024` before running `mull-runner` (see Environment
  Setup section below).

**Ubuntu/Debian:**

```bash
# Option A: Cloudsmith APT repository
curl -1sLf \
  'https://dl.cloudsmith.io/public/mull-project/mull-stable/setup.deb.sh' \
  | sudo -E bash
sudo apt-get update
sudo apt-get install mull-19  # match your LLVM version

# Option B: Direct .deb from GitHub
gh release download --repo mull-project/mull \
  --pattern 'Mull-19-*-ubuntu-amd64-24.04.deb'
sudo dpkg -i Mull-19-*.deb
```

**RHEL/Fedora:**

```bash
# Option A: Cloudsmith RPM repository
curl -1sLf \
  'https://dl.cloudsmith.io/public/mull-project/mull-stable/setup.rpm.sh' \
  | sudo -E bash
sudo dnf install mull-20  # match your LLVM version

# Option B: Direct .rpm from GitHub
gh release download --repo mull-project/mull \
  --pattern 'Mull-20-*-rhel-amd64-*.rpm'
sudo rpm -i Mull-20-*.rpm
```

**Verify installation:**

```bash
mull-runner --version
```

If `mull-runner` is not found after installation, check that the
install prefix is on `$PATH`. **DO NOT** fall back to "manual mutation
analysis" — fix the installation or report the error.

### Configure and Build

Mull requires the project to be compiled with Clang and the Mull
compiler plugin. The plugin injects mutations at the LLVM IR level.

**Key build requirements:**
- Use the **same Clang version** that matches your Mull release
- Pass `-fpass-plugin=<path-to-mull-ir-frontend>` to the compiler
- Use `-g -O0` (debug info required, no optimization)
- **Disable assembly** (`--disable-asm`) — Mull can only mutate
  LLVM IR, not hand-written assembly
- Disable hardening flags that interfere: `--disable-ssp --disable-pie`

**Find the plugin path:**

```bash
# The plugin is typically installed alongside mull-runner:
# Linux:  /usr/lib/mull-ir-frontend-<N>  (or mull-ir-frontend.so)
# macOS:  <install-prefix>/lib/mull-ir-frontend-<N>
# Use `find` or `locate` if unsure:
find /usr/local /opt/homebrew /tmp -name "mull-ir-frontend*" 2>/dev/null
```

**Simple projects:**

```bash
MULL_PLUGIN=$(find /usr/local /opt/homebrew -name "mull-ir-frontend*" 2>/dev/null | head -1)
clang -fpass-plugin=$MULL_PLUGIN -g -O0 \
  -o test_binary test_main.c src/*.c
```

**Autotools projects (configure/make):**

```bash
MULL_PLUGIN=$(find /usr/local /opt/homebrew -name "mull-ir-frontend*" 2>/dev/null | head -1)
LLVM_BIN=$(dirname $(which clang))  # or /opt/homebrew/opt/llvm@18/bin

CC=$LLVM_BIN/clang \
CFLAGS="-fpass-plugin=$MULL_PLUGIN -g -grecord-command-line -O0" \
./configure --disable-shared --enable-static --disable-asm \
  --disable-ssp --disable-pie
make clean && make -j$(nproc)
```

**CMake projects:**

```cmake
set(CMAKE_C_COMPILER clang)
set(CMAKE_CXX_COMPILER clang++)
set(MULL_PLUGIN_PATH "" CACHE STRING "Path to Mull plugin")
if(MULL_PLUGIN_PATH)
  add_compile_options(-fpass-plugin=${MULL_PLUGIN_PATH} -g -O0)
endif()
```

```bash
MULL_PLUGIN=$(find /usr/local /opt/homebrew -name "mull-ir-frontend*" 2>/dev/null | head -1)
cmake -B build -DMULL_PLUGIN_PATH=$MULL_PLUGIN
cmake --build build
```

### Run

```bash
# Set FD limit (required on macOS, see Environment Setup)
ulimit -n 1024

# Run with GoogleTest binary
mull-runner --allow-surviving --no-output --timeout=5000 \
  --reporters=Elements --report-dir=mull-report ./build/tests

# Run with custom test command
mull-runner --test-program=ctest ./build/tests

# Generate report
mull-runner --report-dir=mull-report ./build/tests
```

**Recommended flags:**
- `--allow-surviving` — don't treat survived mutants as errors
- `--no-output` — suppress stdout/stderr from mutant runs
- `--timeout=5000` — 5 second timeout per mutant (adjust based on
  baseline test runtime; use 1000ms for tests completing in <100ms)
- `--reporters=Elements` — JSON output in Mutation Testing Elements
  format (machine-parseable for triage)
- `--report-dir=DIR` — write JSON reports to this directory
- `--report-name=NAME` — control output filename (useful when
  running multiple test binaries)
- `--workers=N` — parallelism for mutant execution (defaults to
  CPU count)

### Parse survived mutants

Mull outputs results to stdout and optionally to report files. Each
survived mutant includes the file path, line number, and mutation type.

```bash
# JSON report (if --report-dir used)
cat mull-report/mutation-testing-report.json | \
  jq '.files | to_entries[] | .value.mutants[] |
    select(.status == "Survived")'
```

### Environment Setup (Required)

**Before running `mull-runner`, always set a bounded file descriptor
limit.** On macOS (especially Tahoe / macOS 26+), the default
`ulimit -n` is `unlimited`, which causes Mull's subprocess library
(reproc) to fail with `EINVAL` when it tries to close inherited file
descriptors in the forked child process. The fix:

```bash
# REQUIRED before any mull-runner invocation
ulimit -n 1024
```

Add this to your Mull runner scripts or shell session. Without it,
you will see:

```
[error] Cannot run executable: Invalid argument
```

**Root cause:** reproc calls `getrlimit(RLIMIT_NOFILE)` to determine
the max FD to close. When the soft limit is `RLIM_INFINITY`, reproc
computes `max_fd = INT_MAX`, which exceeds its internal
`MAX_FD_LIMIT` (1048576) safety check, causing the child to exit
with `EMFILE`.

### Troubleshooting

| Problem | Solution |
| ------- | -------- |
| `mull-runner: command not found` | Install Mull using the instructions above |
| `Cannot run executable: Invalid argument` | Run `ulimit -n 1024` before `mull-runner` (see Environment Setup above) |
| LLVM version mismatch | Install the LLVM version matching your Mull release |
| Plugin load error | Recompile with matching Clang version |
| No mutants generated | Ensure `-g -O0` flags and Mull plugin are active |
| Tests fail without mutations | Fix test suite first — Mull needs a green baseline |
| Original test failed (timeout) | Increase `--timeout` or skip tests with long baseline runtimes |

---

## C#: Stryker.NET

**Install:**
```bash
dotnet tool install -g dotnet-stryker
```

**Run:**
```bash
dotnet stryker --reporter json
```

**Parse survived mutants:**
```bash
cat StrykerOutput/*/reports/mutation-report.json | \
  jq '.files | to_entries[] | .value.mutants[] | select(.status == "Survived")'
```

---

## Ruby: mutant

**Install:**
```bash
gem install mutant
```

**Run:**
```bash
bundle exec mutant run --include lib --require mylib 'MyLib*'
```

**Parse results:** mutant outputs surviving mutations to stdout with
file paths, line numbers, and mutation descriptions.

---

## PHP: Infection

**Install:**
```bash
composer require --dev infection/infection
```

**Run:**
```bash
vendor/bin/infection --show-mutations --min-msi=0
```

**Parse survived mutants:**
```bash
# JSON log at infection-log.json
cat infection-log.json | jq '.survived[]'
```

---

## Haskell: MuCheck or Hedgehog

MuCheck is the primary mutation testing tool for Haskell. For projects
without MuCheck support, property-based testing with Hedgehog or
QuickCheck serves as a mutation-resistant alternative.

### MuCheck

**Install:**
```bash
cabal install MuCheck
```

**Run:**
```bash
mucheck -t "cabal test" src/MyModule.hs
```

MuCheck applies standard mutation operators (negate guards, swap
operators, replace patterns) to the target module and runs the test
suite against each mutant.

**Parse survived mutants:** MuCheck prints results to stdout. Each
survived mutant includes the file path, line number, and mutation
description (e.g., "Negated guard on line 42").

**Limitations:** MuCheck requires the project to build with cabal and
has limited support for large multi-module projects. For Stack-based
projects, wrap the test command: `mucheck -t "stack test" src/Module.hs`.

### Alternative: property-based testing as mutation proxy

For projects where MuCheck is impractical, strong property-based tests
provide equivalent mutation resistance. Properties that assert invariants
over all inputs catch most mutations that MuCheck would surface.

**Hedgehog (preferred):**
```bash
cabal install hedgehog
```

Write properties in `test/` that cover arithmetic, branching, and
boundary behavior. A comprehensive property suite catches the same
classes of defects as mutation testing.

**QuickCheck:**
```bash
cabal install QuickCheck
```

QuickCheck properties work similarly. Use `forAll` with custom generators
to target the input domain of each function under test.

---

## Universal Mutant Record Format

Regardless of framework, normalize each survived mutant to this schema
before feeding into Phase 3 triage:

```json
{
  "file_path": "src/parser.py",
  "line": 42,
  "mutation_type": "arithmetic_operator",
  "original": "+",
  "replacement": "-",
  "function_name": "parse_header",
  "status": "survived"
}
```

Map the containing function name by matching `file_path:line` against
trailmark graph nodes using their `location.start_line` and
`location.end_line` ranges.

---

## Necessist: Test Statement Removal

Necessist complements mutation testing by removing statements and method
calls from **test code** and re-running the tests. If a test still passes
after a statement is removed, that statement may be unnecessary —
indicating weak assertions or missing coverage.

Mutation testing mutates production code to check if tests detect changes.
Necessist mutates test code to check if each test statement is actually
needed. Run both when the language supports it.

### Supported Frameworks

| Framework | Language | Auto-detected |
| --------- | -------- | ------------- |
| Anchor | Rust (Solana) | Yes |
| Foundry | Solidity | Yes |
| Go | Go | Yes |
| Hardhat (TypeScript) | TypeScript | Yes |
| Rust | Rust | Yes |
| Vitest | JavaScript/TypeScript | Yes |

Necessist auto-detects the framework from project files. Use `--framework`
to override when auto-detection fails.

### Install

```bash
cargo install necessist
```

### Run

```bash
# Auto-detect framework, run on all test files
necessist

# Explicit framework selection
necessist --framework foundry

# Target specific test files
necessist tests/test_parser.rs tests/test_validator.rs

# Set timeout per test (default 60s, 0 = no timeout)
necessist --timeout 120

# Resume a previous run (results stored in SQLite)
necessist --resume
```

### Parse Results

Necessist stores results in a SQLite database by default. Use `--dump`
to export:

```bash
necessist --dump
```

Each result line contains the test file, line number, the removed
statement, and whether the test passed or failed after removal. Filter
to **passed after removal** entries — these are the findings to triage.

### Configuration

Create `necessist.toml` in the project root (`necessist --default-config`
generates a template):

```toml
ignored_functions = ["println", "eprintln", "dbg"]
ignored_methods = ["clone", "to_string", "unwrap"]
ignored_macros = ["debug_assert", "trace"]
```

- `ignored_functions` — Skip removals of these function calls
- `ignored_methods` — Skip removals of these method calls
- `ignored_macros` — Skip removals of these macro invocations

For Foundry projects, consider ignoring common cheatcodes that are
setup-only (e.g., `vm.label`, `vm.deal` for labeling/funding).

### Normalized Necessist Record Format

Normalize each finding before feeding into Phase 3 triage:

```json
{
  "test_file_path": "tests/test_parser.rs",
  "test_line": 42,
  "removed_statement": "parser.validate(&input)",
  "test_function": "test_parse_header",
  "status": "passed_after_removal",
  "source": "necessist"
}
```

The `source` field distinguishes necessist findings from mutation testing
results during triage and reporting. Map the removed statement to a
production function using the graph analysis algorithm described in the
`genotoxic` skill.

## references/report-template.md

# Vector Forge Report Template

Write the report to `VECTOR_FORGE_REPORT.md` in the working directory.

```markdown
# Vector Forge Report

## Target Algorithm
[Algorithm name and specification reference]

## Implementations Tested

| Library | Language | Type | Mutation Framework |
|---------|----------|------|--------------------|

## Baseline Results (Existing Vectors Only)

[Per-implementation baseline table]

## Escape Analysis

### [Implementation Name]
- Total escaped: N
- By code path:
  - [Path 1]: N mutants — [description]
  - [Path 2]: N mutants — [description]

## New Vectors Generated

| Vector ID | Target Code Path | Expected Kill |
|-----------|-----------------|---------------|

## After Results (With New Vectors)

[Per-implementation after table]

## Before/After Comparison

[Delta table per implementation]

## Conclusions
[What the vectors caught, what they missed, and why]
```

## references/vector-patterns.md

# Test Vector Patterns for Cryptographic Primitives

Patterns for designing test vectors that target specific code paths
identified through mutation testing escape analysis.

## Contents

- General principles
- Serialization / deserialization vectors
- Signature scheme vectors
- Hash-to-curve vectors
- Pairing-based cryptography vectors
- Aggregate / threshold scheme vectors
- Key encapsulation vectors
- Symmetric cipher vectors
- Mapping escaped mutants to vector patterns

---

## General Principles

### Every Vector Needs a Purpose

Each test vector should target a specific code path or validation
check. Document the purpose in the vector's `comment` field:

```json
{
  "tcId": 5,
  "comment": "signature with flipped sign bit in G2 y-coordinate",
  "result": "invalid",
  "flags": ["ModifiedSignature"]
}
```

### Cross-Implementation Verification is Mandatory

A test vector is only trustworthy if two independent implementations
agree on its result. If they disagree, one has a bug — and that
disagreement is itself a valuable finding.

### Negative Vectors are More Valuable Than Positive Ones

Valid-case vectors verify basic correctness. Invalid-case vectors
exercise error handling, validation, and rejection logic — the code
paths where security bugs hide.

### Edge Cases Over Random Cases

Random test vectors exercise the "happy path." Edge cases exercise
boundary conditions where off-by-one errors, overflow, and
validation gaps lurk.

---

## Serialization / Deserialization Vectors

Target: `SetBytes`, `FromCompressed`, `Decode`, `Unmarshal`,
`from_bytes`, `deserialize` and similar functions.

### Point Encoding Vectors (Elliptic Curves)

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| Valid compressed point | Baseline correctness | valid |
| Valid uncompressed point | Baseline for uncompressed path | valid |
| Identity / point at infinity | Special case handling | valid or invalid (spec-dependent) |
| Wrong length (truncated) | Length validation | invalid |
| Wrong length (extra bytes) | Length validation | invalid |
| All-zero bytes | Zero-check handling | invalid |
| Field element >= modulus | Field validation | invalid |
| Point not on curve | Curve check | invalid |
| Point on curve but wrong subgroup | Subgroup check | invalid |
| Flipped compression flag bit | Flag parsing | invalid |
| Flipped sign bit | Sign selection | invalid or different point |
| Maximum valid field element | Boundary condition | valid |
| Modulus - 1 as field element | Boundary condition | valid |
| Mixed compressed/uncompressed flags | Flag consistency | invalid |

### Roundtrip Assertions

For every valid deserialization vector, add a roundtrip check:
`serialize(deserialize(bytes)) == bytes`. This catches field
arithmetic corruption (carry propagation, modular reduction,
square root, negation bugs) that produces a valid-looking but
incorrect point — the wrong y-coordinate changes the sort bit
in the re-compressed encoding.

This technique killed 15 previously-missed `Fp` mutations in
the BLS12-381 campaign without requiring knowledge of the
internal field representation.

### Single-Fault Negative Vectors

Each negative vector should isolate ONE validation check by
having exactly one defect. For flag parsing mutations:

| Defect | Construction | Validates |
|--------|-------------|-----------|
| Compression flag cleared | `bytes[0] &= 0x7f` on valid point | Flag bit 7 check |
| Infinity flag set | `bytes[0] \|= 0x40` on non-identity | Flag bit 6 check |
| Sort flag on identity | `bytes = [0xe0, 0, ...]` | Identity + flag consistency |
| Compression cleared on identity | `bytes = [0x40, 0, ...]` | Identity encoding check |
| Both infinity + sort | `bytes[0] \|= 0x60` on valid point | Multi-flag validation |
| Wrong length | 192 bytes with compression flag | Length vs flag consistency |

Keep the underlying field element valid so the ONLY reason for
rejection is the flag. This is what kills `&` → `|` mutations
in `from_compressed_unchecked`.

### Scalar Encoding Vectors

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| Zero scalar | Zero handling | valid (context-dependent) |
| One scalar | Identity element | valid |
| Group order - 1 | Maximum valid | valid |
| Group order | Reduction check | invalid or reduced to zero |
| Group order + 1 | Overflow handling | invalid or reduced to one |
| All-ones bytes | Large value handling | invalid (usually > order) |
| Non-canonical encoding | Reduction behavior | depends on spec |

---

## Signature Scheme Vectors

Target: `Verify`, `Sign`, `verify`, `core_verify` and similar.

### Single Signature Vectors

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| Valid signature on empty message | Empty input handling | valid |
| Valid signature on single byte | Minimal input | valid |
| Valid signature on large message | No length limits | valid |
| Wrong message (1 bit flip) | Verification correctness | invalid |
| Wrong public key | Key binding | invalid |
| Truncated signature | Length check | invalid |
| Signature with extra bytes | Strict parsing | invalid |
| Identity point as signature | Identity rejection | invalid |
| Identity point as public key | Identity rejection | invalid |
| Negated signature | Sign check | invalid |
| Signature from wrong scheme/DST | Cross-scheme isolation | invalid |
| All-zero signature bytes | Degenerate input | invalid |
| Signature with field overflow | Field validation | invalid |

### Multi-Signature / Aggregate Vectors

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| 1 signer, valid | Minimal aggregate | valid |
| N signers, all valid | Standard case | valid |
| N signers, one wrong message | Detects per-message binding | invalid |
| Mismatched pubkey/message count | Input validation | invalid |
| Empty signer list | Empty input handling | invalid |
| Duplicate messages (rogue key attack) | See spec requirements | invalid |
| Identity key in aggregate | Identity rejection | invalid |
| Identity signature in aggregate | Identity rejection | invalid |

---

## Hash-to-Curve Vectors

Target: `HashToG1`, `HashToG2`, `hash_to_curve`, `encode_to_curve`.

### Known Answer Tests (KATs)

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| Empty message | Empty input handling | known point |
| Single byte 0x00 | Minimal non-empty | known point |
| ASCII string "abc" | Standard test | known point |
| Long message (128+ bytes) | No length restrictions | known point |
| Very long message (256+ bytes) | Large input handling | known point |
| RFC test vectors | Spec compliance | known point |

Hash-to-curve vectors must use a specific DST (domain separation
tag) and the expected output must be computed by a reference
implementation.

---

## Pairing-Based Cryptography Vectors

Target: `PairingCheck`, `MillerLoop`, `FinalExponentiation`,
`multi_miller_loop`, `pairing`.

### Pairing Check Vectors

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| e(P, Q) == e(P, Q) | Reflexivity | pass |
| e(aP, Q) == e(P, aQ) | Bilinearity | pass |
| e(P, O) == 1 | Identity handling (O = point at infinity) | pass |
| e(O, Q) == 1 | Identity handling | pass |
| e(P, Q) with P not in G1 | Subgroup check | fail or undefined |
| e(P, Q) with Q not in G2 | Subgroup check | fail or undefined |
| Multi-pairing with n=1 | Minimal multi-pairing | matches single pairing |
| Multi-pairing with n=0 | Empty input | implementation-defined |

---

## Key Encapsulation Vectors (KEM)

Target: `Encapsulate`, `Decapsulate`, `encaps`, `decaps`.

| Vector Type | Purpose | Expected Result |
|-------------|---------|-----------------|
| Valid encaps/decaps roundtrip | Correctness | shared secrets match |
| Modified ciphertext (1 bit flip) | Ciphertext integrity | decaps fails or different secret |
| Wrong secret key | Key binding | decaps fails or different secret |
| Truncated ciphertext | Length validation | error |
| All-zero ciphertext | Degenerate input | error |
| Known-answer test (deterministic encaps) | Spec compliance | known ciphertext + secret |

---

## Mapping Escaped Mutants to Vector Patterns

When escape analysis (Phase 4) identifies survived mutants, use
this mapping to select appropriate vector patterns:

| Mutant Location | Mutant Type | Vector Pattern |
|-----------------|-------------|----------------|
| Length check (`len != N`) | CONDITIONALS_BOUNDARY | Truncated / extended inputs |
| Field validation (`>= modulus`) | CONDITIONALS_NEGATION | Field overflow values |
| Subgroup check | CONDITIONALS_NEGATION | Wrong-subgroup points |
| Identity check (`IsInfinity`) | CONDITIONALS_NEGATION | Identity point inputs |
| Sign bit handling | ARITHMETIC_BASE | Negated / flipped-sign inputs |
| Error return path | CONDITIONALS_NEGATION | Input triggering that error |
| Serialization flag parsing | ARITHMETIC_BASE | All flag combinations |
| Loop bound (`i < n`) | INCREMENT_DECREMENT | Boundary-length inputs |
| Arithmetic operation | INVERT_NEGATIVES | KATs verifying exact output |

### Example: Mapping gnark-crypto BLS12-381 Escapes

```
marshal.go:117-352 (streaming encoder, NOT COVERED)
→ Not reachable via SetBytes/Bytes API
→ Need vectors exercising io.Writer-based Encode/Decode
→ Pattern: Serialization vectors via streaming API

pairing.go:352-394 (Miller loop internals, NOT COVERED)
→ Reachable via PairingCheck but specific arithmetic lines
  don't have distinguishing inputs
→ Pattern: Pairing bilinearity KATs with edge-case points

g1.go:184, g2.go:191 (endomorphism, NOT COVERED)
→ Only used in multi-scalar multiplication optimization
→ Pattern: Large-scalar multiplication with known answers
```