feat(validation): oneOf near-miss hints on VALIDATION_ERROR issues

[bokelley]

Closes #460

Ports the JS SDK e7f8e228 oneOf near-miss hint feature to Python. When a oneOf/discriminated-union check fails (e.g., pricing_options[0] submitted with type instead of pricing_model), an optional hint field now appears on the failing issue in the VALIDATION_ERROR envelope, naming the closest-matching variant and its required discriminator field. Hint text is built exclusively from schema-declared strings — variant titles, discriminator field names, and const values — so it never echoes user-supplied keys or values into logs or LLM contexts. Clients that ignore the field are unaffected.

Changes:

• src/adcp/validation/schema_validator.py: adds hint: str | None = None to ValidationIssue; adds _infer_oneof_hint() (scores each branch by required-field-presence count, extracts discriminator from required const properties, caps at 20 branches); updates _format_error() to call it; updates SchemaValidationError.details serialization to include hint when present
• src/adcp/validation/schema_errors.py: updates build_adcp_validation_error_payload to include hint when present (omits the key when None, consistent with all other optional fields in AdCP error objects)
• tests/test_schema_validation.py: 8 new tests in TestOneOfNearMissHints covering the pricing_options regression class, no-hint on non-oneOf failures, hostile key-name sanitization, and wire serialization in both paths

What was tested:

• pytest tests/test_schema_validation.py — 32 passed (24 existing + 8 new)
• mypy src/adcp/validation/ — no errors in changed files (pre-existing errors in other modules unrelated to this change)
• ruff check src/adcp/validation/ — all checks passed

Pre-PR review:

• code-reviewer: approved — fixed discriminator search restricted to required fields; explicit if i.hint is not None serialization avoids falsy-filter concern; no blockers remain
• ad-tech-protocol-expert: approved — additive field on additionalProperties: true issues array is non-breaking; omit-when-None is correct per AdCP optional-field convention; nit: a future validation-issue.json schema type would make hint spec-visible (pre-existing gap, out of scope for this PR)

Nits noted (not fixed):

• Future: add validation-issue.json schema type to make hint discoverable from the spec (protocol expert nit, pre-existing schema gap)
• Future: verify hint text format matches JS SDK e7f8e228 output exactly (protocol expert nit)
• _MAX_ONEOF_BRANCHES = 20 cap not directly tested

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_0147Kbe9nML1irSFSxMBxtWi

---

Generated by Claude Code

[bokelley]

Superseded by #476 (feat(validation): oneOf near-miss validator hints + issues[].hint on every VALIDATION_ERROR), already merged to main.

[bokelley]

Acknowledged — superseded by #476 (merged). No further action on this PR.

---

Generated by Claude Code