feat(adagents): inline-resolution path for publisher_properties selectors + directory inverse-lookup wrapper

[bokelley]

Two related pieces of SDK work coming out of adcp#4825 and adcp#4823.

Part 1 — Inline-resolution path for publisher_properties selectors

adcp#4825 (spec PR adcp#4827) endorses parent-file inline resolution: when a parent file's top-level properties[] entries carry a publisher_domain matching one in the selector's publisher_domains[], the consumer MAY satisfy the selector from those inline properties without per-child adagents.json fetches.

This SDK has two related bugs at adcp/adagents.py:953-957:

1. Returns raw selector dicts instead of resolved properties. get_properties_by_agent(cafemedia_data, "https://interchange.io") returns 1 selector dict instead of the 6,843 inline properties.

2. No publisher_domains[] fan-out. _resolve_agent_properties doesn't expand the compact-form publisher_domains[] array into per-domain resolution. This is the bug adcp#4825's triage identified as orthogonal to the spec change.

Both need fixing. The fix:

if authorization_type == "publisher_properties":
    selectors = agent.get("publisher_properties", [])
    if not isinstance(selectors, list):
        return []
    resolved: list[Property] = []
    parent_properties = adagents_data.get("properties", []) or []
    for selector in selectors:
        if not isinstance(selector, dict):
            continue
        domains = _selector_domains(selector)  # publisher_domain | publisher_domains
        for domain in domains:
            inline = _resolve_inline(selector, parent_properties, domain)
            if inline is not None:
                resolved.extend(inline)
                continue  # inline succeeded; skip federated fetch
            resolved.extend(_resolve_federated(selector, domain))
    return resolved

_resolve_inline returns None (not []) when no matched property carries the expected publisher_domain, so federated fallback fires. Empty inline match with at least one inline candidate counts as a real empty resolution.

Divergence rule (from spec): if both paths resolve to the same (publisher_domain, property_id) and disagree, federated wins; SDK SHOULD log the divergence.

Revocation: inline path MUST honor revoked_publisher_domains[] on the parent file.

Part 2 — Directory inverse-lookup wrapper

adcp#4823 (spec PR adcp#4828) defines GET /v1/agents/{agent_url}/publishers. SDK needs a wrapper:

def fetch_agent_authorizations_from_directory(
    agent_url: str,
    directory_url: str = "https://agenticadvertising.org",
    *,
    since: datetime | None = None,
    status: list[str] = ["authorized"],
    cursor: str | None = None,
    limit: int = 200,
    timeout: float = 30.0,
) -> AgentDirectoryLookup:
    """Inverse of fetch_agent_authorizations — returns the publishers
    that authorize this agent, sourced from the AAO directory's index.

    Mirrors the existing AdAgentsValidationResult provenance fields
    (discovery_method, manager_domain) so consumers can route directory-
    sourced and per-domain results through the same code path.
    """

Return type mirrors the response envelope schema. Iterator support for paginated responses is a plus.

Acceptance

Part 1:

• get_properties_by_agent(cafemedia_data, "https://interchange.io") returns the 6,843 inline properties matching tags ∋ "raptive_managed" and publisher_domain ∈ publisher_domains[...], not the selector dicts.
• publisher_domains[] compact form is fanned into per-domain resolution.
• When inline and federated diverge, SDK logs the divergence and uses the federated result.
• Parent-file revoked_publisher_domains[] revokes inline matches for that domain.

Part 2:

• fetch_agent_authorizations_from_directory returns spec-conformant AgentDirectoryLookup with discovery_method, manager_domain, properties_authorized, properties_total, signing_keys_pinned, status, last_verified_at per publisher.
• Cursor pagination handled transparently or exposed as iterator.
• Reuses AdAgentsValidationResult provenance fields where the vocabulary overlaps.

References

• Spec PR for the resolution rule: adcp#4827
• Spec PR for the directory endpoint: adcp#4828
• Downstream consumer hitting Part 1: prebid/salesagent#511
• Existing SDK gap: adcp/adagents.py:909-959

[bokelley]

Triage

