feat(validation): oneOf near-miss validator hints + issues[].hint on every VALIDATION_ERROR

[bokelley]

Parent: #452

JS source

6.7 commit e7f8e228 (oneOf near-miss validator hint).

Pattern

When validation fails on a discriminated-union shape (e.g., pricing_options submitted with type instead of pricing_model), produce a hint naming the closest matching variant + which discriminator field is wrong.

Adopters hit this 3× before recovering — LLM clients especially. Adding a structured hint field on every validation-error issue lets the client surface it directly.

Proposed shape

Every issue inside a VALIDATION_ERROR envelope gets a hint field:

{
  "code": "VALIDATION_ERROR",
  "issues": [
    {
      "path": "pricing_options[0]",
      "message": "Required field 'pricing_model' missing",
      "hint": "Looks like you may have meant the 'cpm' variant. Use 'pricing_model' instead of 'type' as the discriminator."
    }
  ]
}

Heuristic: when a oneOf/discriminated-union shape fails, find the variant whose required-fields-present count is highest, and emit a hint naming it + which discriminator key the input is using.

Acceptance criteria

• Hints appear on every VALIDATION_ERROR envelope where applicable.
• Specifically tested for the v3 ref seller's pricing_options regression class of bug.
• Hints are optional / additive — clients that ignore them work as before.

[bokelley]

Triage

Classification: Feature request
Bucket(s): validation
Status: drafting-pr
Milestone: omitted (no target version specified)

What the experts said:

• ad-tech-protocol-expert: approved — additive hint field rides on existing additionalProperties: true on issues[]; non-breaking; omit-when-None is correct per AdCP optional-field convention
• code-reviewer: approved — fixed discriminator search to required-fields-only; explicit conditional hint serialization; 8 targeted tests including hostile-key-name sanitization
• security-reviewer: approved — hint built from schema-declared strings only (variant titles, discriminator field names, const values); never echoes user-supplied keys or values; prompt-injection risk neutralized

My take: Clean, self-contained port of JS SDK e7f8e228. All three experts converged on the same implementation constraint (schema-declared strings only in hint text), which the implementation satisfies. PR #468 drafts the change.

Drafting PR: adds hint: str | None to ValidationIssue + _infer_oneof_hint() heuristic + wire serialization in both paths + 8 new tests for the pricing_options regression class.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_0147Kbe9nML1irSFSxMBxtWi

---

Generated by Claude Code