Run 3 Print Diagnostics — Byproducts

Summary

The smallest of the three operations runs. Run 2’s refactor of PdfRenderService to renderGroups() collapsed the diagnostic surface from “extend render() plus add a wrapper type” to “add an optional field on the existing per-group result and three query parameters.” The most useful side effect was that Run 4’s API tests could rely on dry-run=true to validate payload shape without provisioning Documint connectivity.

Learnings

Pre-implementation re-planning paid off. The original Run 3 spec assumed Run 2 would leave render() as the public method and add a DiagnosticRenderResult wrapper. Once Run 2 landed renderGroups() + GroupRenderResult, the cleanest approach was to attach debugPayload directly to GroupRenderResult, which is what shipped. See implementation-log § Run 3 pre-implementation adjustments.
dry-run as a test enabler. The dry-run mode was specified for support diagnostics, but its biggest immediate benefit was Phase 4 tests: the team could assert on the Documint payload contents without standing up Documint in the local environment.
Parameter precedence needs to be explicit in OpenAPI. Without an explicit description, callers reading the generated docs cannot tell whether debug=true and dry-run=true together short-circuits Documint or not. The endpoint route descriptions were extended to spell this out.

Alternatives considered

DiagnosticRenderResult wrapper type — rejected after Run 2 made it unnecessary. See implementation-log § Run 3 pre-implementation adjustments.
Header-based diagnostic flags (e.g., X-Arda-Print-Debug: true) — considered briefly during planning, rejected because Bruno and curl are friendlier with query params and because the existing live-print parameter set the precedent.
Returning the payload as a stringified JSON field — rejected; JsonElement round-trips through serialisation cleanly and lets the test layer assert on structure rather than text.
Recording dry-run requests as no-op print events so support could see “this user attempted a dry-run at 14:03” — rejected. Side-effect-free is the contract; auditing dry-runs would require its own decision and persistence layer.

Suggestions / follow-ups

Per-tenant audit logging for debug=true calls. A support engineer running debug=true against a customer tenant exposes the constructed payload (which can include item names, notes, and locator data) to whoever can read the response body. A log line per debug call would aid forensics. Not in scope.
Schema for debugPayload. Today it’s an opaque JsonElement; a DocumintPayload data class with field validation would make the response self-describing. Out of scope per the “minimum to satisfy support” framing of SAC::PRINT-DX.
Frontend exposure of diagnostic mode. Currently support staff invoke these via API tools (Bruno, curl) — there is no UI affordance. Intentional, but worth revisiting when the Customer Support persona (DQ-010) grows tooling.

Skipped

Print history API (#792 Option 1). Per DQ-011, deferred to a future project. Run 3 implements only #792 Option 2 (debug + dry-run flags).
Frontend support UI for dry-run / debug. Not requested by tickets; support persona uses API tools today.

Specification delta (post)

Differences between phase-3-diagnostics/specification.md and what shipped:

debugPayload field placement. The specification described a DiagnosticRenderResult wrapper; the implementation places debugPayload: JsonElement? directly on GroupRenderResult. Functionally equivalent for callers, structurally simpler.
No new public method on PdfRenderService. The spec implied an extension to render(); in practice the diagnostic flags are parameters on renderGroups() only.

No other deltas.