Skip to content

Make room before 0.9.0: five types non-exhaustive, the labels, Verdict::new (no behaviour moves) - #49

Merged
Calgooon merged 5 commits into
betafrom
lane/make-room
Nov 17, 2026
Merged

Calgooon merged 5 commits into
betafrom
lane/make-room

Conversation

@Calgooon

Copy link
Copy Markdown
Contributor

The room made before 0.9.0, and nothing more. Ruled 2026-11-17 16:1xZ: bsv-stack-lean docs/RULINGS-2026-10-12.md (the section of that hour) and docs/DECISIONS-2026-10-19.md 28.8.1, option (c) with its three additions (the labels, the sentence, the CLI's maps); VerdictError is the fifth type by the keeper's reading of 17:1xZ, recorded in the same 28.8.1 (c). The three rows of those rulings (#45 finality, #46 the status code, #47 conflicted keeping its proof) land after the cut as minors. None of them is built here. No behaviour moves: every test of the base keeps its name and its answer, and the compact bytes are unchanged, pinned by a golden that landed on the base before any other change. No version bump, no tag, no release.

The surface

#[non_exhaustive] pub enum HostAction { /* unchanged variants */ }
#[non_exhaustive] pub enum Reask { /* unchanged variants */ }
#[non_exhaustive] pub enum HintStatus { /* unchanged variants */ }   // + Serialize, Deserialize
#[non_exhaustive] pub enum VerdictError { /* unchanged variants */ }
#[non_exhaustive] pub struct Verdict { pub status, pub height, pub reason, pub competitors }

impl Verdict {
    #[must_use] pub fn new(status: impl Into<String>) -> Self; // as given, no height, reason or competitors
}
impl HintStatus {
    pub const LABELS: &'static [&'static str]; // accepted, seen, mined, stale_block, rejected,
                                               // double_spend, orphan_mempool, unknown, mempool_present
    #[must_use] pub fn label(&self) -> &'static str;
}
impl Reask {
    pub const LABELS: &'static [&'static str]; // reorg, fork, hint, proof_failed, recheck, age, spend
    #[must_use] pub fn label(&self) -> &'static str;
}

// HintStatus's serde form, the crate's stored form of a status:
#[serde(tag = "status", rename_all = "snake_case")]
//   DoubleSpend { #[serde(default, skip_serializing_if = "Vec::is_empty")] competitors }
//   MempoolPresent { #[serde(rename = "courier")] source }
// no #[serde(other)], no default kind: an unknown word or a missing payload is refused.

The type alone is marked, no variant. Each label is a match with no wildcard arm. LABELS is in declaration order, which is the compact form's tag order (a unit test inside the crate checks LABELS[i] against the tag the writer gives). Reask has the words alone: no serde, no Display, no bytes. Hint, Verdict and HostAction have no serde. No other type is marked.

Part F's table, after this pull request

From the keeper's design (docs/p0/tracker-rulings-2026-11-17-design.md, part F), by my own read of the crate at this head:

ruling the public change additive after this PR?
28.1 Lock { lock_time, sequences_final }, Lock::from_transaction yes: a new type and a new function.
28.1 HostAction::Lock(Lock); Reask::WaitFinal { lock }, Reask::AnnounceFinal; HintStatus::NonFinal yes: all three enums are #[non_exhaustive]; the words append to LABELS (non_final, wait_final, announce_final) and the compact tags append after version 1's.
28.1 State::finality(&self, &H) -> Finality; the Tracker's pending-lock index yes: a new method and a new type; the index is a private field. The behaviour is new.
28.2 Headers::time_at (a provided method answering Ok(None)); median_time_past(&H) yes: a defaulted trait item and a free function, both minor by Cargo's semver reference.
28.3 State::rivals(), Rival; Reask::CompetitorGone { competitors }; on_chain/recheck select Conflicted by its rivals; the Tracker indexes rivals yes for the API: an accessor, a new type, a re-ask kind on a marked enum, a private index. The behaviour moves in a minor, as 28.8.1 (c) says ("what (c) does not cover"). The compact form goes to version 2, read beside version 1: COMPACT_VERSION changes value (no compile break), and a 0.9.0 reader refuses a version-2 state with UnknownVersion, so hosts on two minors that share one store read each other's rows only from the newer one.
28.4 Verdict::status_code: Option<u16>; into_hint 466 and 476; Verdict::from_arc_refusal yes: a field on a marked struct (Verdict::new sets it to None), a variant of VerdictError if the refusal reader needs one, a new function. The 466 and 476 arms change behaviour.
28.5 nothing

No type outside the five is broken by a row as part F states it. Two depend on the design holding: Word (not marked) stays unbroken only while #47 keeps the rivals beside the word (State::rivals) and not inside Word::Conflicted. CompactError (not marked) stays unbroken only while version 2's refusals fit Malformed. Neither is marked here.

