[dmccoystephenson]

Summary

• main went red after Say what the logger hears and that queue drops are silent, in the Javadoc #21 (a Javadoc-only change). queue_isBoundedAndDropsRatherThanGrows failed on the Java 8 leg with logged: 1. The same tree had passed both of Say what the logger hears and that queue drops are silent, in the Javadoc #21's pull_request runs, so this is a flake in the assertion added in Say that queue drops are silent and how the tags block skips lines #20, not a regression.
• In that test the server only answers 201, so the one line the send path can log is could not deliver …, written when one of the ~257 short-lived loopback connections fails. Requiring zero lines assumed loopback never fails.
• The assertion now allows only lines starting [trace] could not deliver , and fewer of them than a tenth of the 511 drops. A client that logged each drop still fails the test, and the failure message lists the logged messages instead of only their count, so a future failure shows what was written.
• Test-only change. TraceClient.java, the README and the contracts are untouched.

Test plan

• mvn -B verify locally (Java 21): 78 tests run, 0 failures
• The test run 40 times in a row locally (temporary @RepeatedTest(40), not committed): all passed. The flake did not reproduce on Java 21.
• Mutation check, DiscardPolicy swapped temporarily for a handler that logs each drop as dropped a report: fails on the prefix assertion
• Mutation check, drop logged as could not deliver a report: fails on the count assertion (logged 511 lines)
• CI matrix (8, 17, 21) green on the PR head

Closes #22

Not picked this cycle: #15 (quoted enabled: "false" in the server-wide config) and #13 (withVersion past MAX_TAGS). Both change opt-out or wire behaviour, which is a contract with the server, operators and every program that vendors the file, so they need a maintainer decision. Fixing the red main came first.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (scored against CI run 39402161259 on the PR head, plus local mvn -B verify):

• Scope: PASS. The only file changed is TraceClientTest.java (+12/−3): the import and the one assertion queue_isBoundedAndDropsRatherThanGrows flakes on Java 8: one failed loopback send fails the drops-are-silent assertion #22 names.
• Tests-new: PASS (not applicable). No new public members.
• Tests-fix: PASS, checked by mutation because this is a test-only flake fix with no production revert to stash. Swapping DiscardPolicy temporarily for a handler that logs each drop made the test fail. A drop message worded could not deliver … failed on the count bound with logged 511 lines. Both mutations were reverted, and git ls-files src/main / git diff origin/main show TraceClient.java untouched.
• Sibling structure / sibling renames: PASS (not applicable). No new files and no renames.
• Docs: PASS. The README "What report promises" row and the class Javadoc still say drops are silent, and the test still enforces that.
• Issue resolution: PASS. queue_isBoundedAndDropsRatherThanGrows flakes on Java 8: one failed loopback send fails the drops-are-silent assertion #22 asks for tolerance of the odd failed send, keeping the regression value, and printing the messages. All three are in the diff.
• CI: PASS. build (8), build (17) and build (21) are green on the head.
• No dependencies / single file / Java 8: PASS. pom.xml is untouched, src/main still holds only TraceClient.java, and streams and lambdas are Java 8 (the build (8) leg passed).
• Never throws / non-blocking & bounded / environment seam / version agreement / opt-out contract: PASS (not applicable). No production code changed.

Inline findings:

• src/test/java/software/stephenson/trace/TraceClientTest.java:526: the dropped / 10 tolerance (51 lines) is a judgment call. It is generous enough that a few transport failures on a slow runner never trip it, and far below the 511 lines that logging every drop would produce. The flaky line itself was never seen (the old message printed only a count), so "a failed loopback send" is the only explanation the code allows, not one that was observed.
• Phase 5 caveat: the flake did not reproduce in 40 local runs on Java 21, and only Java 8 CI showed it. A recurrence will now print its message.

Summary: a test-only, one-assertion fix for the red main. It touches no do-not-auto-merge path.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson