Sync canonical schemas post-3.0.2-beta.0: aliases.py drift on 38 *1 codegen artifacts

[bokelley]

Context

Upstream adcontextprotocol/adcp shipped two refactors that the Python SDK hasn't synced yet:

1. adcp#3459 (asset-union refactor, 3.0.2-beta.0) — promoted the inline asset-variant oneOf to canonical core/assets/asset-union.json. This eliminates the *Asset1 codegen artifacts that json-schema-to-typescript (and our datamodel-code-generator) were emitting from inline duplication.
2. adcp#3493 (version-negotiation, merged 2026-04-29) — adds adcp_version (release-precision string) to every request/response schema via allOf composition against core/version-envelope.json, deprecates adcp_major_version (integer).

When python scripts/sync_schemas.py is run against latest.tgz and types are regenerated, src/adcp/types/aliases.py fails to import because 38 *1 discriminator artifacts no longer exist:

• 4 asset-union artifacts (DaastAsset1, VastAsset1, etc.) — eliminated by #3459.
• 34 oneOf-response-discriminator artifacts (AcquireRightsResponse1, SyncCreativesResponse1, etc.) — likely affected by the schema layout change but root cause not yet investigated.

Repro

mv src/adcp/ADCP_VERSION src/adcp/ADCP_VERSION.bak
python scripts/sync_schemas.py --no-skills      # falls back to latest.tgz
python scripts/generate_types.py                 # ImportError on AcquireRightsResponse1
mv src/adcp/ADCP_VERSION.bak src/adcp/ADCP_VERSION

Full list of broken aliases

AccountReference1, AcquireRightsResponse1, ActivateSignalResponse1, ActivationKey1,
Assets1, AuthorizedAgents1, BuildCreativeResponse1, CalibrateContentResponse1,
CatalogFieldBinding1, ComplyTestControllerResponse1, CreateContentStandardsResponse1,
CreateMediaBuyResponse1, DaastAsset1, Deployment1, Destination1, Field1,
GetAccountFinancialsResponse1, GetBrandIdentityResponse1, GetContentStandardsResponse1,
GetCreativeFeaturesResponse1, GetMediaBuyArtifactsResponse1, GetRightsResponse1,
ListContentStandardsResponse1, LogEventResponse1, PreviewCreativeResponse1,
PreviewRender1, ProvidePerformanceFeedbackResponse1, PublisherPropertySelector1,
Response1, SyncAccountsResponse1, SyncAudiencesResponse1, SyncCatalogsResponse1,
SyncCreativesResponse1, SyncEventSourcesResponse1, UpdateContentStandardsResponse1,
UpdateMediaBuyResponse1, ValidateContentDeliveryResponse1, VastAsset1

Suggested fix path

Each old *1 name maps to either:

• A new canonical type (e.g. VastAsset1 → AssetUnion member, or kept as inner type via the new core/assets/asset-union.json $ref).
• A renamed branch of a discriminated oneOf (e.g. AcquireRightsResponse1 → likely AcquireRightsAcquiredResponse or similar named branch).

Concrete steps:

1. Sync schemas (scripts/sync_schemas.py against latest.tgz or 3.0.2-beta.0+).
2. Run scripts/generate_types.py and inspect src/adcp/types/_generated.py for the new exported names.
3. Map each broken alias in src/adcp/types/aliases.py to its new canonical name. Use git-blame on the original alias additions to recover semantic intent for the discriminated branches.
4. Update tests that may depend on the old names.
5. Bump src/adcp/ADCP_VERSION to the synced version once stable.

Why this is its own PR

