# Result: item `bootstrap` (batch e01-foundation)

Credit: Taylor (gtmcknight), solved-policy research, github.com/gtmcknight/amm-sim @ 4812a6382311624e1506aca131ca35c378f930d9 (research/solved). The prebuilt `amm_sim_rs` wheel, its `.so` hash, `harness.py` and the no-Rust setup idea are his release `sim-6b6921f8`.

## Outcome

`setup_fast.sh` works on Linux x86_64 in both modes, cold and cached, online and offline. Every download is pinned by sha256 and size. The test suite ran 25 tests: 24 passed, 1 skipped (real macOS execution, which needs a Mac). **macOS arm64 was not executed**: its four files were downloaded, hash-verified and inspected only.

## Files changed (all inside the allowed paths; nothing committed or staged)

| Path | What |
|---|---|
| `setup_fast.sh` | the one-command installer |
| `bootstrap/manifest.tsv` | 20 pinned downloads: set, kind, sha256, bytes, filename, url |
| `bootstrap/pins.sh` | versions, engine commit and tree, `.so` sha256, smoke seed |
| `bootstrap/verify_env.py` | post-install check: real imports, versions, numba JIT, engine `.so` hash, solc, harness location |
| `bootstrap/smoke_replica.py` | bounded seeded numba workload (synthetic, not replica2) |
| `bootstrap/smoke_engine.py` | one engine run, seed 9700000 only; any other seed refused |
| `tests/test_setup_fast.py` | 25 tests, standard library only |
| `docs/setup.md` | commands, flags, exit codes, interpreter and engine locations, pin table, derivation |
| `.gitignore` | `scratch/`, `__pycache__/`, `*.py[cod]`, `.pytest_cache/` |

Every file carries the credit in its header (the tests check this).

## Exact commands

```sh
bash setup_fast.sh --platform linux-x86_64 --cache scratch/cache                 # replica + engine
bash setup_fast.sh --platform linux-x86_64 --replica-only --cache scratch/cache  # replica only
bash setup_fast.sh --platform macos-arm64 --replica-only --cache scratch/cache   # macOS 12+, replica only
. scratch/env.sh && python -I your_script.py
python3 tests/test_setup_fast.py -v
```

Other flags: `--offline`, `--scratch PATH`, `--fetch-only`, `--smoke`, `--force`, `--deadline SEC` (default 420, max 470). Default cache without `--cache` is `$HOME/.cache/imd-amm`; every run in this item passed `--cache scratch/cache` or a subdirectory of it.

**Resume command:** rerun the same command. Verified files stay cached, a finished install is skipped, and exit 75 means the deadline was reached.

## Next-wave usage

- Interpreter: `scratch/venv/bin/python` (`$IMD_AMM_PYTHON`), CPython 3.12.16.
- Engine checkout: `scratch/engine/amm-challenge` (`$IMD_AMM_ENGINE`), benedictbrady/amm-challenge @ `6b6921f8d463314aa7c96234e1be25a25245f704`; `amm_competition` and `amm_sim_rs` import from any directory. Taylor's harness is `scratch/engine/harness.py` (`$IMD_AMM_HARNESS`).
- `env.sh` also sets `SOLCX_BINARY_PATH`, `NUMBA_CACHE_DIR`, `TMPDIR` and `XDG_CACHE_HOME`, all under `scratch/`.
- The venv has no pip. A new package means a new pinned row in `bootstrap/manifest.tsv`.
- Per-seed engine configs: use the transcription in `bootstrap/smoke_engine.py::config_for`. `harness.py`'s `build_configs` builds every config from 0 to the last seed, which is 9.7 million objects for the 9700000 range.
- Setup runs no simulation. Only `--smoke` or `smoke_engine.py` touches the engine, and only seed 9700000.

## Versions

