Document GPT diagnostics attribution and correlation evidence

[prk-Jr]

Summary

• Complete the public GPT Runtime Diagnostics guide against the behavior merged in Attribute GPT renders to Trusted Server on observed evidence #997, so an operator can interpret request-path, delivery, replacement, and attribution evidence rather than only open the console.
• Document the one server-side effect of enabling the integration that the guide never mentioned: the per-auction hb_auction_id correlation token published into window.tsjs.bids, and the targeting boundary that keeps it out of the GAM ad request.
• Remove a stale claim carried over from the pre-Attribute GPT renders to Trusted Server on observed evidence #997 implementation ("No creative-provenance or auction attribution claims") and make the diagnostics guide reachable from the GPT integration page.

Changes

File	Change
docs/guide/integrations/gpt-diagnostics.md	New "Auction correlation token" section (token format, per-auction minting, not EC-derived, not a GAM targeting key, absent without winning bids); badge content and delivery-label table; creative-bridge failure table with the bridge condition that triggers each category; Ad Manager identifier normalization (positive whole numbers, eight-ID list cap); adInit refresh scoped context alongside Prebid's; three new troubleshooting entries for unattributed/competing refreshes, candidate_unconfirmed delivery, and missing correlation evidence (all eight attribution reasons); exact ?ts_console=1 activation and ?ts_console=0 deactivation examples
docs/guide/integrations/gpt.md	Link the diagnostics guide from "Ads Not Rendering" troubleshooting and from "Next Steps"
docs/guide/integrations-overview.md	Replace the stale "no attribution claims" bullet with the delivery-evidence, request-path, and Ad Manager identifier capabilities, keeping the evidence boundary explicit

Closes

Closes #1014

Test plan