The tests

  • (a) tests/compact_golden.rs, alone on the base: ten states built through the public API. Between them they hold the nine words, a checked proof (mined, suspect after a fork, kept after a stale), every HintStatus kind without a verdict and with one read from an ARC body, and the seven Reask kinds. Each to_compact is asserted against hex written out in the test. Green at that commit (75 passed) and unchanged since.

  • (b) A compile_fail doctest on each of the five, each quoting its code: E0004 for an exhaustive match outside the crate on HostAction, Reask, HintStatus and VerdictError, E0639 for a Verdict literal. Stable rustdoc does not check the code, so I ran them under nightly too: all five hold. With the marks removed, all five compile (5 FAILED), so each fails for its mark alone. tests/verdicts.rs's three literals now use Verdict::new and field assignments, with the same values and the same answers. No match in src/ gains a wildcard arm, and no test under tests/ matched one of the five enums without one.

  • (c) tests/labels.rs:

    • the sixteen (value, word) pairs;
    • both LABELS in order;
    • every status's JSON golden round-tripped to the same text ({"status":"double_spend"} for none, {"status":"mempool_present","courier":"c"}, ...);
    • the serde tag equals label();
    • {"status":"non_final"}, {"status":"mined"}, {"status":"mempool_present"} (and rejected with no reason, a capitalised word, a missing tag) are each Err;
    • the host's shape: { source, #[serde(flatten)] status: HintStatus, observed } reads every text bsv-wallet-cli's StoredHint::of writes and writes it back identical. A copy of StoredHint and of from the CLI's beta at 108f80e (src/tracker_host.rs:408-452) proves those texts are the CLI's, its match gaining an arm that panics aloud on a kind it does not name. flatten round-trips every text.

    There are also two unit tests in src/compact.rs that LABELS[i] is the word of the kind the writer tags i.

The hosts

  • A match on HostAction, Reask, HintStatus or VerdictError gains a wildcard arm that keeps and surfaces what the host does not name (a re-ask by Reask::label). Never an arm that maps to HintStatus::Unknown or drops the value.
  • A Verdict built by literal becomes Verdict::new(status) with the other fields assigned after it. A Verdict { .. } pattern outside the crate also needs its .. now (E0638).
  • A host that stores hints stores HintStatus's serde form and reads it back by it, and surfaces a status the reader refuses.
  • bsv-wallet-cli's stored rows read as they are (the flatten test above). bsv-wallet-cli builds no tracker Verdict and matches no HostAction (git grep on its beta).

The proof (this head, 1d6141b; base 3adda34)

cargo test --locked:

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out   (doctests)
TOTAL passed 87 failed 0      (base: 64; at commit (a): 75)

Every test of the base has the same name and answer at the tip. cargo test --locked -- --list at both, compared by binary: none missing. 23 new: 5 doctests, 11 compact_golden, 5 labels and 2 unit tests.

RUSTDOCFLAGS=-Dwarnings cargo doc --locked --no-deps:

    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.65s
   Generated .../doc/bsv_tracker/index.html

cargo fmt --all -- --check: clean (exit 0). cargo clippy --locked --all-targets -- -D warnings:

    Checking bsv-tracker v0.9.0-beta.8
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.77s

The two vectors steps, as ci.yml runs them:

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 6 filtered out   -> grep: 8 passed OK
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out   -> grep: 1 passed OK

cargo build --locked --target wasm32-unknown-unknown --features wasm: Finished. MSRV: declared 1.88, cargo +1.88 check --locked --all-targets: Finished.

cargo semver-checks --baseline-rev origin/beta --release-type patch (0.51.0; without --release-type it skips all 260 checks, both sides being one prerelease version):

     Checked 229 checks: 227 pass, 2 fail, 0 warn, 31 skip
--- failure enum_marked_non_exhaustive: HostAction, HintStatus, VerdictError, Reask
--- failure struct_marked_non_exhaustive: Verdict
     Summary semver requires new major version: 2 major and 0 minor checks failed

The five marks and nothing else. cargo deny --locked check bans licenses sources: bans ok, licenses ok, sources ok.

git diff origin/beta --stat:

 CHANGELOG.md            |  20 +++
 README.md               |  15 +++
 src/compact.rs          |  62 +++++++++
 src/hints.rs            | 126 +++++++++++++++++-
 src/state.rs            |  66 +++++++++
 tests/compact_golden.rs | 347 ++++++++++++++++++++++++++++++++++++++++++++++++
 tests/labels.rs         | 266 +++++++++++++++++++++++++++++++++++++
 tests/verdicts.rs       |  29 ++--
 8 files changed, 909 insertions(+), 22 deletions(-)

Landing

The landing is the captain's. No release is cut for this alone: it rides the crate's next prerelease. bsv-wallet-cli's pin of that prerelease replaces its two hand maps (StoredHint::of/hint and reask_label) with these words under a test that plants a kind the host does not name. That is a row there, not here.

🤖 Generated with Claude Code

