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.
Task
The worked examples in
crates/dig-wallet/src/sage/sources.rs's sweep documentation are prose, notexecuted 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.
:501claimed#[cfg(test)] fn f() { ChiaQuery::new(c); }fails loudly; it measuressites=[2]— the constructionis 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::newappears inproduction 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
sweep/production_linesdocumentation into doctests thatactually run the classifier and assert the measured
sites/ended_inside_a_test_itemvalues.c5aad53; the doctest justmakes them self-enforcing.
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
https://github.com/DIG-Network/dig_ecosystem/issues/2760
crates/dig-wallet/src/sage/sources.rs, statements at:26,:501,:508Done 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.