Document timeoutMs, fetch, debug and the client's limits in the README

[dmccoystephenson]

Summary

Stage A documentation accuracy sweep. The README names the optional debug callback but never describes it, and leaves several user-facing behaviours of trace-client.ts undocumented. A new "Options and limits" section is added after "What report promises". Each claim was checked against the source:

• timeoutMs: default 5000; anything but a positive finite number falls back to it (trace-client.ts:184-188).
• fetch: defaults to the global fetch (trace-client.ts:293).
• debug: lines are prefixed [trace] , and a throwing sink is swallowed (trace-client.ts:317-324).
• flush(timeoutMs) / close(timeoutMs): default to the client timeout. A negative or non-finite bound counts as 0 (bounded(), trace-client.ts:432-433).
• Which drops produce a debug line: the in-flight cap, a serialize failure, a delivery failure or abort, and a non-2xx answer. The last two include the JSON body. Silent no-ops are a disabled or closed client and a blank or non-string name (trace-client.ts:233-262, 307-309).
• Tag cleaning: null/undefined values are dropped, other values are converted with String(), and a conversion that throws drops the report with a debug line (withVersion()/serialize()).
• TraceClient.TIMEOUT_MS, IN_FLIGHT_CAPACITY and MAX_VERSION_LENGTH are listed.

No tracking issue: the gap was found during triage. The backlog had no open issues when this cycle started, so no issues were skipped.

Test plan

• Every new README claim was checked against trace-client.ts and the existing tests. The fallback, tag-cleaning, negative-timeout and throwing-debug behaviours are already pinned by tests in tests/trace-client.test.ts.
• CI (npm ci, npm run typecheck, npm test on Node 22) is green. Local run: UNVERIFIED-not-applicable. Node is not installed in the dispatch sandbox, and no code or test file is changed.

Cross-client parity / changelog

• No cross-client-visible behaviour changed, so trace-client-python and trace-client-java need no matching change.
• CHANGELOG.md has no new entry. trace-client.ts is unchanged, so a re-vendor brings nothing new. The changelog records changes to the vendored file.

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 (docs-only PR, anchored on CI run 36687986169: # tests 44, # pass 44, # fail 0):

• Scope: PASS. Only README.md is modified (+29 lines), all in the new "Options and limits" section.

• Tests-new: PASS (not applicable). No public member was added.

• Tests-fix: PASS (not applicable). No bug fix is included.

• Sibling structure: PASS. The section uses the README's existing ## heading plus a | Option | Default | Meaning | table, matching the Next.js opt-out table.

• Sibling renames: PASS (not applicable). Nothing was renamed.

• Docs: PASS. Each claim was traced to source:

  • timeoutMs fallback: trace-client.ts:184-188
  • fetch default: :293
  • [trace] prefix and throwing-sink swallow: :317-324
  • flush/close bound of 0: bounded(), :433
  • Logged drops: :238, :245, :251, :308
  • Silent no-op: :234
  • Tag cleaning: withVersion() and serialize()
  • Constants: :113-116

  The TSDoc for debug ("one line per dropped report") agrees with the README.

• Issue resolution: PASS (not applicable). No Closes; the gap was found during triage.

• CI: PASS. The test job is green on the PR head, and 44 tests executed.

Repo-specific: trace-client.ts, tsconfig.json, package*.json and the export surface are untouched, and the version string is unchanged. No CHANGELOG.md entry is needed because the vendored file did not change. Cross-client parity is not affected.

Judgment call, not changed: README.md (new section) says that debug lines for failed or non-2xx deliveries include the JSON body. That is accurate (trace-client.ts:251, :308). Calling it out lets a program that forwards debug to shared logs see that tag values such as page paths will appear there. A reviewer may prefer that this caveat move into the TSDoc for debug as well. That is left for a code cycle, since this PR does not touch trace-client.ts.

Local anchor: UNVERIFIED-not-applicable. Node is absent in the dispatch sandbox, and no file the anchor validates was modified.

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

---

drafted by Claude on behalf of Daniel Stephenson