interface:
  display_name: "Vector Forge"
  short_description: "Generate cryptographic test vectors from surviving mutants"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

# 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.

# 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.**

# 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.

# 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]
```

# 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
```