CPython 3.12.16 (python-build-standalone 20261026, `install_only_stripped`), numpy 2.5.4, numba 0.68.1, llvmlite 0.50.0 (the versions item numba-rng used), amm_sim_rs 0.1.0.post1 (cp310-abi3), pyrevm 0.3.7, py-solc-x 2.1.0, solc 0.8.24+commit.e11b9ed9, requests 2.34.2, urllib3 2.8.0, idna 3.20, certifi 2026.10.23, charset-normalizer 3.5.2, packaging 26.3. Installed by the pip 26.2.2 bundled in the CPython archive with `--no-index --no-deps --require-hashes`. No Rust, maturin, uv, source build or `latest` URL.

## Downloads: sha256, bytes, URL

**linux-x86_64:replica**

- `ce4f6d0a6cfdb3bed6e44c2f9affd85943c76a42e25ad3a259002f31d6fb8a20` 34505639 B https://github.com/astral-sh/python-build-standalone/releases/download/20261026/cpython-3.12.16+20261026-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
- `fbde6962867ee75b48b0ee29b2b9372ec5d617799dbaf38e82dc0596f2f7738a` 16727283 B https://files.pythonhosted.org/packages/43/a3/c799c62e19c337e6d3770b08e475887fb30ce8477d3c09efca6b2f0228a6/numpy-2.5.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- `8b33fee239194b9b6cb9b176f3c2563b94e5882fd846748ad0cf960daeee5406` 3890001 B https://files.pythonhosted.org/packages/43/23/0813ab091f60403c33cb741392ae77db13324587748df6f52167bf3a2404/numba-0.68.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
- `d501e5103076b9a14be885d2574dc2f6793171aa54a853d1244e011d476f1399` 59696588 B https://files.pythonhosted.org/packages/4c/72/22b6449e15bec4cc86c62b659e6c625ab777d01e87aaec717ecef440f87a/llvmlite-0.50.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

**linux-x86_64:engine**

- `aedb68280aca34c110968f00148387c95885207913fb2cf19a1ab4c5cfd6887a` 727586 B https://github.com/gtmcknight/amm-sim/releases/download/sim-6b6921f8/amm_sim_rs-0.1.0.post1-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
- `d055860c3352d6bc180b80255d8563f0b3c0fe6ce62b5c2a52e1bc7ecc4fad4f` 4317826 B https://files.pythonhosted.org/packages/7c/6c/17f60815e678474fa8bb36363e4a9f336fa444abb983c2a1e4bb08f681ae/pyrevm-0.3.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- `4bf45aa96c29ed0a3654dcb6951f0f14c648d2be3f938260babbbd1ace6dde04` 18126 B https://files.pythonhosted.org/packages/8d/6d/3456e1c77b7efe9e277c5202bb8b879048117369f97c2b3dcefbc4c43071/py_solc_x-2.1.0-py3-none-any.whl
- `d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c` 129956 B https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl
- `2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0` 73075 B https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl
- `3d31298449090ab8d47b7b1b2a555ff73cac7ed438a08b7ac160980c7ebed649` 257601 B https://files.pythonhosted.org/packages/7f/c5/38806a25ab5e65fc178f39affeda20858efafede2fce1ffc2556cfc9fe73/charset_normalizer-3.5.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
- `ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c` 69583 B https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl
- `0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3` 135717 B https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl
- `e9b54de76e530bb6cf0ccd036787103acb58fd42ba930ea8bf948ddbaa2f61d1` 135082 B https://files.pythonhosted.org/packages/32/d1/a3652fe2c19134d0d15922177821d863cbd7e842d53a21bbe7e8e3a1b5ac/certifi-2026.10.23-py3-none-any.whl
- `fa91b175c4b0db13fa44657903f55f664c80fb34796172c94d57ebebba71ec9e` 58742 B https://codeload.github.com/benedictbrady/amm-challenge/tar.gz/6b6921f8d463314aa7c96234e1be25a25245f704
- `0fe3bcb3f836bf9bbd8f6b88b06c7cbd2971bfd5999c4b366aba25675f86c590` 5222 B https://github.com/gtmcknight/amm-sim/releases/download/sim-6b6921f8/harness.py
- `fb03a29a517452b9f12bcf459ef37d0a543765bb3bbc911e70a87d6a37c30d5f` 15020760 B https://binaries.soliditylang.org/linux-amd64/solc-linux-amd64-v0.8.24+commit.e11b9ed9