This is independent of the version-negotiation work (PR #294) and shouldn't bundle with it. The aliases drift affects every consumer using union types from the public surface; needs careful review and probably a CHANGELOG entry for the rename.

Cross-refs

• Protocol issue: json-schema-to-typescript emits Foo+Foo1 for inline asset variants referenced from multiple parents adcp#3459 (still OPEN; tracks the schema-side fix)
• Already shipped upstream: spec(versioning): release-precision protocol version negotiation adcp#3493 (version-negotiation), 3.0.2-beta.0 (asset-union)
• PR feat(sdk): per-instance adcp_version pin + wire emission (Stage 2 + 3a) #294 (this SDK, bokelley/port-pr-1044) intentionally does NOT include the schema sync to keep the version-negotiation work scoped.

[bokelley]

Triage

Classification: Bug
Bucket(s): client (types — aliases.py); validation (schema sync) — note: neither bucket label exists in this repo; flagging for label gap in run summary
Status: ready-for-human

What the experts said:

• code-reviewer: Non-breaking for standard consumers (semantic names in __all__ unchanged); semantic-mapping risk is real — a wrong ordinal assignment silently swaps variant meaning (e.g., AcquireRightsAcquiredResponse ↔ AcquireRightsPendingResponse); flag since datamodel-code-generator is unavailable in triage and 34/38 aliases are uninvestigated.
• ad-tech-protocol-expert: allOf composition in adcp#3493 (version-envelope.json) on response schemas is the likely root cause of 34 renumbered discriminators; adcp#3459 asset-union artifacts may not yet be present in the 3.0.2-beta.0 CDN bundle; two open questions before safe execution: (a) does adcp#3493 apply allOf to response schemas, or only requests? (b) is core/assets/asset-union.json resolvable from the published tarball?

My take: The fix is architecturally clean — the semantic public API (AcquireRightsAcquiredResponse, UrlVastAsset, etc.) stays unchanged; only the internal *1 bridge names inside aliases.py need remapping. Correct remapping requires verifying each new class's discriminator literal (status: Literal["acquired"]) against its semantic alias, which requires running sync_schemas.py + generate_types.py and diff-reading the output. That tooling is not available in this triage environment. @bokelley is best positioned to execute: run the two scripts on a branch, diff _generated.py, remap each alias by checking the discriminator value, then confirm with pytest tests/test_discriminated_unions.py tests/test_asset_aliases_stable.py.

---

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

---

Generated by Claude Code

[bokelley]

/triage execute

[bokelley]

Triage

Classification: bug
Bucket(s): client
Status: ready-for-human

What the experts said:

• code-reviewer: non-breaking (public semantic aliases are stable); however tests/test_type_aliases.py lines 29–36 and 213–233 also hardcode *1/*2 internal names from _generated and will fail at import — fix scope extends beyond aliases.py to those tests. Also flagged that the Assets81–Assets106 block in aliases.py likely renumbers too (adcp#3459 reshuffles $defs ordering in core/format.json).
• dx-expert: alias layer design is sound — zero user-facing change; gap is that there's no make check-aliases target to detect which aliases broke after codegen, making future drift silent until pytest fails.

My take: Two hard blockers prevent execution in this environment: (1) scripts/sync_schemas.py returns 403 (no outbound network), so the 3.0.2-beta.0 bundle cannot be fetched and generate_types.py cannot run; (2) root causes for 34/38 type renames are explicitly "not yet investigated" — without seeing the new generated names, any alias rewire is speculative and likely wrong.

To unblock @bokelley:

1. On a machine with access: python scripts/sync_schemas.py --no-skills && python scripts/generate_types.py
2. Grep the new _generated.py for candidates replacing each broken *1 name (discriminator-field literal is the reliable key).
3. Rewire aliases.py + update tests/test_type_aliases.py lines 29–36 and 213–233 (old is VastAsset1 identity checks → discriminator-value checks, same pattern as test_asset_aliases_stable.py).
4. Re-comment /triage execute — the bot can write the rewire once the new names are known.

---

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

---

Generated by Claude Code

[bokelley]

Hands-on findings — defer until 3.0.2 stabilizes

Picked this up after triage hit the network blocker. Ran the repro locally:

```
echo latest > src/adcp/ADCP_VERSION
python scripts/sync_schemas.py --no-skills # ✓ fetches latest.tgz
python scripts/generate_types.py # ✗ TypeError
```

The runtime failure surfaces before we even see the *1 alias drift this issue documents:

```
TypeError: Value 'reuse' for discriminator 'selection_type' mapped to multiple choices
```

A Pydantic discriminator collision in the regenerated types — `selection_type: "reuse"` is duplicated across two schema branches in the dev snapshot. That's a separate, fresher breakage on top of the 38 alias renames this issue tracks.

Why I'm not fixing it now:

1. `3.0.2-beta.0.tgz` is a 404 (the upstream release isn't published as a pinned tag yet — only `latest.tgz` is fetchable, and that's a moving dev snapshot).
2. The bundle keeps moving — today's `latest` has the `selection_type` collision; yesterday's didn't have it (per issue body); tomorrow's may have something else again. Wiring up aliases against it now is wasted effort.
3. The Python SDK is pinned to 3.0.1 and stable; nothing's broken on `main`.

Reopen condition: when AdCP cuts a stable `3.0.2` (or `3.0.2-rc.N`) tag with a frozen tarball, the alias-rewire work becomes worth doing. By then the discriminator collision will either be resolved upstream or the SDK will need its own override.

Reverted local changes, no commits. Marking as deferred-upstream.

[bokelley]

Triage update

Classification: Bug
Bucket(s): client
Status: deferred

@bokelley's hands-on findings settle this: 3.0.2-beta.0.tgz is a 404, latest.tgz introduces a selection_type: "reuse" Pydantic discriminator collision that breaks generate_types.py before alias rewiring is even reachable, and the bundle is a moving dev snapshot. Wiring aliases against it now is wasted effort — main is stable on 3.0.1 and nothing is broken there.

Reopen condition: upstream cuts a stable 3.0.2 (or 3.0.2-rc.N) tag with a frozen tarball and generate_types.py completes without collision.

Label gap: deferred-upstream not found in this repo — no label created. Flagging for maintainer if the label is wanted.

---

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

---

Generated by Claude Code