docs: state the trust base accurately and bring spec, soundness and build docs up to v0.21

[defenwycke]

PR "B" of the four-PR docs cleanup that follows the factual audit. Every audit finding below was checked against code, git history, GitHub or the evidence files before it was applied; the ones that did not hold up as stated are under Rejected audit findings. No file is moved or renamed (PR C does that). No code changes except scripts/check-spec.sh, and nothing under prover/methods/ is touched, so METHOD_ID does not move.

Per file

docs/SPEC.md + scripts/check-spec.sh

• §9 now pins in_smt_root to the empty coinbase-SMT root, with the value as the code defines it (e[256], e[0] = 32 zero bytes, e[d] = SHA256(0x11 || e[d-1] || e[d-1]) — coinbase-smt/src/roots.rs), and says "All seven". Evidence: RangeState::is_genesis_anchored (rangestate/src/lib.rs), the host's assert_genesis_in_boundary (prover/host/src/main.rs, the audit fetch_block.py: coin_mtp uses header nTime instead of MTP(coin_height-1) → check-full/prove-full false-reject BIP68 time-locks (standalone path only) #3 F-3 block) and the verifier's shared-predicate call (verifier/src/lib.rs, F-2).
• check-spec.sh checks §9 mechanically: the field list comes from is_genesis_anchored itself (self.* references), every one must appear in §9's condition list, and "All N MUST be checked" must count that list. It also guards against a regex that parses nothing. Negative controls run on a scratch copy: deleting the in_smt_root bullet fails (missing: ['in_smt_root']), and a wrong count word fails. The first version searched all of §9 and passed with the bullet deleted, because the prose below the list names in_smt_root; scoping to the list fixed it.
• §10 seam list adds time and the coinbase-SMT root (guest fold_range asserts both).
• §1 claim drops "unmodified" and says maximal-Core; §12 trust base lists all non-Core code: accumulator, coinbase SMT (coinbase-smt/src/{roots,bip30}.rs, #[path] in the guest), 0012 (field_bigint2.h, field_bigint2_impl.h, src/field_bigint2.rs), 0013 (src/liftx_hint.rs), 0001/0002, coreshim (provision-vps.sh phase 5).
• §14: nine self-audit rounds plus rounds 10–11 (AI-assisted external reviews, SECURITY.md), still no commissioned audit. Wrapped proof "2,033 bytes" was block 170 only; the [1..1000] fold wraps to 3,441 B (prover/evidence/fold_and_snark_wrap_1_1000.txt).

docs/SOUNDNESS.md

• §2 trust base: new item for 0012/0013 as consensus-relevant non-Core code, described from the patches, docs/FIELD_BIGINT2_BACKEND.md §5b and docs/LIFTX_HINT.md §3, with the missing gate 4 flagged. The accumulator is no longer "the one non-Core component" — the coinbase SMT and the field backend are named too.
• H6 adds in_smt_root (audit fetch_block.py: coin_mtp uses header nTime instead of MTP(coin_height-1) → check-full/prove-full false-reject BIP68 time-locks (standalone path only) #3 F-2/F-3). H7 now describes what _frontier_chain actually does (coordinator/server.py): full boundary digest, H9 height contiguity, most-work selection.
• §6 item 2 no longer says BIP68-time "completes with the bridge" (§5 records it fixed without one); 6(a) succinct chunk receipts marked done 2026-07-15 (docs/HAZYNC_ARCHITECTURE.md, FIX A).
• §7 rewritten: negative regression tests and BIP68-time are done (SECURITY.md open items 1–2); rounds 10–11 described; open items are an independent audit, gate 4, and the standalone build_full anchor.

docs/EXPLAINER.md

• "Unchanged/unmodified" crypto → plain-English maximal-Core wording, in three places.
• The outside-review line now says two AI-assisted outside reviews found no flaw and that no professional audit has happened (SECURITY.md rounds 10–11).
• Adds the live board and CONTRIBUTING.md; the closing pointer to HAZYNC_ARCHITECTURE.md (historical notes) now goes to CONTRIBUTING.md and docs/GOALS.md.

docs/EXTERNAL_REVIEW.md

• epoch_start_time expectation corrected. The verifier reports rs.out_epoch_start (verifier/src/lib.rs), which is the timestamp of block ⌊height/2016⌋×2016; it equals 1231006505 only below 2016. A reviewer following the old line would have chased a non-bug.
• New review item 3: the 0012 field backend and 0013 hint, with exact paths; rounds 10–11 predate them. Items 3–5 renumbered 4–6.
• Coordinator item: Let anyone run their own coordinator (archive node + bridge + board) without duplicating proving work #69 closed 2026-08-24 (docs/RUN_YOUR_OWN_COORDINATOR.md, PEER_COORDINATORS), "do not commission until Let anyone run their own coordinator (archive node + bridge + board) without duplicating proving work #69 has a design" removed, the unbounded .read() in get() (coordinator/hazync) kept.
• "Five internal audits are in docs/AUDIT_*.md": only docs/AUDIT_2026-07.md (round 8) exists; the text now says so.

docs/FUZZING.md, audit-fuzz/FINDINGS.md, audit-fuzz/seeds/README.md

• Passes table adds forest_cache_equivalence (192k runs), fuzz-native/differential.cpp (27 checks), memsafety.cpp (661 cases, 0 sanitizer findings), realvector.cpp (Native differential + memory-safety harness: run the guest's Core code without a zkVM #222, be9761b), the in-zkVM negative corpus 7/7 (Negative corpus: every consensus rule violated alone must be refused — 7/7 #223, 8779122), and leaf-differential (in CI). Notes that CI runs seam_fuzz.py 20000 / parse_fuzz.py 30000 against the manual 200k/300k, and that the libFuzzer campaigns and fuzz-native/ do not run in CI.
• "Native C++ differential — the highest-value next step … a prerequisite the repo doesn't ship" replaced by what landed and what is still uncovered: the native harnesses build stock libsecp, not 0012/0013, and the negative corpus has no bad-signature, locktime or BIP30 case.
• guest-pure-fuzz comment: build.rs searches main.rs and script_flags.rs.
• Accumulator positive control marked UNVERIFIED. The recorded crash in tree_of predates 8e789a9 (accumulator: refuse adversarial proof input instead of panicking (L-2) #63, L-2), which made tree_of return Option and delete return false for i >= num_leaves, so the committed seed should no longer crash the reference. The reference still lacks the guest's height and position pins, so run_reference's REFERENCE SOUNDNESS assertion may still fire on another input. That is plausible, not measured; no campaign was run here. The exact rerun command is given. The seeds README no longer says a non-crashing control means the harness broke, and notes that check-test-surfaces.sh only checks the seed exists.

docs/FIELD_BIGINT2_BACKEND.md

• Up front: shipped in the canonical CORE guest since v0.21.0 (c12ad67, provision-vps.sh phase 5a). Gate 4 (corrupt-signature negative control) is recorded as an open soundness item for shipped code. No run was found: the Negative corpus: every consensus rule violated alone must be refused — 7/7 #223 corpus has no signature case, realvector.cpp's byte-flip builds stock libsecp natively, and no case in host adversarial / ci_negative_tests.sh corrupts a signature.
• Goal "~24 → ~9" now sits beside the measured 10 cards and 1.295 straggler (docs/BUILDS.md §1). "Gates 0–2 pass" → 0–3. The unmeasured-straggler and "~9 holds only if C2 reproduces the digest" paragraphs are resolved. The normalize "no-op" row is reconciled with §3b's 21 instructions. The private-memory reference is removed.

docs/LIFTX_HINT.md

• "COMPLETE BUT NEVER COMPILED, AND NOT MEASURED" → shipped (42417d2, canonical since c12ad67), measured +6.31% with 98.1% hits (docs/RELEASE_NOTES_v0.20.0.md), and liftx: hits=430 in 9d860d7. The "remaining host work" is done (b0c19dc). §3 soundness kept.
• New §6, the run-time requirement. HAZYNC_LIFTX_HINT is read by prover/methods/build.rs (read only) and at run time by the host's write_chunk_inputs; the guest reads the hint block in chunk_prove. A chunked command run without the variable dies with DeserializeUnexpectedEnd (docs/history/BENCH_8xL40S_2026-09-08.md). It applies to every caller of write_chunk_inputs (prove-seg, prove-chunk, seg-serve, the chunk-profile and seg-* measurement commands). The worker CLI uses prove-range-bridge/fold-range, so board contributors are unaffected. The §5 A/B command now sets it.
• Private-memory references removed.

docs/BUILDS.md (and docs/GHOST_NEXT_BUILD.md deleted)

• Ghost recipe: "packing constants -- DEFAULTS. Do NOT apply Core's refit" was wrong since c12ad67, where the built-in consts became Core's refit (417,798 / 462,435 / 41,387 / 2, prover/host/src/main.rs). Ghost now gets its own Ghost calibration MEASURED on hardware: straggler 1.462x → 1.189x #227 constants explicitly (85636 / 168542 / 2 / 53162, af0534c). Measured: straggler 1.462 → 1.189 on the Ghost calibration MEASURED on hardware: straggler 1.462x → 1.189x #227 A/B, and §1's separate run measured 1.438 at those defaults.
• The contradiction between "card counts are DERIVED" and "every card count is measured" is resolved: chunks were proved serially on one card (scripts/gpu-benchmark.sh) and turned into card counts by formula. The fleet check is 8 × L40S at 15m13s measured vs 15.2 min projected, putting sub-10-minute CORE blocks at ~13 L40S.
• §4 "What is NOT measured": items 0–3 are done or superseded; replaced with what is genuinely still unmeasured.
• provision-vps.sh quote corrected (see Rejected).
• Merged GHOST_NEXT_BUILD.md as §3.1, fixing it on the way: the byte term is 2, not 6; the constants are global consts plus env overrides, not per-build-mode; 11.467x is an execute-mode cycle ratio; steps 1–3 are done. The remaining levers follow Ghost's next build: the four levers reopened by "fastest wins" #209 as it stands (MSM, wholesale bigint2 re-measure, G3 and scalar-inverse re-measure, the aggregate).

docs/TOPOLOGY_AND_SETTINGS.md — rewritten for v0.21.x CORE (531 → ~215 lines)

• Stock-guest pricing replaced by CORE measurements, each labelled. Latency: the BENCH_8xL40S curve, ~13 L40S sub-10-min (INFERRED from N=8). 4090s: MILESTONE runs 1 and 4. Throughput: ~11 L40S (INFERRED, arithmetic shown).
• Removed: 9.10x wholesale (never produced by a run, 9b767b5/c7feb62). "Scaling past 2 cards UNMEASURED" is replaced by 2.78x on 3 workers (2facde4, stock), 203.8 s on 8 workers and the Aggregate: measure the N-curve past 2, and remove the ~20s non-scaling execute #235 sweep. "Chain fold cost never measured" is replaced by 3.76 s/fold and 2.0–3.0 s/fold. "4090 must drop to po2 20" is replaced by po2 21 at a 22,478 MiB peak.
• §4: -O3, fat LTO, codegen-units=1 and window 21 all shipped in v0.20.0 (42417d2 is the first tagged commit carrying each); ECMULT_GEN_KB is still 22. The old §7 "not settled" items 1–3 are answered, and "stock images ship CUDA 13.2" is dropped as unverified.
• Kept: seg_po2 21/20, CUDA 12.8, the hazync GPU lock, chunk count free (+0.2%). Added: HAZYNC_LIFTX_HINT=1 at run time and HAZYNC_CHUNKS = card count. The §1 and §4.1 anchors are kept because other docs link to them. History links point under docs/history/ only for files already there.
• The pre-rewrite body is f24c43b:docs/TOPOLOGY_AND_SETTINGS.md (last changed in 65c386e), for PR C to archive.

docs/GOALS.md

• G1 transcript removed. It claimed "released v0.16.0 binaries" but printed 37987b85, because the id line was rewritten at re-baselines (067062e says so). It is replaced by a pointer to the CI assertion (hazync-verify exits exactly 2 on prover/testdata/snark/neg500.snark, regenerated under the current guest). The G4 ghostd transcript had the same defect — it was recorded under 4722cec8 (aedce8b) — and was turned into prose.
• The hand-kept guest-id chain (wrong on b62d2a60: that is 067062e, 2026-08-21, first in v0.19.0; audit fetch_block.py: coin_mtp = MTP(coin_height-1), not header nTime (fixes #3) #5 is 4722cec8, 61a6f9f, v0.17.0) is replaced by a reproduce/LINEAGE.tsv pointer.
• G2 and G6 and the modes table are restated for CORE, with stock figures labelled as such. Per input: ~0.77 card-s (INFERRED, 966,108). That gives ~44–73 L40S card-years (INFERRED; money not re-derived), ~11 L40S throughput and ~13 latency, plus the measured 4090 runs. The 24 GB po2 claim is corrected, and the ACCELERATION.md refs point to docs/history/.
• G3: G3: verify the aarch64 verifier on real Pi-class hardware — the claim rests on qemu #41 closed 2026-08-01, superseded by WASM; "Done when" marked met, and a physical-device run noted as unrecorded. G4: stale "adoption itself still missing" paragraph deleted. bigint2 verifies ECDSA 13.78x faster than libsecp256k1 in-guest — decide what to do about it #139: closed 2026-08-23, and v0.21.0 ships CORE without it.

docs/PROVING.md

• CUDA 12.6 → 12.8 (provision-vps.sh). The cost-model formula is replaced by the real constants and HAZYNC_COST_* overrides. Added: the prover: a stuck block prove can hold a worker (and a claim) for 6 h -- there is no progress signal, and a timeout walks the OOM ladder #256 stall retry (once at the same size, no ladder) and the vendored risc0-circuit-rv32im-sys Prover emits a succinct receipt that fails its own verify() for rare rand_z values — both backends, in preflight #119 fix (prover/Cargo.toml).
• The id table (wrong on b62d2a60, incomplete) and the v0.10–v0.13 narrative are replaced by a LINEAGE.tsv pointer plus scripts/release.sh. The canonical date is 2026-09-07, per LINEAGE. It now says "The current release is v0.21.4". Before this, check-versions.sh check 4 was silently skipping, because the line it greps did not exist.
• Phone verifier: Build the payoff: SNARK-wrap the range/chain proof, and demo a node syncing from it #19 and Mobile verification: there is no genesis→N proof to hand a phone, and nothing a phone could run #24 are closed, and G3 was met via WASM; Groth16 fails on every CUDA build we ship (sppark illegal memory access); CPU path works #20 was closed won't-fix. The acceleration note no longer says "pure Core, unaccelerated libsecp"; sm_100 is added to the NVCC flags and the cuobjdump expectation (prover/build-release.sh, Ship native sm_100, and make the CUDA version a knob (#178) #181).

docs/METHOD_ID_DURABILITY.md (text of Discussion #299)

• "Happened 17 times" → 17 ids, 16 supersessions. "Linked discussion" now links Should a proof survive a guest change? One METHOD_ID, and what we would do the day we are forced off it #299.
• "Rule coverage unchanged; changes since are performance/build" → no rule added, but 4722cec8 (audit fetch_block.py: coin_mtp = MTP(coin_height-1), not header nTime (fixes #3) #5, e5d8b12) was soundness hardening, not performance.
• The sections duplicated from PROOF_DURABILITY.md (the 1d6c3792 case, the composition mechanism, the two corrections) are cut to pointers. The position statement, the two constraints and the open questions are intact.

docs/PROOF_DURABILITY.md

• "Every guest change across the 7 ids after that date is performance or build work": the 7 includes dfc9eeda itself. Of the 6 later changes, 4722cec8 is hardening. The "7 of 17 share today's rule set" count is correct and stays.
• "Journal-format compatibility (broken before, at 68819a54)": 96407d0 changed the witness wire format, and its diff touches no journal struct. The journal changed when dfc9eeda (70a0fa5) added the SMT roots to RangeState.

Rejected audit findings

• BUILDS "the quoted provision-vps.sh text is not in the file" — both fragments are there: "a box provisioned with this must never produce a shipped proof" is the phase-5b comment, and "This box is for benchmarking only." is its echo. They are not contiguous, though, and they describe the bigint2 verifies ECDSA 13.78x faster than libsecp256k1 in-guest — decide what to do about it #139 patch 0005 lever, not "the Ghost lever". So the finding is only partly right; the quote was corrected rather than removed.
• BUILDS "state measured straggler 1.189x vs 1.438 on shipped defaults" — the Ghost calibration MEASURED on hardware: straggler 1.462x → 1.189x #227 A/B's defaults arm measured 1.462; 1.438 is §1's separate 2026-09-02 run. Both are now quoted, with their sources.
• EXTERNAL_REVIEW "audits Guest: sigop over-count — missing IsPayToScriptHash() guard in tx_full_sigops (reject-valid, consensus divergence, METHOD_ID-affecting) #1, Archive bridge does not emit BIP30 overwrite witnesses → blocks 91842/91880 unprovable via bridge (liveness) #2, guest: guard P2SH sigop count with IsPayToScriptHash() (fixes #1) #4 have no write-up" — which internal audit number AUDIT_2026-07.md corresponds to could not be established from the repo (SECURITY.md keeps the two numbering schemes deliberately separate). The verifiable statement was used instead: it is the only standalone audit write-up.
• LIFTX/TOPOLOGY "HAZYNC_LIFTX_HINT=1 must be set at run time or the guest dies" — true only for commands that build a chunk payload. The hint block is written by write_chunk_inputs and read by guest chunk_prove; the board worker's prove-range-bridge/fold-range path carries no hint block. Applied with that scope.
• PROVING "Groth16 fails on every CUDA build we ship (sppark illegal memory access); CPU path works #20 closed won't-fix" — GitHub's state_reason says completed, but the closing comment says "Closing as won't-fix — upstream defect". The comment was followed.

Checks run (worktree root)

• ./scripts/check-versions.sh — pass ("versions consistent"; check 4 now actually runs: docs/PROVING.md current release (v0.21.4) == newest tag)
• ./scripts/check-spec.sh — pass (10 checks, including the three new §9 ones); negative controls run as above
• ./scripts/check-test-surfaces.sh — pass
• ./scripts/lineage.sh --check — pass (17 rows)
• ./scripts/test-lineage.sh — pass (0 failures)

Left for a human / later PRs

• Gate 4 has never run. An execute-mode check-full on a CORE build, with one signature byte corrupted, must reject. This is an open soundness item for shipped code.
• The accumulator reference control needs a rerun (cd audit-fuzz && cargo +nightly fuzz run delete_soundness_reference -- -max_total_time=300). No builds were run here.
• The CORE card-years (~44–73) and ~11 L40S throughput are inferred from one block (966,108), using BENCH_8xL40S's own aggregate fit. Worth a decision on whether to publish card-years at all.
• docs/PROVING.md still says CUDA 12.8 is installed "over the stock image's 13.2"; the 13.2 part is unverified and untouched.
• For PR C: docs/history/GHOST_GAINS.md:8 and docs/history/README.md:32 still link GHOST_NEXT_BUILD.md; docs/history/TEN_MINUTE_BLOCK.md:1110 cites TOPOLOGY §0.5, which no longer exists; archive the old TOPOLOGY body from f24c43b.