fix: flatten validation-only oneOf schemas to single subclassable classes

Follow-up to adcontextprotocol#156. The previous fix unwrapped RootModel unions to Union
type aliases, but Union aliases are also non-subclassable — consumers
that do `class MyType(LibraryType)` still break.

Root cause: JSON Schema uses anyOf/oneOf with required-only branches to
express "at least one of these fields must be set." datamodel-code-generator
misinterprets this as a type union, generating separate variant classes
(e.g., FrequencyCap1/2/3) plus a RootModel wrapper. Neither RootModels
nor Union type aliases can be subclassed by consumers.

Fix: Added flatten_validation_oneof() to generate_types.py that detects
required-only anyOf/oneOf patterns in schemas and removes them before
code generation. This produces a single BaseModel class per type —
restoring the v3.6 API surface where all types were subclassable.

10 types flattened:
- FrequencyCap, UserMatch, AudienceMember, Catchment (value types)
- GetSignalsRequest, UpdateMediaBuyRequest, GetCreativeDeliveryRequest,
  ProvidePerformanceFeedbackRequest, SiSendMessageRequest,
  PackageUpdate (request types)

Also adds a consumer subclassability contract test that guards 27
consumer-facing types against becoming non-subclassable in future
schema updates.

Author: KonstantinMirin

scripts/generate_ergonomic_coercion.py

@@ -50,8 +50,7 @@
     ("GetProductsRequest1", "media_buy.get_products_request"),
     ("GetProductsRequest2", "media_buy.get_products_request"),
     ("GetProductsRequest3", "media_buy.get_products_request"),
-    ("PackageUpdate1", "media_buy.package_update"),
-    ("PackageUpdate2", "media_buy.package_update"),
+    ("PackageUpdate", "media_buy.package_update"),
 ]
 
 # Types that should get subclass_list coercion (for list variance)
@@ -234,7 +233,7 @@ def generate_code() -> str:
     from adcp.types.generated_poc.media_buy.list_creatives_request import ListCreativesRequest, Sort
     from adcp.types.generated_poc.media_buy.list_creatives_response import ListCreativesResponse
     from adcp.types.generated_poc.media_buy.package_request import PackageRequest
-    from adcp.types.generated_poc.media_buy.package_update import PackageUpdate1, PackageUpdate2
+    from adcp.types.generated_poc.media_buy.package_update import PackageUpdate
 
     # Map names to classes
     request_classes = {
@@ -257,8 +256,7 @@ def generate_code() -> str:
         "GetProductsRequest1": GetProductsRequest1,
         "GetProductsRequest2": GetProductsRequest2,
         "GetProductsRequest3": GetProductsRequest3,
-        "PackageUpdate1": PackageUpdate1,
-        "PackageUpdate2": PackageUpdate2,
+        "PackageUpdate": PackageUpdate,
     }
 
     # Analyze all types
@@ -377,10 +375,7 @@ def generate_code() -> str:
     lines.append("    Sort,")
     lines.append(")")
     lines.append("from adcp.types.generated_poc.media_buy.package_request import PackageRequest")
-    lines.append("from adcp.types.generated_poc.media_buy.package_update import (")
-    lines.append("    PackageUpdate1,")
-    lines.append("    PackageUpdate2,")
-    lines.append(")")
+    lines.append("from adcp.types.generated_poc.media_buy.package_update import PackageUpdate")
 
     # Add response type imports
     lines.append("from adcp.types.generated_poc.media_buy.create_media_buy_response import (")
@@ -424,8 +419,7 @@ def generate_code() -> str:
         "GetProductsRequest3",
         "PackageRequest",
         "CreateMediaBuyRequest",
-        "PackageUpdate1",
-        "PackageUpdate2",
+        "PackageUpdate",
         # Response types
         "GetProductsResponse",
         "ListCreativesResponse",
@@ -518,8 +512,7 @@ def generate_code() -> str:
         lines.append(f"    {type_name}.model_rebuild(force=True)")
         lines.append("")
 
-    # Handle PackageUpdate1 and PackageUpdate2 together if they have same coercions
-    # (they're already handled in the loop above)
+    # PackageUpdate is now a single class (flattened from validation-only oneOf)
 
     # Add helper function
     lines.append("")

scripts/generate_types.py

@@ -70,6 +70,63 @@ def rewrite_refs(obj, current_schema_rel_path: Path):
     return obj
 
 
+def flatten_validation_oneof(schema: dict) -> dict:
+    """Flatten anyOf/oneOf that only express required-field constraints.
+
+    JSON Schema uses anyOf/oneOf with required-only branches to express
+    "at least one of these field groups must be set." datamodel-code-generator
+    misinterprets this as a type union, generating separate variant classes
+    (e.g., FrequencyCap1, FrequencyCap2, FrequencyCap3) plus a RootModel wrapper.
+
+    This function detects the pattern and removes the anyOf/oneOf, keeping
+    only the intersection of required fields so a single class is generated.
+
+    Follow-up to #155: enables consumer subclassing without RootModel or
+    Union type alias barriers.
+    """
+    if "properties" not in schema:
+        return schema
+
+    branch_key = None
+    branches = None
+    for key in ("anyOf", "oneOf"):
+        if key in schema:
+            branch_key = key
+            branches = schema[key]
+            break
+
+    if not branches:
+        return schema
+
+    # All branches must contain only 'required' (and optionally 'not')
+    if not all(set(b.keys()) <= {"required", "not"} for b in branches):
+        return schema
+
+    # All branches are required-only — this is a validation constraint, not a type union
+    # Compute the intersection of required fields (fields required in ALL branches)
+    branch_required = [set(b.get("required", [])) for b in branches]
+    always_required = set.intersection(*branch_required) if branch_required else set()
+
+    # Include any top-level required fields
+    top_required = set(schema.get("required", []))
+    always_required |= top_required
+
+    title = schema.get("title", "unknown")
+    branch_count = len(branches)
+
+    # Remove the anyOf/oneOf
+    del schema[branch_key]
+
+    # Set required to the intersection (or remove if empty)
+    if always_required:
+        schema["required"] = sorted(always_required)
+    elif "required" in schema:
+        del schema["required"]
+
+    print(f"    flattened {branch_key} ({branch_count} branches) in {title}")
+    return schema
+
+
 def flatten_schemas():
     """
     Copy schemas to temp directory, preserving directory structure.
@@ -113,6 +170,9 @@ def flatten_schemas():
         # Rewrite $ref paths: convert absolute paths to relative, hyphens to underscores
         schema = rewrite_refs(schema, rel_path)
 
+        # Flatten validation-only anyOf/oneOf into single-class schemas
+        schema = flatten_validation_oneof(schema)
+
         with open(output_file, "w") as f:
             json.dump(schema, f, indent=2)
 
@@ -361,6 +421,16 @@ def main():
         restore_unchanged_files()
 
         # Generate ergonomic coercion module (type coercion for better API ergonomics)
+        # Reset _ergonomic.py first — the old version may import variant classes
+        # that no longer exist after schema flattening (e.g., PackageUpdate1).
+        ergonomic_file = REPO_ROOT / "src" / "adcp" / "types" / "_ergonomic.py"
+        if ergonomic_file.exists():
+            ergonomic_file.write_text(
+                '"""Auto-generated ergonomic coercion — regenerating..."""\n'
+                "\ndef apply_ergonomic_coercion() -> None:\n"
+                "    pass\n"
+            )
+
         ergonomic_script = REPO_ROOT / "scripts" / "generate_ergonomic_coercion.py"
         if ergonomic_script.exists():
             print("\nGenerating ergonomic coercion module...")

scripts/post_generate_fixes.py

@@ -298,10 +298,13 @@ def fix_constr_type_annotations():
 
 
 # Types to unwrap from RootModel to Union type alias.
-# ALL Request/Response types are unwrapped so consumers can subclass them
-# with model_config overrides (extra='forbid', custom validators, etc.).
-# Value-type RootModels (PricingOption, Destination, etc.) keep the RootModel
-# wrapper + __getattr__ proxy since nobody subclasses them.
+# Only genuine discriminated unions (different field shapes per variant) belong here.
+# "Validation-only" oneOf types (same fields, different required combos) are now
+# handled at the schema level by flatten_validation_oneof() in generate_types.py,
+# which produces a single BaseModel class — no RootModel or unwrapping needed.
+# Removed from this set (now single classes): GetCreativeDeliveryRequest,
+# GetSignalsRequest, ProvidePerformanceFeedbackRequest, SiSendMessageRequest,
+# UpdateMediaBuyRequest.
 # See: https://github.com/adcontextprotocol/adcp-client-python/issues/155
 _UNWRAP_TO_UNION: set[str] = {
     "ActivateSignalResponse",
@@ -311,25 +314,20 @@ def fix_constr_type_annotations():
     "CreateMediaBuyResponse",
     "GetAccountFinancialsResponse",
     "GetContentStandardsResponse",
-    "GetCreativeDeliveryRequest",
     "GetCreativeFeaturesResponse",
     "GetMediaBuyArtifactsResponse",
     "GetProductsRequest",
-    "GetSignalsRequest",
     "ListContentStandardsResponse",
     "LogEventResponse",
     "PreviewCreativeRequest",
     "PreviewCreativeResponse",
-    "ProvidePerformanceFeedbackRequest",
     "ProvidePerformanceFeedbackResponse",
-    "SiSendMessageRequest",
     "SyncAccountsResponse",
     "SyncAudiencesResponse",
     "SyncCatalogsResponse",
     "SyncCreativesResponse",
     "SyncEventSourcesResponse",
     "UpdateContentStandardsResponse",
-    "UpdateMediaBuyRequest",
     "UpdateMediaBuyResponse",
     "ValidateContentDeliveryResponse",
 }

src/adcp/types/__init__.py

@@ -184,6 +184,7 @@
     GetProductsResponse,
     GetPropertyListRequest,
     GetPropertyListResponse,
+    GetSignalsRequest,
     GetSignalsResponse,
     Gtin,
     HtmlAsset,
@@ -398,7 +399,6 @@
     GetProductsWholesaleRequest,
     GetSignalsDiscoveryRequest,
     GetSignalsLookupRequest,
-    GetSignalsRequest,
     HtmlPreviewRender,
     InlineDaastAsset,
     InlineVastAsset,

src/adcp/types/_ergonomic.py

@@ -75,10 +75,7 @@
     Sort,
 )
 from adcp.types.generated_poc.media_buy.package_request import PackageRequest
-from adcp.types.generated_poc.media_buy.package_update import (
-    PackageUpdate1,
-    PackageUpdate2,
-)
+from adcp.types.generated_poc.media_buy.package_update import PackageUpdate
 from adcp.types.generated_poc.media_buy.create_media_buy_response import (
     CreateMediaBuyResponse1,
 )
@@ -317,71 +314,38 @@ def _apply_coercion() -> None:
     )
     CreateMediaBuyRequest.model_rebuild(force=True)
 
-    # Apply coercion to PackageUpdate1
-    # - creative_assignments: list[CreativeAssignment] (accepts subclass instances)
-    # - creatives: list[CreativeAsset] (accepts subclass instances)
-    # - ext: ExtensionObject | dict | None
-    # - pacing: Pacing | str | None
-    _patch_field_annotation(
-        PackageUpdate1,
-        "creative_assignments",
-        Annotated[
-            list[CreativeAssignment] | None,
-            BeforeValidator(coerce_subclass_list(CreativeAssignment)),
-        ],
-    )
-    _patch_field_annotation(
-        PackageUpdate1,
-        "creatives",
-        Annotated[
-            list[CreativeAsset] | None,
-            BeforeValidator(coerce_subclass_list(CreativeAsset)),
-        ],
-    )
-    _patch_field_annotation(
-        PackageUpdate1,
-        "ext",
-        Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
-    )
-    _patch_field_annotation(
-        PackageUpdate1,
-        "pacing",
-        Annotated[Pacing | None, BeforeValidator(coerce_to_enum(Pacing))],
-    )
-    PackageUpdate1.model_rebuild(force=True)
-
-    # Apply coercion to PackageUpdate2
+    # Apply coercion to PackageUpdate
     # - creative_assignments: list[CreativeAssignment] (accepts subclass instances)
     # - creatives: list[CreativeAsset] (accepts subclass instances)
     # - ext: ExtensionObject | dict | None
     # - pacing: Pacing | str | None
     _patch_field_annotation(
-        PackageUpdate2,
+        PackageUpdate,
         "creative_assignments",
         Annotated[
             list[CreativeAssignment] | None,
             BeforeValidator(coerce_subclass_list(CreativeAssignment)),
         ],
     )
     _patch_field_annotation(
-        PackageUpdate2,
+        PackageUpdate,
         "creatives",
         Annotated[
             list[CreativeAsset] | None,
             BeforeValidator(coerce_subclass_list(CreativeAsset)),
         ],
     )
     _patch_field_annotation(
-        PackageUpdate2,
+        PackageUpdate,
         "ext",
         Annotated[ExtensionObject | None, BeforeValidator(coerce_to_model(ExtensionObject))],
     )
     _patch_field_annotation(
-        PackageUpdate2,
+        PackageUpdate,
         "pacing",
         Annotated[Pacing | None, BeforeValidator(coerce_to_enum(Pacing))],
     )
-    PackageUpdate2.model_rebuild(force=True)
+    PackageUpdate.model_rebuild(force=True)
 
     # Apply coercion to GetProductsResponse
     # - context: ContextObject | dict | None