Skip to content

test(dig-wallet): make the sweep guard's worked examples doctests — a backwards example survived four gate rounds #363

Description

@MichaelTaylor3d

Task

The worked examples in crates/dig-wallet/src/sage/sources.rs's sweep documentation are prose, not
executed code
. Make them doctests, so a wrong example fails CI instead of misleading a reader.

Why this is worth doing

A doc example that was exactly backwards survived FOUR gate rounds on that file. :501 claimed
#[cfg(test)] fn f() { ChiaQuery::new(c); } fails loudly; it measures sites=[2] — the construction
is dropped. Correct behaviour (it is test code), and the doc asserted the opposite.

Four rounds of adversarial review read past it, because reviewers read a doc example as documentation
rather than as a claim to test.
Everything else in the file was measured; only the examples were not,
and that is precisely where the false statement lived.

The same file also carried, across earlier rounds, "It fails when a second ChiaQuery::new appears in
production code anywhere in this crate"
and "every imprecision fails LOUDLY" — both false, both
retracted. The pattern is that the guard's prose over-claims and nothing mechanically contradicts it.

Scope

  • Convert the worked examples in the sweep / production_lines documentation into doctests that
    actually run the classifier and assert the measured sites / ended_inside_a_test_item values.
  • Keep the inline measured outputs that are there now — they are correct as of c5aad53; the doctest just
    makes them self-enforcing.
  • A doctest that cannot fail is worse than prose, so each one must be shown to fail when its expected
    value is altered.

Out of scope

Do not add another classifier heuristic. Five gate rounds established that the durable artifact is the
fail-closed flag plus an honest, explicitly-open enumeration — not a better parser. This ticket is about
making the documentation self-checking, nothing else.

Context

Done condition

The worked examples execute in CI, and altering any expected value makes the test suite fail.

Effort

Low-medium. The examples exist and their true values are measured; the work is wiring them so they run.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions