# tools result

Implemented verified reference inputs and two runnable harnesses. Credit: Taylor (gtmcknight), original Gaussian filter, qm tables, replica, and setup. No baseline, setup, Foundry, dependency configuration, or other workers' source files were changed. Required output remains untracked.

## Changes

- Extracted R's Solidity fence verbatim to `reference/qtr2/Strategy.sol`: asserted 43,073 bytes and required SHA256. Extracted SP's Patch diff verbatim, applied it to a copy, and asserted the required patched Solidity SHA256.
- Extracted the Code Python fences verbatim to `reference/twocomp/twocomp.py`, `reference/mix/wavg_fees.py`, and `reference/mix/wavg_offsets.py`. Source links and extraction details are in `reference/CHECKS.md`.
- Adapted SP replay.py into `tools/check.py CONTRACT MODULE.CLASS START END OUTPUT`: fresh pyrevm deployment and policy per seed, initialization with actual replica configuration, first 2,000 own-pool callbacks, 245,000 gas per call, effective reference fees via replica2.clampf, tolerance 0.01 bps. Preserved source-style JSON rows, gas maps and raw output hashes, now with one candidate arm.
- Adapted SP engine.py into `tools/engine.py CANDIDATE BASELINE START END OUTPUT`: independent runs against Vanilla with eight workers, default MatchRunner configs, per-arm raw gas statistics and per-seed edges, paired n/mean_diff/se/worst5. Output reservation is exclusive before simulation; partial results persist after each arm. Ranges are half-open. Source-hash compilation caches and engine state stay under scratch/.
- Documented exact setup and CLI commands in `tools/README.md`; recorded replica values and smoke results in `reference/CHECKS.md`. Added Where things are and updated README seed ledger: 9800000..9801089 spent/reserved, next free 9801090.

## Commands and validation

All commands ran locally; long commands had `timeout 470` (under eight minutes). Disposable files, engine clone, caches and dependencies are only in test/scratch/. No engine seed beyond the assigned two was run.

1. Fetched the five named api.imdnotdead.fun artifacts using Python urllib into test/scratch/. Extracted their fenced blocks without edits; verified original and patched qtr2 hashes with hashlib/sha256sum. Applied `patch reference/qtr2/StrategySpans.sol reference/qtr2/spans.diff` to a copied Strategy.sol. Rechecked all five original fences byte-for-byte at the end.
2. `python3 -I test/scratch/replica_checks.py` using unchanged replica2.py and qt1/blob.bin. Driver inserts only the four bundled reference directories, instantiates each policy afresh per seed, and runs replica2.run. Equivalent self-contained command is delivered in CHECKS.md.
3. `git clone -q https://github.com/benedictbrady/amm-challenge test/scratch/amm-challenge`; `git -C test/scratch/amm-challenge checkout -q 6b6921f8d463314aa7c96234e1be25a25245f704`. Copied unchanged tools/setup.sh to that checkout's scratch/setup.sh, then from its root ran `timeout 470 sh scratch/setup.sh`. Successful: wheel module SHA256 ff88b6353c2aad7342f0a26194f7347e78b9c3b38d683a7449006d423978cd14; Solidity 0.8.24 installed; StarterStrategy compiled and validated.
4. From engine checkout: `. scratch/env.sh && timeout 470 python ../../../tools/check.py ../../../reference/qt1/Strategy.sol qmref.QMRef 70000 70001 scratch/F_qt1_70000_70001.json`. Passed, 2,000 callbacks, maximum 1.504892703507732e-6 bps error; peak 177,686 pyrevm afterSwap gas. qt1 compiled runtime 20,605 bytes.
5. From engine checkout: `. scratch/env.sh && timeout 470 python ../../../tools/engine.py ../../../reference/qt1/Strategy.sol ../../../reference/qt1/Strategy.sol 9801088 9801090 scratch/engine_qt1_qt1_9801088_9801090.json`. Passed; each arm independently versus Vanilla. Both arms edges: seed 9801088 = 573.595237186163, seed 9801089 = 591.10427219484. Paired mean/se exactly zero. Engine invocation time, both arms total: 10.853595495223999 seconds. Submission afterSwap max 200,361, 0 OutOfGas or any other error. The two arms reuse the assigned window only as required for paired comparison; no reruns.
6. Downloaded pinned Taylor qm_k1e-5.json into test/scratch/gates and asserted SHA256 5ff53e42ca87390e5f65d1caa3f7a480e67a8212fb0670274dfd562b05ba1afd. Copied unchanged Taylor scripts and pol_mid.json alongside it; `(cd test/scratch/gates && timeout 470 python3 -I gates.py)` reproduced all original values below. These immutable policy checks ran after source import, with no policy changes.
7. `python3 -m py_compile tools/check.py tools/engine.py`; from engine checkout `. scratch/env.sh && python -I ../harness_checks.py`: PASS. Checked all three Python input modules too, byte equality of five extracted fences, pinned span hash, config parity against MatchRunner._build_configs (5 seeds × 12 fields, config construction only), nonzero paired-statistic arithmetic, one-seed null SE, and smoke JSON invariants. No extra simulations.
8. Final path/status review and `git diff --check`; baseline and setup files unchanged.

## CHECKS values (six decimal places)

| Reference | 10000 | 10001 | 10002 |
| --- | ---: | ---: | ---: |
| qmref.QMRef | 443.101741 | 571.454483 | 525.908441 |
| twocomp.TwoComp | 443.690614 | 571.968071 | 526.124475 |
| wavg_fees.QMRef | 444.116689 | 571.977148 | 525.771328 |
| wavg_offsets.QMRef | 444.115542 | 571.986018 | 525.772792 |

Original Taylor gates:

```text
seed   perfect-info      gaussian+plain    gaussian+qm       lattice+qm
10000  448.261189  443.455598  443.522608  443.663520
10001  576.779199  571.463409  571.623551  571.977293
10002  531.886497  525.168028  525.865859  526.411631
```

## Smoke JSON evidence

Gate F:

```json
{
  "rows": [
    {
      "seed": 70000,
      "n": 2000,
      "max_error_bps": {
        "candidate": 1.504892703507732e-06
      },
      "peak": {
        "candidate": 177686
      },
      "sum_gas": {
        "candidate": 253658209
      },
      "sha256": {
        "candidate": "221472443e11ab733f0f2f33f8a59c135909b690af1b9ee93aad0af702e2a782"
      }
    }
  ],
  "seconds": 3.367746114730835
}
```

Engine paired:

```json
{
  "n": 2,
  "mean_diff": 0.0,
  "se": 0.0,
  "worst5": [
    {
      "seed": 9801088,
      "diff": 0.0
    },
    {
      "seed": 9801089,
      "diff": 0.0
    }
  ]
}
```

Raw engine gas_stats() below is identical for both arms, captured after separate resets:

```json
[
  {
    "role": "Baseline",
    "callback": "afterInitialize",
    "calls": 2,
    "ok": 2,
    "max_ok_gas": 21796,
    "sum_ok_gas": 43592,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  },
  {
    "role": "Baseline",
    "callback": "afterSwap",
    "calls": 22875,
    "ok": 22875,
    "max_ok_gas": 22592,
    "sum_ok_gas": 516125520,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  },
  {
    "role": "Baseline",
    "callback": "getName",
    "calls": 2,
    "ok": 2,
    "max_ok_gas": 21526,
    "sum_ok_gas": 43052,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  },
  {
    "role": "Submission",
    "callback": "afterInitialize",
    "calls": 2,
    "ok": 2,
    "max_ok_gas": 90858,
    "sum_ok_gas": 181716,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  },
  {
    "role": "Submission",
    "callback": "afterSwap",
    "calls": 23027,
    "ok": 23027,
    "max_ok_gas": 200361,
    "sum_ok_gas": 3161171583,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  },
  {
    "role": "Submission",
    "callback": "getName",
    "calls": 2,
    "ok": 2,
    "max_ok_gas": 21579,
    "sum_ok_gas": 43158,
    "oog": 0,
    "revert": 0,
    "other_halt": 0,
    "tx_error": 0,
    "bad_return": 0
  }
]
```

## Scope and failures

All requested Linux setup and smoke runs executed. No failure, timeout, OOM, blocked step, hash mismatch, fee mismatch, OutOfGas or reverted callback occurred. No external account or requester input was needed.

Not executed: full 50 × 2,000 Gate F, full 1,024/2,048-seed Gate Q, candidate engine comparisons, candidate Solidity compilation or new performance optimization. These are outside this input-and-harness item's smoke scope. No claim of beating qt1 is made. Engine output reservation prevents overwriting its chosen filename, not global seed reuse under another filename; the documented ledger governs global seed allocation. Successful samples do not certify general behavior.

## Delivered source inventory

All delivered source/document changes are listed below, using final on-disk bytes. This report is separately delivered at artifacts/goal/batches/e3-trunk-tools/items/tools/result.md; its own hash is reported in the final response to avoid a self-referential digest. Scratch inputs, drivers, logs, dependencies and caches are temporary and are not submitted.

| File | Bytes | SHA256 |
| --- | ---: | --- |
| `README.md` | 3907 | `33b9d82d6b53308a8c6b3cc94c975516befd0eff98c3c99fcda6544d5b9e4613` |
| `reference/CHECKS.md` | 5147 | `47124e3ff2ac6019ba5c57ec16323b8af03ed857b2e3edd1a3846f8364296795` |
| `reference/qtr2/Strategy.sol` | 43073 | `7b99afae570ef1627b0163fb21411f14c496b005a07c3966cc7323906dee664f` |
| `reference/qtr2/spans.diff` | 1733 | `35ec1bab15959eebeac3ea9bf46e70d723b7acfe1f3f82881d10bd1a8bb81623` |
| `reference/qtr2/StrategySpans.sol` | 43289 | `bbf63364ed407fc3a94ec3b4cc02223b6855b1b9c083e6e7a7566a2ba70e24b5` |
| `reference/twocomp/twocomp.py` | 11202 | `9d3c1833321493fb51bbde4e1b4dabc2f8978bd6d774ee2af8dc8aed13f0f0af` |
| `reference/mix/wavg_fees.py` | 8934 | `668a287ae4c7a1a311d7a8de94269c068bc543b9fb1661040a796c45e6a3da60` |
| `reference/mix/wavg_offsets.py` | 9068 | `591768f2c61efc4972084c6f172acf9ee887577672eb493af15d28c7f941f116` |
| `tools/check.py` | 4755 | `cbcfea4c793ac7b78e0ee27dd723c9e6af4d9d704a70a8038c985acffffcfed1` |
| `tools/engine.py` | 4430 | `306c529d0c84c88610c1e8a9a6aa34634534b73ab83312e9155ef14476e46300` |
| `tools/README.md` | 4474 | `4e75965d6ec00e9e9e3887b83688bb3f9ea8fc438f4d3336ef104bae8a234c6f` |