feat(decisioning): state-machine helpers, typed exceptions, ref_account_id

[bokelley]

Closes #455

Adds three sets of additive helpers to adcp.decisioning (Batch 1 item 3 of the JS 6.7 parity epic #452). All additions are non-breaking new exports; no public symbols changed or removed.

(a) State-machine transition helpers (src/adcp/decisioning/transitions.py) — MEDIA_BUY_TRANSITIONS and CREATIVE_TRANSITIONS are dict[Status, set[Status]] maps derived from the spec state-machine diagrams. validate_media_buy_transition / validate_creative_transition accept raw strings or enum members and raise AdcpError(INVALID_REQUEST, recovery="correctable") on disallowed moves or unknown status strings — eliminating the bare ValueError leak that open-coded enum lookups produce. Creative rejected→processing (resubmit) and archived→approved (unarchive) paths are included per creative-status.json enumDescriptions.

(b) Typed AdcpError subclasses (src/adcp/decisioning/exceptions.py) — PermissionDeniedError, AuthRequiredError, ServiceUnavailableError, RateLimitedError, MediaBuyNotFoundError, AccountNotFoundError, BillingNotPermittedForAgentError, RequestValidationError. Each hard-codes the correct wire code and recovery value from enumMetadata in schemas/cache/enums/error-code.json (the spec's authoritative SDK classification block). Named RequestValidationError (not ValidationError) to avoid shadowing pydantic.ValidationError and the existing adcp.validation.legacy.ValidationError.

(c) ref_account_id(ref) -> str | None — extracts account_id from a wire account reference dict, returning None for missing/non-string values. Eliminates ref.get("account_id") if ref else None inline patterns in multi-tenant platform methods.

What was tested

• pytest tests/test_decisioning_transitions_exceptions.py — 56 new tests, all passing
• pytest tests/test_decisioning_types.py tests/test_decisioning_dispatch.py — 57 existing tests, all passing, no regressions
• ruff check — clean on all new files
• mypy src/adcp/decisioning/exceptions.py src/adcp/decisioning/types.py — no issues
• mypy src/adcp/decisioning/transitions.py src/adcp/decisioning/types.py — no issues

Pre-PR review

• code-reviewer: approved after one fix iteration — caught that PERMISSION_DENIED and BILLING_NOT_PERMITTED_FOR_AGENT are correctable per spec enumMetadata (not terminal); both corrected before PR open.
• dx-expert: approved — nits only: (1) quickstart docstring in __init__.py doesn't mention the new helpers (omitted per nit policy); (2) ref_account_id placement in transitions.py rather than a dedicated helpers.py (placement is acceptable given the module docstring already covers "account-reference utilities"; follow-up issue if it creates agent-tax); (3) validate_* functions raise AdcpError(INVALID_REQUEST) not RequestValidationError — correct and intentional, but worth a doc note on the validate functions.

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_01XbBfrSnfmVy6fQtoebgxWJ

---

Generated by Claude Code

[bokelley]

Superseded by #465 (feat(decisioning): state-machine helpers + typed exception classes + ref_account_id), already merged to main. Same three-part scope: transitions, typed exceptions, ref_account_id.

[bokelley]

Acknowledged — noted that this was superseded by #465 (already merged to main). No further action needed on this PR.

---

Generated by Claude Code

---

Generated by Claude Code