refactor: remove direct generated_poc imports

CLAUDE.md

@@ -17,31 +17,84 @@ FormatId = str
 PackageRequest = dict[str, Any]
 ```
 
-**Stable Public API Layer**
+**Stable Public API Layer - Import Architecture**
 
-**CRITICAL**: The `generated_poc` directory is internal implementation. **Never import directly from it**.
+**CRITICAL**: Both `generated_poc/` and `_generated.py` are internal implementation. Source code must ONLY import from `stable.py` or `aliases.py`.
 
-Generated types in `src/adcp/types/generated_poc/` may have:
-- Numbered suffixes (e.g., `BrandManifest1`, `BrandManifest2`) due to schema evolution
-- Structural changes between minor versions
-- Files added/removed as schemas evolve
+### Import Architecture
 
-**Always use the stable API:**
+The type system has a strict layering to prevent brittleness:
+
+```
+generated_poc/*.py (internal, auto-generated from schemas)
+    ↓
+_generated.py (internal consolidation, handles name collisions)
+    ↓
+stable.py (public API for base types) + aliases.py (public API for discriminated unions)
+    ↓
+__init__.py (user-facing exports)
+```
+
+### Import Rules for Source Code
+
+**✅ CORRECT - Public API only:**
+```python
+# For base types (requests, responses, domain models)
+from adcp.types.stable import (
+    GetProductsRequest,
+    GetProductsResponse,
+    Product,
+    Package,
+    BrandManifest,
+)
+
+# For semantic aliases (discriminated unions)
+from adcp.types.aliases import (
+    CreateMediaBuySuccessResponse,
+    CreateMediaBuyErrorResponse,
+    PreviewCreativeFormatRequest,
+)
+
+# Or from main package
+from adcp import Product, CreateMediaBuySuccessResponse
+```
+
+**❌ WRONG - Internal implementation (brittle):**
 ```python
-# ✅ CORRECT - Stable public API
-from adcp.types import BrandManifest, Product, CpmFixedRatePricingOption
-from adcp.types.stable import BrandManifest, Product
+# Never import from _generated - it's internal consolidation
+from adcp.types._generated import GetProductsRequest
 
-# ❌ WRONG - Internal generated types (will break)
-from adcp.types.generated_poc.brand_manifest import BrandManifest1
-from adcp.types._generated import BrandManifest1
+# Never import from generated_poc - it's internal generated code
+from adcp.types.generated_poc.product import Product
+
+# Never import numbered types directly - use semantic aliases
+from adcp.types._generated import CreateMediaBuyResponse1
 ```
 
-The stable API (`src/adcp/types/stable.py`) provides:
-1. **Clean names** - `BrandManifest` not `BrandManifest1`
-2. **Stability** - Aliases are updated when schemas evolve
-3. **Versioning** - Breaking changes require major version bumps
-4. **Deprecation warnings** - Direct `generated_poc` imports trigger warnings
+### Why This Matters
+
+1. **`generated_poc/`** may have:
+   - Numbered suffixes (e.g., `Response1`, `Response2`)
+   - Files added/removed as schemas evolve
+   - Name collisions between modules
+
+2. **`_generated.py`** may have:
+   - Collision-resolution qualifiers (e.g., `_PackageFromPackage`)
+   - Internal consolidation logic
+   - Changes when collision handling evolves
+
+3. **`stable.py` and `aliases.py`** provide:
+   - Clean, semantic names
+   - Stability guarantees within major versions
+   - Explicit public API
+
+### Special Cases
+
+**Only `stable.py` and `aliases.py` may import from `_generated.py`:**
+- `stable.py`: Imports base types and re-exports with clean names
+- `aliases.py`: Imports numbered discriminated union types and creates semantic aliases
+
+**All other source files must import from `stable.py` or `aliases.py`.**
 
 **NEVER Modify Generated Files Directly**
 

schemas/cache/.hashes.json

@@ -1,6 +1,6 @@
 {
-  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/index.json": "eed524f6ca3b7b8981035a74f3eaf339da6fadab85e4af9196c1c7c4d5150095",
-  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/adagents.json": "bd0e7cd9189b191d827a3ab7fb9d4f9ef4913377c816c5aa27af30bfd20d3451",
+  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/index.json": "46f68f0e55d63361c0eda1cc7ffff4f25c9416467dd3a04db2cca0973f086b7d",
+  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/adagents.json": "f32e3778a454b7ae65f42952906f06466008bfd1208b83729e14d5f2164902d5",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/activation-key.json": "bb9c20c6200b651ce6db89f7160be60b9845dbbb4390a13363ea5b82c1c3c786",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/asset-type.json": "a61ac8e14a61adef64d10d6ab39c204d703c087f29efa45c69c527988c93cd3d",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/assets/audio-asset.json": "e25d688d22c8b130d9d1a2a09f9aa462cb7a5c83db6eea6f328cd937f8625a3f",
@@ -34,11 +34,12 @@
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/performance-feedback.json": "80384474042b6cda08b1128859143ec5822d6dcc907ba1fa3ecf81719e7644a7",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/placement.json": "ea814df6d878232bfdb1249fe199a1e32ec18598b7d3e3c57324d6e6120d9cf8",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/pricing-option.json": "cfaeff3d4fc49e0d3ae76364e246b3b7a772ef12cbda65b1cff400ab1f841bfa",
-  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/product.json": "f3ef04e850cb61c2ba86e05da1d5a352b63031ddbb42fbdffbbbd6c8432ad5c5",
+  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/product.json": "e1b4faa9029bd06baa537fbf534993e7830b1bdc2241279dea4806c134cea50d",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/promoted-offerings.json": "d8b4b92db0e2debc5c0ddbc0a8ff673f258f0bbc0348737df61be20a25827077",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/promoted-products.json": "77773b1dce91b219ec5043c091eb2977a82ba301e03aead3868ba704e625379e",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/property.json": "510458c96a93deb90d9fa3a4dfc11b63c113755dbec3de386690f6838213bc84",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/protocol-envelope.json": "c6096b4ed4330c5e2045989bfd5cdc64fa6587cf8b0d1d2c19e33c7434cdacb8",
+  "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/publisher-property-selector.json": "3e4870d0446a5825c16365a99d49932517223c1d9d3d46a4fbf413d377ed43dd",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/push-notification-config.json": "be2af5dbf7d398c958e59c70ab61a845e4a7d1f1e076412589d06d53454b64b0",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/reporting-capabilities.json": "c463c8d512c17b8ac7afde34d782b5e5f700ed9cf73a52992a328f85ad24d568",
   "https://raw.githubusercontent.com/adcontextprotocol/adcp/main/static/schemas/v1/core/response.json": "0ac624a30da08e1aa90d2a9379f8c1ed29b704c3f5399224b9684672d3df9723",

schemas/cache/1.0.0/adagents.json

@@ -318,7 +318,7 @@
               "properties": {
                 "description": "Specific properties this agent is authorized for (alternative to property_ids/property_tags)",
                 "items": {
-                  "$ref": "property.json"
+                  "$ref": "/schemas/v1/core/property.json"
                 },
                 "minItems": 1,
                 "type": "array"
@@ -354,68 +354,7 @@
               "publisher_properties": {
                 "description": "Properties from other publisher domains this agent is authorized for. Each entry specifies a publisher domain and which of their properties this agent can sell",
                 "items": {
-                  "oneOf": [
-                    {
-                      "additionalProperties": false,
-                      "properties": {
-                        "property_ids": {
-                          "description": "Specific property IDs from the publisher's adagents.json properties array",
-                          "items": {
-                            "pattern": "^[a-z0-9_]+$",
-                            "type": "string"
-                          },
-                          "minItems": 1,
-                          "type": "array"
-                        },
-                        "publisher_domain": {
-                          "description": "Domain where the publisher's adagents.json is hosted (e.g., 'cnn.com')",
-                          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
-                          "type": "string"
-                        },
-                        "selection_type": {
-                          "const": "by_id",
-                          "description": "Discriminator indicating selection by specific property IDs",
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "publisher_domain",
-                        "selection_type",
-                        "property_ids"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "additionalProperties": false,
-                      "properties": {
-                        "property_tags": {
-                          "description": "Property tags from the publisher's adagents.json tags. Agent is authorized for all properties with these tags",
-                          "items": {
-                            "pattern": "^[a-z0-9_]+$",
-                            "type": "string"
-                          },
-                          "minItems": 1,
-                          "type": "array"
-                        },
-                        "publisher_domain": {
-                          "description": "Domain where the publisher's adagents.json is hosted (e.g., 'cnn.com')",
-                          "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
-                          "type": "string"
-                        },
-                        "selection_type": {
-                          "const": "by_tag",
-                          "description": "Discriminator indicating selection by property tags",
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "publisher_domain",
-                        "selection_type",
-                        "property_tags"
-                      ],
-                      "type": "object"
-                    }
-                  ]
+                  "$ref": "/schemas/v1/core/publisher-property-selector.json"
                 },
                 "minItems": 1,
                 "type": "array"
@@ -487,7 +426,7 @@
     "properties": {
       "description": "Array of all properties covered by this adagents.json file. Same structure as list_authorized_properties response.",
       "items": {
-        "$ref": "property.json"
+        "$ref": "/schemas/v1/core/property.json"
       },
       "minItems": 1,
       "type": "array"