eggsact 1.2.2

Deterministic MCP and in-process utility tools for coding agents
Documentation
# Fuzzing and Property Testing

Release 5 adds persistent fuzz corpora, targeted property tests, and reproducible triage workflows.

## Prerequisites

Install cargo-fuzz and the nightly toolchain:

```bash
rustup toolchain install nightly
cargo install cargo-fuzz --locked
```

Fuzz targets require the nightly toolchain because libFuzzer uses unstable Rust features.

## Fuzz Targets

| Target | Module | What it fuzzes |
|--------|--------|----------------|
| `calculator_expression` | `src/calc/` | Expression parser/evaluator |
| `calculator_normalization` | `src/calc/` | Normalization/tokenization |
| `unified_diff` | `src/text/patch.rs` | Unified diff parser |
| `shell_tokenization` | `src/text/shell.rs` | Shell command splitting |
| `shell_quoting` | `src/text/shell.rs` | Quote/parse round-trips |
| `regex_classification` | `src/text/regex_engine.rs` | Regex feature classifier |
| `regex_execution` | `src/text/validate.rs` | Regex compile and match |
| `json_pointer` | `src/text/validate.rs` | JSON parse/extract/canonicalize |
| `toml_config` | `src/text/toml.rs`, `config.rs` | TOML/dotenv/INI validation |
| `unicode_inspection` | `src/text/unicode_*.rs` | Unicode normalization/inspection |
| `markdown_fences` | `src/text/markdown.rs` | Markdown structure extraction |
| `glob_matching` | `src/text/glob.rs`, `path.rs` | Glob and path operations |

## Running Fuzz Targets

### Build all targets

```bash
cargo fuzz build
```

### Run a specific target

```bash
cargo fuzz run calculator_expression -- -max_total_time=60 -timeout=5
```

### Run with specific corpus

```bash
cargo fuzz run calculator_expression fuzz/corpus/calculator_expression/
```

### Run with limited iterations

```bash
cargo fuzz run unified_diff -- -max_total_time=30 -runs=10000
```

## Corpus Policy

### What to commit

- Seed corpus files in `fuzz/corpus/<target>/` (small, representative inputs)
- Minimized regression fixtures from fixed bugs
- Historical test cases and edge cases

### What NOT to commit

- Raw crash artifacts (large or unreviewed)
- Generated corpora from long fuzz campaigns
- Multi-megabyte files without justification

### Seed sources

- Existing unit/integration test fixtures
- Historical bug reproductions
- Python parity edge cases
- Machine-code error cases
- Boundary inputs (min/max lengths, empty, etc.)

## Crash Workflow

For every crash, timeout, OOM, or invariant failure:

1. **Preserve** the raw artifact locally
2. **Reproduce** with the exact target
3. **Minimize** using `cargo fuzz tmin`:
   ```bash
   cargo fuzz tmin calculator_expression <crash-file>
   ```
4. **Classify** the finding:
   - Production bug (fix in src/)
   - Harness bug (fix in fuzz_targets/)
   - Expected resource rejection (document and filter)
   - Duplicate of known issue
5. **Fix** the production or harness bug
6. **Add regression test** in `tests/`
7. **Add minimized input** to persistent corpus
8. **Re-run** target and full test gate

## Property Tests

Property tests run in ordinary CI via `cargo test`. They verify algebraic properties:

- **Calculator**: determinism, context isolation, normalization idempotence
- **Diff**: Levenshtein symmetry, triangle inequality, span bounds
- **Shell**: round-trip `parse(quote(argv)) == argv`, determinism
- **Regex**: classification determinism, span bounds, max_matches
- **JSON**: canonicalization idempotence, compare symmetry, extract bounds
- **Config**: validation determinism
- **Unicode**: NFC idempotence, grapheme bounds, casefold validity
- **Markdown**: fence span ordering, extraction determinism
- **Path/Glob**: normalization idempotence, matching determinism

Run property tests:
```bash
cargo test --locked --all-features property
```

## CI Integration

Fuzz and sanitizer workflows are manual-only (`workflow_dispatch`). They do not run on every pull request or push to `main`.

### Extended Fuzzing

The `fuzz-scheduled.yml` workflow runs all 12 targets in a matrix with per-target timeouts. It also runs a 7-target AddressSanitizer matrix. Dispatch manually before material releases or after changes to parser, regex, normalization, or concurrency surfaces.

### Passing runs produce no provenance artifacts. Failed runs preserve crash reproducers.

## Sanitizers

AddressSanitizer and LeakSanitizer are available via cargo-fuzz:

```bash
cargo fuzz run calculator_expression --sanitizer=address
cargo fuzz run calculator_expression --sanitizer=leak
```

## Security Handling

If a fuzz finding has plausible security impact:

1. Do not publish exploit details before assessment
2. Use the repository's security reporting process
3. Minimize and fix privately if required
4. Add a public regression test only after disclosure policy permits