**macos-arm64:replica**

- `353d5f1b4fd2715e7053f12f068435d5bbad16b91e057006b5d01e0925709a7e` 25035343 B https://github.com/astral-sh/python-build-standalone/releases/download/20261026/cpython-3.12.16+20261026-aarch64-apple-darwin-install_only_stripped.tar.gz
- `b11e8fda06a7d69f15ebf542660b74466c2e51094800c1fb794f47ad4faeef17` 12015718 B https://files.pythonhosted.org/packages/ff/a9/bac826765e971d8e16e2064e9ac7525fd69b40ac17c905033a7f5442023f/numpy-2.5.4-cp312-cp312-macosx_11_0_arm64.whl
- `7de5e5d00e6c8967fc861be2a015eb8ad701ab3cf65d7f4a2c4d950990cf65d3` 2762483 B https://files.pythonhosted.org/packages/d4/a7/2e54558d08bb64c8718ad398314605b6c73d154a593cf2bbf1360047fa4e/numba-0.68.1-cp312-cp312-macosx_12_0_arm64.whl
- `55f50a6b7c0b8de88b05d6bc407d70a60486ce024013997dc97e202bd187c75b` 40534277 B https://files.pythonhosted.org/packages/d9/1f/2576416b3e9b73f77b8331b7f2e41ce5ae7bbff0489eb16d98099a71693c/llvmlite-0.50.0-cp312-cp312-macosx_12_0_arm64.whl

Totals: Linux replica 4 files, 114,819,511 B; Linux engine adds 12 files, 20,949,276 B; macOS replica 4 files, 80,347,821 B.

## How the pins were verified

- **Engine pin verified.** The GitHub API returns commit `6b6921f8d463314aa7c96234e1be25a25245f704` in benedictbrady/amm-challenge (2026-02-07, tree `87a2faad51fe2c2902bb28a67e7e49b257f09f2c`). The pinned tarball, extracted and passed through `git add -A && git write-tree`, gives that same tree hash.
- **Wheel.** The post1 wheel hashes to `aedb6828…887a`, equal to the release asset digest and Taylor's README. The `amm_sim_rs.abi3.so` inside hashes to `ff88b6353c2aad7342f0a26194f7347e78b9c3b38d683a7449006d423978cd14`, his published value; `verify_env.py` re-checks it on every setup.
- **Starting harness.** goal-3170 `tools/setup.sh` hashes to `2bac901b…a4b1`, equal to Taylor's release asset `setup-fast.sh`.
- **CPython archives** equal the digests GitHub publishes for the release assets. **solc** equals the sha256 in `binaries.soliditylang.org/linux-amd64/list.json`. **harness.py** equals its release asset digest.
- **PyPI wheels.** The Linux set is pip's own resolution of `numpy==2.5.4 numba==0.68.1 py-solc-x==2.1.0 pyrevm==0.3.7` with `--only-binary=:all:`, so transitive wheels are included; each file's sha256 and size equal PyPI's JSON API. The macOS hashes come from the same API and were confirmed by downloading.

## Measured timings (this machine: 8 cores, AMD EPYC, glibc 2.39)

| Run | Result |
|---|---|
| Cold engine setup with `--smoke` | 11.99 s: fetch 3.64, install 4.25, verify 1.88, smoke 2.20; 16 downloads, 135,768,787 B |
| Cold engine setup, fresh sub-cache | 9.66 s: fetch 3.53, install 4.36, verify 1.75 |
| Cold replica-only with `--smoke`, fresh sub-cache | 8.67 s: fetch 1.14, install 4.10, verify 1.51, smoke 1.90; 4 downloads |
| Cached rerun | 0.89 s: 16 cache hits re-hashed, install reused |
| Cached rerun with `--offline` | 0.93 s |
| `--offline --force` reinstall from cache | 4.52 s: install 2.50, verify 1.81 |
| macOS `--fetch-only`, fresh sub-cache | 1.03 s, 4 downloads |
| Test suite | 25 tests in 24.5 s |

