Skip to content

quality.md

Latest commit

 

History

History
145 lines (121 loc) · 9.82 KB

quality.md

File metadata and controls

145 lines (121 loc) · 9.82 KB
Raw

Quality roadmap (living)

Ranked remaining work and invariants that must not slip. Closed work lives in CHANGELOG.md. Peer-node notes: peer-clients.md (do not copy here).

Last reaudit: 2026-10-08. Live schema: SCHEMA.md (SCHEMA_VERSION = 26). Q-64, Q-71, and Q-72 are off this list: SV2 plans A–C are in tree, and the Talip and Livera indexes are fully dispositioned. Core functional inventory: core-functional.md. Findings 001–023 fixed. Nightly fuzz 21 jobs. Nightly mutants, 8 hour budget split between new code and the backlog, cursor on the mutants-state branch (not required; owner TESTING.md). Previous: 2026-09-15.

Section Purpose
Open Single prioritized backlog — rank 1 = next
Won't fix Retired. Do not reopen without a new product decision
Protect Invariants. Not a backlog. Do not “improve” them away

P0 trust/correctness (Q-01–Q-05) stays empty unless there is new evidence (failed Core corpus, new dual path, red required CI, MSRV drift).

Open (priority order)

Counts and procedures stay in the owner doc. A row is the rank and the outcome.

Rank ID Item Done looks like
1 Q-41 Grow Core functional run set Inventory run covers claimed wallet-client / P2P / mempool / buried-activation, and each run hits node production. Owner: core-functional.md.
2 Q-48 BIP331 rust-bitcoin package types Native package types when rust-bitcoin exposes them (RB-007), then the local RPC / Esplora / Electrum package calls. Owner: rust-bitcoin-limitations.md, COMPAT.md.
3 Q-31 Hermetic tip fixtures Frozen signet/mainnet tip packs for offline consensus/Electrum regression (no live API). Fuzz already merges tiny signet_block_*.bin / mainnet_block_290329.bin. Electrum hermetic packs still Open.
4 R-10 Residual god-files Peel only when a higher row needs a seam. Do not split interpreter.rs opcode match or io_uring machines. Named extracts: Q-61 Completed. Q-56 Completed (scriptnum + pack-ints). Q-68 Completed (create.loc SIMD).
5 Q-67 asked_blocks clone on hold hold_body clones asked_blocks before held_bodies insert so the read lock does not overlap the write (HeldBodies::insert already takes &HashSet). Bound is MAX_SERVE_BLOCKS × peers. Follow-up: pass the read guard with a documented lock order, or keep the clone as a named trade. Owner: crates/rbitcoin-net/src/chain.rs.
6 Q-70 Batch lookup-path hit counters if a profile names them head_resolve_stats::add_hit_rank does two relaxed fetch_adds per resolved txid (head_resolve_denserels, tx_table). SH extract collect flushes output and hit counts once per fk batch, not per output. Still once per event: accepted_wb (SeqCst, per confirmed block), serve_perf::note_serve (per historical getdata), page_ios (per SH page read). Done: a profile shows add_hit_rank on confirm lookup and those counters flush per batch, or the profile shows the line is noise and this row moves to Won't-fix. add_hit_ages is already a batched flush; add_hit_age remains the one-bucket path.

R-ids were the 2026-08-12 slice. Canonical id is bold. Do not start R-11+. Next unused Q-id is Q-73.

Close work by writing the Open row into changelog.d/ in the same edit as the landing change (do not grow a Completed museum here). New item: insert at an explicit rank with Q-63+.

Won't fix

ID Item Why
Q-24 CODEOWNERS / issue templates No public collaboration process
Q-25 crates.io package metadata Distro is nix build .#rbitcoin-musl
Q-32 Structured logging option INFO/DEBUG text is the operator contract
Q-33 Published rustdoc site cargo doc locally; no docs.rs until crates.io
Q-35 Mainnet soak program Signet first, then mainnet with monitoring. No badge
— Darwin notarization Ad-hoc codesign -s - only
— Leftover maps as txid → Vec<Fk> errata.md: only if a mainnet miss is shown
X-M3 Esplora unbounded process sh_join LRU Last-1 GET + last-bulk POST (16 MiB/client) shipped. Sticky joins stay Electrum TCP
— BIP331 package relay and package RBF submitpackage package-evaluates a child-with-parents remainder (package feerate, dynamic-floor waiver). No P2P package message and no package RBF
— Chained Esplora scripthash_mempool_stats Dialect / page cost. Compact /txs/summary is COMPAT dialect
— Retired algo-review micro-opts Reopen a named Q-id only with a mainnet profile that names the cost
— Headerless SH extent interiors Uniform 4 KiB page records; ~0.2% density; schema bump
— Restore rbtc-script-coord-* ibd-confirm publishes waves. No coordinator threads
— Flatten purpose-built io_uring machines io-modality.md: fix the machine; do not replace it with generic batched pread/pwrite without asking
— Large process-resident body, pin, or archive caches (FIFO, LRU, or sticky residency). Examples: process pin FIFO, CreateResidency, ContigPark, archive sticky Pins are plan/batch only. IBD is body-queue → lookup → load
— rbitcoin-bench in default-members / musl / required CI Optional host A/B. Not a packaging or coverage gate
— cargo miri test --workspace io_uring, tokio, secp256k1-sys. Primitives only
— LCOV never-falls vs master llvm-cov LH jitters tens of hits. Floor is 93%
— ast-grep as a second clippy Structural RSS/task-leak shapes only
Q-54 ast-grep named-cap rules Caps live in ibd-memory.md and production evict. Pinning const = 128 is a second clippy. Q-51 already owns shapes.