• Docs format: cd docs && npm run format
• Docs lint: cd docs && npm run lint
• Docs build: cd docs && npm run build (VitePress build succeeds; #auction-correlation-token anchor and sidebar/integration links resolve in the built output)
• cargo fmt --all -- --check
• JS format: cd crates/trusted-server-js/lib && npm run format
• cargo test-fastly && cargo test-axum — not run: no Rust source changed
• cargo clippy-fastly && cargo clippy-axum — not run: no Rust source changed
• JS tests: cd crates/trusted-server-js/lib && npx vitest run — not run: no JS source changed
• Other: every documented value traced back to source — request paths, opportunities, delivery states, response classes, creative failures, and attribution reasons against crates/trusted-server-js/lib/src/core/types.ts and .../gpt_diagnostics/store.ts; token minting and gating against crates/trusted-server-core/src/publisher.rs; targeting keys against crates/trusted-server-js/lib/src/integrations/gpt/index.ts; badge labels against .../gpt_diagnostics/badges.ts; identifier caps against .../gpt_diagnostics/observer.ts

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...") (documentation only; no code changed)
• Uses tracing macros (not println!) (documentation only; no code changed)
• New code has tests (documentation only; no code changed)
• No secrets or credentials committed — examples use publisher.example.com and a fictional token value

[ChristianPavilonis]

Automated Review:

Review Summary

Reviewed the documentation-only change against the GPT diagnostics implementation and its surrounding request, delivery, refresh-attribution, correlation, and export behavior. No high-confidence correctness, security, compatibility, or documentation defect was identified.

Findings

P0 / Blockers

None.

P1 / High

None.

P2 / Medium

None.

P3 / Low

None.

CI / Existing Reviews

All reported PR checks are passing. No prior submitted reviews or inline review comments were present at review time. Local documentation formatting could not be run because the repository's documentation dependencies are not installed (prettier: not found); the PR's format-docs CI check is passing.

[aram356]

Summary

Docs-only completion of the GPT Runtime Diagnostics guide against the #997 behavior. Nearly every added claim verified exactly against source: token minting, format, and gating (publisher.rs), the six targeting keys, all four ts_console directives and cookie attributes, standalone caching and load order, all seven delivery states and badge labels (badges.ts), all eight attribution reasons and every retention constant (store.ts), the Ad Manager identifier normalization (observer.ts), and the Prebid-restores/adInit-clears context asymmetry. Two of the new statements do not match the store's actual behavior and should be corrected before merge; details in the inline comments.

Blocking

🔧 wrench

• Empty-render cycles can still export a delivery claim: the creative_request_on_empty_cycle row says the attempt was dropped "instead of claiming delivery", but the stamped selection/response timestamps survive an explicitly empty render and export as trusted_server_selected / trusted_server_response_sent (docs/guide/integrations/gpt-diagnostics.md:527)
• creative_attempt_unknown description incomplete: it also fires on a repeat creative markup request referencing a capacity-evicted attempt, not only on responses and failures (docs/guide/integrations/gpt-diagnostics.md:529)

Non-blocking

♻️ refactor

• State the 30-second bound on late delivery upgrades (docs/guide/integrations/gpt-diagnostics.md:514)

⛏ nitpick

• "one server-side effect" undercounts: module-route availability is also activation-independent (docs/guide/integrations/gpt-diagnostics.md:48)
• cache_fetch_failed also covers body-read failure after an OK status (docs/guide/integrations/gpt-diagnostics.md:229)

🏕 camp site

• Duplicate w?/h? members in AuctionBidData: crates/trusted-server-js/lib/src/core/types.ts:91-100 declares the winning creative width/height pairs twice. Pre-existing on main and outside this diff; worth a one-line cleanup in a follow-up.

CI Status

• GitHub checks: PASS (all 19, including format-docs, cargo fmt, clippy-equivalent analyze jobs, all adapter test suites, vitest, browser and parity integration tests)
• Local re-verification on the PR branch: docs format PASS, docs lint PASS, VitePress build PASS (anchors and links resolve)

[prk-Jr]

All five inline items verified against source and addressed in 69b7d29. Both blocking items are fixed as behavior corrections, not just wording softeners — replies in each thread carry the trace.

The first one leaked into two more places than the flagged row, so the not_applicable row and the "never produce a delivery claim" preamble were corrected alongside it. The 30-second bound was also applied to the duplicate unbounded claim at line 219.

On the 🏕 camp-site item: confirmed the duplicate w?/h? members exist in AuctionBidData and that they are pre-existing — git diff origin/main...HEAD touches only the three doc files, and git show origin/main:crates/trusted-server-js/lib/src/core/types.ts already carries both pairs. Leaving it out of this docs-only PR; worth noting that duplicate interface members are a tsc error, so it is likely surviving only because esbuild strips types without checking. Happy to open the follow-up if you want it tracked.

Verification on the updated branch: npm run format PASS, npm run lint PASS, npm run build (VitePress) PASS.

[ChristianPavilonis]

Automated Review:

Review Summary

Reviewed the documentation-only changes at 69b7d29ed2d647a4c357bd137d32a349dee5f68a against the GPT Runtime Diagnostics implementation and the current PR feedback. No high-confidence correctness, security, compatibility, or documentation defect was identified.

Findings

P0 / Blockers

None.

P1 / High

None.

P2 / Medium

None.

P3 / Low

None.

CI / Existing Reviews

All reported required PR checks are passing, including format-docs. Local documentation formatting could not run because the documentation dependencies are not installed (prettier: not found). Existing inline review feedback was addressed in the current head; no additional inline comments are submitted.

[aram356]

Summary

Re-review of head ae55e2f after 69b7d29ed. All five findings from the previous round are fixed, each re-verified against the runtime source rather than taken from the replies. No new findings; no source file behind the doc's claims changed between the two review bases.

Prior findings, verified resolved

• 🔧 Empty-render cycles exporting a delivery claim: the creative_request_on_empty_cycle row now states the attempt is dropped and cannot complete while stamped selection/response evidence still appears as the cycle's delivery state; the not_applicable row and the attribution-issue preamble were also qualified to match. All three now agree with delivery() checking the Trusted Server timestamps ahead of the isEmpty branch and eviction leaving those stamps in place (docs/guide/integrations/gpt-diagnostics.md:213, 520, 527).
• 🔧 creative_attempt_unknown description incomplete: now "A request, response, or failure referenced an attempt no longer retained", matching the repeat-markup-request path through the unpruned attemptIdsByCycle map (docs/guide/integrations/gpt-diagnostics.md:529).
• ♻️ Unbounded late-upgrade claim: both statements now carry the 30-second attempt window, and the troubleshooting version adds that the window is measured from the cycle's GPT request and requires the cycle to still be retained — matching the strict > gate in store.ts (docs/guide/integrations/gpt-diagnostics.md:220, 514).
• ⛏ "one server-side effect" undercount: now "one further server-side effect, beyond module availability", consistent with the activation-independent standalone module route (docs/guide/integrations/gpt-diagnostics.md:48).
• ⛏ cache_fetch_failed body-read path: the row now includes "failed while reading the body", matching the shared rejection handler for res.text() failures (docs/guide/integrations/gpt-diagnostics.md:229).

Still open, out of this PR's scope

• 🏕 Duplicate w?/h? members in AuctionBidData (crates/trusted-server-js/lib/src/core/types.ts:91-100): pre-existing, outside this docs diff; tracked from the previous review for a separate cleanup.

CI Status

• Analyze (actions): PASS
• Analyze (javascript-typescript): PASS
• Analyze (rust): PASS
• CodeQL: PASS
• browser integration tests: PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo fmt: PASS (required)
• cargo test: PASS (required)
• cargo test (axum native): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• format-docs: PASS (required)
• format-typescript: PASS (required)
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• prepare integration artifacts: PASS
• vitest: PASS