[dmccoystephenson]

Stage A documentation accuracy sweep, run after the 0.7.0 coalescing change (#30). Each claim was checked against TraceClient.java.

Summary

• Class Javadoc: "Three properties hold for every call to report" is corrected to "Four". The list gained "It is throttled" in 0.7.0, but the count was not updated.
• Builder.logger Javadoc: said only a report dropped by a full queue goes unlogged. A new event dropped because MAX_COALESCED_EVENTS other events are already being counted is also unlogged (report(): return; // bounded, like a full queue: dropped without a log line). That case is now stated.
• report(String, Double, Map) Javadoc and README "Repeated events are coalesced": the counting formula ("sum of value where coalesced is present, 1 where not") is now qualified. withCount does not add the tag when the event already has MAX_TAGS tags or its own coalesced tag, so such a count reads as a single report. Only the current behaviour is documented here. Whether to change it is a wire-format decision, filed as A coalesced count at MAX_TAGS, or on an event with its own coalesced tag, is sent without its count tag #31.
• README "The wire format": now says that count events also carry coalesced.
• close() Javadoc: a stray line break is rejoined, with no wording change.

No code, contract strings, version strings, or "Opting out"/"Keys" README sections are touched.

Open issues not picked

• withVersion pushes an event already at MAX_TAGS over the server's tag limit #13, A quoted enabled: "false" in the server-wide config does not turn reporting off #15, A comment-only enabled: line in the server-wide config shadows a later enabled: false #27: each needs a maintainer decision on the wire format or the opt-out contract (stated in each issue), so none of them can be done autonomously.

Test plan

• mvn -B verify locally on Java 21: 94 tests run, 0 failures
• CI matrix (Java 8, 17, 21) green on the PR head

No tracking issue: the drift was found during the sweep. Follow-up filed: #31.

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

---

drafted by Claude on behalf of Daniel Stephenson

🤖 Generated with Claude Code

[dmccoystephenson]

Self-review rubric (scored after CI went green on all three legs, build (8), build (17) and build (21), at the PR head):

• Scope: PASS. Only README.md and Javadoc comments in TraceClient.java change. Each edit corrects one specific drift item listed in the PR body.
• Tests-new: PASS (not applicable). No new public members.
• Tests-fix: PASS (not applicable). No bug fix; the behaviour behind A coalesced count at MAX_TAGS, or on an event with its own coalesced tag, is sent without its count tag #31 is documented, not changed.
• Sibling structure: PASS. No new files.
• Sibling renames: PASS. No renames.
• Docs: PASS. The class Javadoc property count, the report() Javadoc, the Builder.logger Javadoc, the README coalescing section and the README wire format now agree with report(), flush() and withCount().
• Issue resolution: PASS (not applicable). No Closes; follow-up A coalesced count at MAX_TAGS, or on an event with its own coalesced tag, is sent without its count tag #31 was filed for the behaviour.
• CI: PASS. All three matrix legs are green on the head commit; locally, mvn -B verify ran 94 tests with 0 failures.
• No dependencies / single file / Java 8: PASS. pom.xml is unchanged; git ls-files src/main lists only TraceClient.java; there are no non-java.* imports.
• Never throws / non-blocking / environment seam / version agreement / opt-out contract: PASS. No executable code, version string, REASON_*/ENV_* constant or "Opting out" table changed.

Findings:

• src/main/java/software/stephenson/trace/TraceClient.java:926: rejoining the stray close() line break left a line of about 100 columns. Fixed in the follow-up reflow commit, and CI was re-confirmed green.
• src/main/java/software/stephenson/trace/TraceClient.java:779: {@value #MAX_TAGS} points at a package-private constant from public Javadoc. This matches the existing {@value #MAX_TAG_LENGTH} usage on builder(), and no javadoc plugin runs in the build, so it was left as is.

Summary: the PR touches documentation only and contains no do-not-auto-merge paths (no pom.xml, workflow, contract constant, version, or "Opting out"/"Keys" section changes).

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

---

drafted by Claude on behalf of Daniel Stephenson