Benchmark costs for capping later work:

- **Replica toolchain** (`smoke_replica.py`, synthetic 10,000-step loop, one core): numba compile 0.90 to 0.99 s; 646 to 687 runs/s/core over 256 runs in 0.38 s; seeded reruns identical. This is not replica2's rate; item (a) must measure its own.
- **Engine** (`smoke_engine.py`, VanillaStrategy vs VanillaStrategy, seed 9700000): solc compile 0.11 to 0.13 s; one 10,000-step simulation 0.19 s; 11,970 afterSwap calls, peak gas 22,592, zero OutOfGas or reverts; edge 346.0273756163182 (submission) and 346.0273756130103 (normalizer), identical in the three runs whose output was read. A real strategy costs more gas and time per run; the engine bank item must benchmark qt1 first.
- **Disk:** venv 270 MB, interpreter 113 MB, solc 15 MB, engine checkout 0.6 MB, Linux cache 136 MB.

## Checks

Passed:

- Hash mismatch: exit 4, nothing cached, no partial file left.
- Size bound, one byte over and one under: exit 4.
- Missing cache with `--offline`: exit 5, naming every file, sha256, URL and expected path.
- Cached offline rerun after the sources were deleted: `setup=cached downloads=0`.
- Corrupt cache entry: caught offline (exit 4), repaired online.
- Failed transfer: exit 6 after 3 attempts. Deadline: exit 75 with a resume hint. Non-https URL: exit 2.
- Refusals: no `--platform`, unknown platform, macOS without `--replica-only` (also with `--fetch-only`), installing a foreign platform (exit 3, no state created), unknown flag, `--deadline` over 470.
- Linux engine setup with real imports through `env.sh`; all paths under scratch; venv has no pip.
- Offline rerun: 16 hits, install reused. Offline forced reinstall with both smokes passing.
- `smoke_engine.py` refuses seeds 9700001, 0 and 9699999 before running anything.
- Replica-only: no engine variables, `import amm_sim_rs` fails, numba JIT works.
- macOS files: download, match pins; interpreter is 64-bit arm64 Mach-O; wheel tags are `macosx_11_0_arm64` (numpy) and `macosx_12_0_arm64` (numba, llvmlite).
- Manifest: 20 rows, https only, unique hashes, no `latest`, wheels only, no macOS engine set.
- Offline runs had a failing fake `curl` first on `PATH`; it was never called.

Failed: none. Skipped: `MacIntegration.test_replica_only_setup_and_numba`, which needs a Darwin arm64 host.

Engine seeds used: 9700000 only, VanillaStrategy vs VanillaStrategy, five runs in total (three setups with `--smoke`, two direct). No policy was run or tuned.

## Missing work and limits

- macOS arm64 execution is unproven. First step on a Mac: `python3 tests/test_setup_fast.py -v`. numba and llvmlite need macOS 12 or later.
- The engine source tarball is generated by GitHub on request. Its bytes match the commit tree today; if GitHub changes them, setup fails with exit 4 (cached copies keep working) and the row must be re-pinned.
- Linux needs glibc 2.28 or later for the `manylinux_2_28` wheels; only glibc 2.39 was tested.
- Not tested with a shared scratch directory used by two setups at once. Cache writes are atomic renames, so sharing a cache is safe.
- The deadline is checked between steps, not inside one; the whole install phase measured at most 4.4 s.
- No pytest is pinned; tests run with `unittest` and are pytest-compatible.
- The cold timings used fresh sub-caches under `scratch/cache/_bench/` so the main cache stayed warm.
- `README.md` with raw URLs belongs to another item; no final commit hash exists yet.
- Files are left uncommitted in the working tree.