apophis-fastify/docs/performance.md

# Performance and Profiling

APOPHIS ships repeatable benchmark scripts for CLI startup and core hot paths.

## Run Benchmarks

```bash
# Run everything
npm run benchmark

# CLI command startup/runtime
npm run benchmark:cli

# Formula, matcher, schema, and in-process qualify path
npm run benchmark:hot
```

Tune sample counts with environment variables:

```bash
BENCH_RUNS=12 BENCH_WARMUP=3 npm run benchmark:cli

# Increase inner-loop work for micro-benchmarks
BENCH_INNER_ITERS=5000 npm run benchmark:hot

# Benchmark with varying test counts
BENCH_RUNS=10,50,200 npm run benchmark:all
```

## Capture CPU Profile for Qualify

```bash
npm run profile:qualify
npm run profile:qualify:quick
```

This writes Chrome-compatible CPU profiles to `.profiles/qualify.cpuprofile` and `.profiles/qualify-quick.cpuprofile`.

## Notes

- CLI benchmark uses spawned `node dist/cli/index.js` commands so startup costs are included.
- Hot path benchmark runs in-process for lower-noise function-level comparisons.
- Use fixed `--seed` for qualify benchmarks to keep runs deterministic.
- Schema generation uses fixed defaults (string≤128, array≤10) regardless of run count.

You can override runs per preset:

```bash
apophis qualify --profile oauth-nightly --seed 42
```