Calgooon and others added 5 commits November 17, 2026 12:44
Ten fixed states that between them hold the nine words, a checked proof
(mined, suspect after a fork, and kept after a stale), every HintStatus
kind without a verdict and with one read from an ARC body (the presence
hint carrying a verdict by Hint's public fields), and the seven Reask
kinds, each reached through the public API. Each state's to_compact is
compared with bytes written out in the test, and a state whose word is
not mined restores equal to itself.

Why: the make-room pull request before 0.9.0 (bsv-stack-lean
docs/DECISIONS-2026-10-19.md 28.8.1 (c), ruled 2026-11-17 16:1xZ) must
move no byte the crate writes. This commit lands alone on the base, so
the later commits are measured against it. No test of the base changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#[non_exhaustive] on the enums HostAction, Reask, HintStatus and
VerdictError and on the struct Verdict; the type alone, no variant
marked, Verdict's four fields still pub. Verdict::new(status) builds a
verdict holding the word as given (not trimmed, not checked) with no
height, no reason and no competitors; from_arc_body stays the checked
reader.

Why: the rulings of 2026-11-17 16:1xZ (bsv-stack-lean
docs/RULINGS-2026-10-12.md; docs/DECISIONS-2026-10-19.md 28.8.1 (c),
VerdictError by the keeper's reading of 17:1xZ) land bsv-tracker #45,
#46 and #47 after the 0.9.0 cut as minors; with the marks their new
kinds, the status-code field and a refusal reader's error are additive.
A host's exhaustive match on the four enums, and a Verdict literal,
stop compiling now instead.

The proof: a compile_fail doctest per type, each quoting its code
(E0004 for the four enums, E0639 for the literal); on nightly, where
rustdoc checks the code, all five hold, and with the marks removed all
five compile. tests/verdicts.rs builds its three verdicts with
Verdict::new and field assignments, the same values and answers. No
match in src/ gains a wildcard arm, and no test under tests/ matches
one of the five enums without one, so none gains an arm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HintStatus::label and Reask::label (#[must_use]) give each kind its
stable word, the payload not in it, the snake_case of the variant's
name; each is a match with no wildcard arm, so a kind added without its
word does not compile. HintStatus::LABELS and Reask::LABELS are every
word in declaration order, which is the compact form's tag order, as a
&'static [&'static str] so a later kind does not change the type.

HintStatus derives Serialize and Deserialize, internally tagged by its
word ({"status":"mined","height":900}); MempoolPresent's source is
written as courier and DoubleSpend's competitors are left out when
empty, so the form equals the JSON bsv-wallet-cli already stores. No
#[serde(other)] and no default kind: an unknown word and a missing
payload are refused. Reask gets the words alone (no serde, no Display,
no bytes); Hint, Verdict and HostAction no serde.

Why: the ruling's labels (bsv-stack-lean docs/DECISIONS-2026-10-19.md
28.8.1 (c), 2026-11-17 16:1xZ): a host that stores hints and shows
re-asks takes the words from the crate instead of a hand map, so a kind
a later minor adds is kept and surfaced, never mapped to Unknown.

Tests: tests/labels.rs (the sixteen pairs, both lists, every status's
text round-tripped, the serde tag equal to label, the refusals, and the
host's shape: a struct with the status flattened between source and
observed reads every text the CLI's StoredHint::of writes, a copy of it
at bsv-wallet-cli 108f80e, and writes it back identical); two unit
tests in src/compact.rs that LABELS[i] is the word of the kind the
compact writer tags i. The compact goldens are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README.md gains "Kinds a later release adds" between "Broadcaster
hints" and "Events and records", and the rustdoc of Reask and of
HintStatus carries the same sentence: a re-ask of a kind the host does
not name is kept and surfaced by Reask::label, never dropped by a
wildcard arm; a hint status is stored by its serde form and read back
by it, never mapped by hand, and a status the reader refuses is
surfaced, never read as HintStatus::Unknown. The words never change, are
never reused, and a later minor only appends.

Why: the sentence is the second of the ruling's three additions
(bsv-stack-lean docs/DECISIONS-2026-10-19.md 28.8.1 (c), 2026-11-17
16:1xZ): without it the marks trade a compile error at a host's pin for
a wrong answer at run time. Docs only; no code moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The lead paragraph (the rows of the rulings of 2026-11-17, bsv-stack-lean
docs/DECISIONS-2026-10-19.md 28.8.1 (c); the five types non-exhaustive,
so a host's exhaustive match on the four enums and a Verdict literal
stop compiling; no behaviour moves and the compact bytes are unchanged,
pinned by tests/compact_golden.rs), then Changed (the five marks), Added
(Verdict::new, label and LABELS, the serde form of HintStatus, the
tests) and Hosts (the wildcard arm that keeps and surfaces, Verdict::new
for a literal, the stored form, and that bsv-wallet-cli's stored rows
read as they are).

Also one word of a test comment in src/compact.rs ("leading byte"), for
the wording rule; no code moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Calgooon Calgooon added this to the 0.9.0 milestone Nov 17, 2026
@Calgooon Calgooon added the enhancement New feature or request label Nov 17, 2026
@Calgooon
Calgooon merged commit 7bbce4f into beta Nov 17, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant