fix(types): PostalArea TypeAdapter output is not round-trippable

[bokelley]

Version

adcp==8.0.0b9

Reproduction

from adcp.types import PostalArea
from pydantic import TypeAdapter

adapter = TypeAdapter(PostalArea)
value = adapter.validate_python({"system": "us_zip", "values": ["10001"]})
wire = adapter.dump_python(value, mode="json")
print(wire)
adapter.validate_python(wire)

The dump is:

{"country": "US", "system": "us_zip", "values": ["10001"]}

Re-validating that output fails because country US expects native systems zip or zip_plus_four, while the parsed legacy arm retained us_zip.

This also breaks ordinary Pydantic model dump/reconstruct cycles for TargetingOverlay.geo_postal_areas and geo_postal_areas_exclude.

Expected

TypeAdapter(PostalArea) output should validate through the same adapter. Either the legacy fused system should remain countryless on serialization, or it should normalize to the matching native system when adding country.

Context

This surfaced while applying the beta.9 object-union migration from #1084.

[bokelley]

Triage

Classification: Bug
Bucket(s): validation, client (neither label exists in the repo — noted in run summary)
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Union arm order is inverted — PostalArea2 | PostalArea1 is the correct fix; PostalArea2.extra='forbid' plus the absence of a country field guarantees native inputs fall through cleanly. Also confirmed the upstream schema emits a global-superset System enum per arm (legacy fused tokens included), making _validate_country_system_pairing the necessary compensating control; that schema defect is a separate upstream issue.
• code-reviewer: Confirmed mis-routing via PostalArea112's country: Literal['US'] = 'US' default swallowing the legacy input. Additionally flagged that the same arm-ordering bug exists in the generated postal_area.PostalArea RootModel (line 418), which is what TargetingOverlay.geo_postal_areas / geo_postal_areas_exclude actually use — the aliases.py fix does not cover that path. Also identified a missing raw-dict test case (existing test uses model-instance path, not TypeAdapter(PostalArea).validate_python(dict)).

My take: Two-site fix required — one line in aliases.py (non-generated, safe to edit directly) and a post-generate step for the generated PostalArea RootModel. Both experts converge; the change is non-breaking because it corrects a mis-routing that causes a broken serialization, not a deliberate behavior change.

Implementation scope:

• src/adcp/types/aliases.py:597 — Change PostalArea1 | PostalArea2 → PostalArea2 | PostalArea1. The safety guarantee: PostalArea2.extra='forbid' + no country field means any native input (with country) is immediately rejected by the legacy arm and falls through to PostalArea1. Legacy inputs (with a CountryFusedPostalCodeSystem token and no country) now route to PostalArea2 first, serialize without injecting a country default, and round-trip cleanly.
• scripts/post_generate_fixes.py (or nearest equivalent) — Apply the same arm-order swap to PostalArea at postal_area.py:418 post-generation, since TargetingOverlay.geo_postal_areas and geo_postal_areas_exclude use the generated class, not the alias. Do not hand-edit generated_poc/.
• tests/test_postal_area_compat.py — Add a raw-dict round-trip test: TypeAdapter(PostalArea).validate_python({"system": "us_zip", "values": ["10001"]}) → dump should contain no country key and re-validate through the same adapter without error.
• Changelog note: serialized form of legacy inputs changes (no longer injects country); callers comparing against the buggy {"country": "US", "system": "us_zip", ...} dump need updating.
• Required checks: pytest tests/test_postal_area_compat.py -v, mypy src/adcp/types/aliases.py, ruff check .

---

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

---

Generated by Claude Code