Coverage theater (chasing 100% lines), rewriting secp/rust-bitcoin/tokio “to reduce deps”, Core-complete RPC, and explorer-search APIs (address-prefix) are also not Open. Liquid and in-binary mempool.space /api/v1/ catalogue stay out.

Parked (not now; promote to Open with a rank to revisit)

Wallet-backing extras from the 2026-09 node survey. Not Won't-fix forever — just not the current product. COMPAT/OPERATOR stay the shipped contract.

ID Item Why parked Reopen when
Q-63 Electrum TLS (50002) + Tor onion in the binary Home Sparrow/phone off-LAN today uses nginx (OPERATOR.md). Node stays plain TCP. Operators refuse a reverse proxy, or a first-class onion listener is the 1.0 install.

Protect

Do not “improve” these away. Design owners are linked; this is the checklist.

  • Thesis: relational archive, pure-Rust scripts, in-process Electrum/Esplora, Linux map-free IO + optional io_uring, reproducible musl. Not a Core clone. architecture.md.
  • No silent consensus/store fallback. Missing promised fact → StoreError::Corrupt("invariant: …"). Confirm dual-path kill. TxApply → dummy Block is rbitcoin_query::testutil only. One Class A planner.
  • Concurrency / IBD: no locks on the store hot path; one Class A appender; ibd-confirm publishes script waves (no coordinator). Pins are plan/batch only. concurrency.md, invariants.md.
  • On-disk: SCHEMA.md current bytes (live SCHEMA_VERSION). Soft-migrate durable side formats; bump or refuse; no silent wipe. Same commit as the format code.
  • io_uring: do not flatten a purpose-built machine to batched pread/pwrite without an explicit ask. io-modality.md.
  • SH create_count: last-page reserved is stamped by the appender. Query/cap probes are read-only (walk when reserved is 0). Do not pwrite the last page from the join path.
  • Live P2PNode tests: topologies in one process may overlap. Each script stage registers its thread; unpark_script_publisher wakes every registered stage. Do not serialize the suite with a process mutex. Do not “fix” flakes with RUST_TEST_THREADS=1. TESTING.md.
  • Default CI is the pin. Unlabeled PRs: cargo test, not Core functional. Floor, CRAP, and what a test may assert: TESTING.md.
  • Operator honesty: experimental 0.x; milestone skip is loud; CLI/conf share apply_kv; dummy RPC numbers labeled or gone; COMPAT matches shipped surface (including Esplora /txs/summary as a dialect).
  • Build: rustc 1.95.0 in CI and Nix; cargo deny; no floating stable. Musl operator binary is GitHub Release only.
  • Fuse8 / leftover: sealed .fuse8 fingerprints are read-only mmap (heap fuse8=0); SH BDZ3 occupancy is the same class (prefix map; mphf_occ= supers); BDZ g is FdOnly. Optional sp_tweaks leftover regenerate is not a Class A wipe.
  • Meters: instance ConfirmStats / session IO stats. Tests assert shipped behavior via those stats or on-disk state, not thread-local hot-path IO probes (example: test_take_*). No process-global confirm meters.
  • Crate graph: unused pub is forbidden; fuzz lives in fuzz/. Clippy: no workspace allow list (code-shape.md).
  • Findings: crashes → docs/external_findings/ + named regression. Core JSON corpora without allowlist.

Suite budgets, coverage math, and default-vs-nightly Core: TESTING.md. Agent hard rules: AGENTS.md.

Reaudit after a multi-commit quality program or when Open claims would rot. Do not restore a LOC snapshot, grade board, or Completed museum.