[dmccoystephenson]

Stage A documentation accuracy sweep. Javadoc-only; no code, wire format or opt-out contract is changed.

Summary

• Builder.logger Javadoc said "Where dropped reports are mentioned". A report dropped because the queue is full goes through DiscardPolicy and is never logged, which the README "Bounded" row has stated since Say that queue drops are silent and how the tags block skips lines #20. The logger is also handed more than drops: build() logs a server-wide config or install ID file that could not be read or written. The Javadoc now lists what is logged ([trace]-prefixed, at FINE) and states that queue drops are not.
• The class Javadoc "It is bounded" bullet now says the drop happens without a log line, even at FINE, matching the same README row.

The rest of the sweep (README example, "What report promises", "Opting out", "Getting it", "The wire format", "Building", the class and method Javadoc, pom.xml, the build.yml comment) was checked against TraceClient.java and no other drift was found. The four version strings still agree at 0.6.1.

Test plan

• mvn -B verify locally on Java 21: Tests run: 78, Failures: 0, Errors: 0, Skipped: 0
• CI matrix build (8), build (17), build (21) green

Deferred issues

• withVersion pushes an event already at MAX_TAGS over the server's tag limit #13 (withVersion and MAX_TAGS): changes what is sent on the wire, so it waits for a maintainer decision.
• A quoted enabled: "false" in the server-wide config does not turn reporting off #15 (quoted enabled: "false"): touches the opt-out contract, so it waits for a maintainer decision.

No tracking issue: the drift was found during triage.

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 (head 6aaeff9):

• Scope: PASS. One file, TraceClient.java, and only Javadoc: the class "It is bounded" bullet and Builder.logger. No code lines changed.
• Tests-new: PASS (not applicable). No new public member was added.
• Tests-fix: PASS (not applicable). This is a documentation fix, not a behaviour change, so there is nothing to revert-and-run.
• Sibling structure: PASS. No new files were added.
• Sibling renames: PASS. Nothing was renamed.
• Docs: PASS. Every claim was checked against the log(...) call sites. send() logs "trace server answered" for any status other than 201 and "could not deliver" for IOException | RuntimeException. resolveInstallId logs an in-memory server-id when the file was unreadable or could not be written. loadOrCreateInstallId logs a read or write failure on the install ID file. readServerWideConfig logs a read failure. DiscardPolicy has no log site, which matches the README "Bounded" row.
• Issue resolution: PASS (not applicable). No Closes #N. The drift was found in a Stage A sweep.
• CI: PASS. Run 39231900452 on head SHA 6aaeff9: build (8), build (17) and build (21) all succeeded. Locally, mvn -B verify on Java 21 ran 78 tests with 0 failures.

Repo-specific:

• No dependencies: PASS. pom.xml is unchanged, and every import is java.*.
• Single file: PASS. git ls-files src/main lists only TraceClient.java.
• Java 8: PASS. build (8) is green, and maven.compiler.release is still 8.
• Never throws / non-blocking / bounded: PASS. No executable code was touched.
• Environment seam: PASS. System::getenv appears only in the environment initializer.
• Version agreement: PASS. No version string changed (0.6.1 in all four places).
• Opt-out contract: PASS. No REASON_*, ENV_*, precedence or README "Opting out" change.

Judgment note: src/main/java/software/stephenson/trace/TraceClient.java:961 — the Builder.logger Javadoc now lists the kinds of message it receives. Any future log(...) call site will need this list updated. A broader wording ("problems ... such as") was considered. It was rejected because the point of the fix is to state precisely that queue drops are not logged.

Do-not-auto-merge path check: only TraceClient.java Javadoc changed. The wire format, REASON_*/ENV_*, precedence, QUEUE_CAPACITY, timeouts, SERVER_WIDE_CONFIG_CONTENT and version strings are untouched, so no protected path matches.

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

---

drafted by Claude on behalf of Daniel Stephenson