Classification: Bug (Part 1) + Feature request (Part 2)
Bucket(s): client (no client label exists in this repo — gap noted)
Status: drafting-pr (Part 1 shipped as #750) / clarify (Part 2 pending 3 questions below)

What the experts said:

• code-reviewer: Part 1 — buggy test encoded selector-passthrough behavior (fixed); by_id branch missing isinstance(str) filter (fixed); no dedup across multi-selector fan-out (fixed); missing by_id unit test (added). Part 2 — mutable default status=["authorized"] is a footgun; function must be async def to match the rest of the module.
• ad-tech-protocol-expert: Part 1 inline path is spec-sound per adcp#4827; publisher_domains[] compact form is not in the 3.0 schema cache (needs regeneration after adcp#4827 merges). Part 2 — endpoint /v1/agents/{url}/publishers doesn't match the live /api/registry/ base already in the SDK; AgentDirectoryLookup return type is undefined; agent_url must be %-encoded in the path.

My take: Part 1 is a clear bug fix with spec backing — draft PR #750 ships today. Part 2 has three unresolved protocol questions; implementing it now would produce a 404-ing endpoint wrapper with an undefined return type.

Part 2 — 3 questions before I can proceed:

1. Endpoint path: Is it /v1/agents/{encoded_url}/publishers or /api/registry/agents/{encoded_url}/publishers? The SDK's existing RegistryClient uses the /api/registry/ base — if /v1/ is a new tree on agenticadvertising.org, please link the changelog or confirm the route.

2. Return type: Should AgentDirectoryLookup be a new Pydantic type (needs a schema file + _generated.py + stable.py export pipeline) or an extension/alias of the existing FederatedAgentWithDetails? The latter already carries publisher_domains: list[str] | None.

3. Divergence rule: Is there a normative quote from adcp#4827 confirming "federated wins on disagreement"? The current PR defers divergence logging pending that confirmation — happy to add it once I can verify the trust-ordering direction.

---

Part 1 shipped: #750

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

Refinements after merging adcp#4827 + adcp#4828 + adcp#4838 + adcp#4840

Two additions to the work already scoped above:

1. Canonical fixture: cafemedia.com / interchange.io

After PR adcp#4840 deploys (the crawler write-path that fans publisher_properties[].publisher_domains[] into per-child rows), production has real data backing the inline-resolution path:

• https://cafemedia.com/.well-known/adagents.json — 2.6 MB, 6,843 inline properties[], 6,800 unique child publisher_domains, all tagged raptive_managed. One authorized agent: https://interchange.io.
• After the fan-out: GET https://agenticadvertising.org/api/v1/agents/https%3A%2F%2Finterchange.io/publishers returns ~6,800 rows with discovery_method='adagents_authoritative' and manager_domain='cafemedia.com'.

Use this as the canonical fixture for the SDK's _resolve_agent_properties test suite — it's the production reference for the managed-network shape, sized large enough to catch O(N²) accidents and provenance edge cases.

2. Part 3 — Divergence detector

When the inline resolution path (Part 1) and federated resolution (per-child fetch) produce different (publisher_domain, property_id) sets, the spec says federated wins and the SDK SHOULD log a divergence warning (adagents.mdx Resolution paths). Today no consumer ever sees that signal because no one runs both paths.

Add a verifier helper:

def detect_publisher_properties_divergence(
    agent_url: str,
    directory_url: str = "https://agenticadvertising.org",
    *,
    sample_size: int | None = None,
    timeout: float = 30.0,
) -> DivergenceReport:
    """
    For each publisher_domain the directory returns under this agent_url:
    1. Read the directory's inline resolution result (counts + property_ids
       if `?include=properties` is supported, else just count).
    2. Fetch the publisher's own adagents.json directly.
    3. Apply the same selector against the child's properties[].
    4. Diff the (publisher_domain, property_id) sets.

    Returns: list of (publisher_domain, missing_in_inline, missing_in_federated,
    child_fetch_error) tuples. Empty list means no divergence detected.

    Intended use: periodic batch over a sales-agent operator's authorization
    set, surfacing publisher-side data-integrity warnings ("cafemedia claims
    site_X has property Y but site_X's own adagents.json doesn't").
    """

sample_size is required for managed networks — running this against cafemedia's 6,800 children means 6,800 sequential HTTP fetches. Default to None (full sweep) but document the cost.

Output should be machine-readable so a sales agent operator can hook it into their existing monitoring rather than reading SDK logs.

This is Part 3 of the ticket — same SDK release as Parts 1 and 2.

Updated acceptance

Part 1 (inline resolution):

• (covered above)
• cafemedia.com / interchange.io fixture included in the test corpus; SDK returns ~6,843 properties for get_properties_by_agent(cafemedia_data, "https://interchange.io")

Part 2 (directory wrapper):

• (covered above)

Part 3 (divergence detector):

• detect_publisher_properties_divergence returns expected drift on a synthetic test fixture where parent and child disagree
• Returns empty diff on cafemedia/interchange.io (production reference where parent and child are by-construction in agreement)
• Documents the per-child fetch cost; sample_size parameter caps it