feat(adagents): clarify publisher_properties resolution — managed-network pattern needs inlined-properties path

[bokelley]

Empirical evidence

Pulled https://cafemedia.com/.well-known/adagents.json (2.6 MB, `last_updated: 2026-05-14`, contact: Raptive). It is the largest known AAO-conformant file in production and represents the canonical "managed network" delegation pattern (~6,800 publisher properties under one operator). Structure:

{
  \"\$schema\": \"https://adcontextprotocol.org/schemas/v3/adagents.json\",
  \"authorized_agents\": [
    {
      \"url\": \"https://interchange.io\",
      \"authorization_type\": \"publisher_properties\",
      \"authorized_for\": \"Official sales agent for Raptive US display inventory\",
      \"publisher_properties\": [{
        \"selection_type\": \"by_tag\",
        \"property_tags\": [\"raptive_managed\"],
        \"publisher_domains\": [\"recipeswithessentialoils.com\", \"cravethegood.com\", ... 6800 total]
      }]
    }
  ],
  \"properties\": [
    {
      \"property_id\": \"5bd748df...\",
      \"property_type\": \"website\",
      \"identifiers\": [{\"type\": \"domain\", \"value\": \"recipeswithessentialoils.com\"}],
      \"publisher_domain\": \"recipeswithessentialoils.com\",
      \"tags\": [\"raptive_managed\"]
    },
    ... 6843 total inline properties
  ],
  \"tags\": {\"raptive_managed\": {\"name\": \"Raptive Managed\", ...}}
}

The gap

Per the spec at /schemas/3.1.0-beta.1/core/publisher-property-selector.json:

"the same `property_tags` predicate is resolved against each listed publisher's adagents.json"

This is the federated resolution model: to enumerate cafemedia's authorized inventory, a resolver must fetch each of the 6,800 child publishers' adagents.json files, follow their delegation chains, and find properties matching the selector. Operationally infeasible at managed-network scale — 6,800 HTTP fetches per agent-authorization check.

Cafemedia's pragmatic answer: inline the properties in the parent file with a publisher_domain field on each property record. The selector + publisher_domains list + property_tags list unambiguously identifies which inline properties belong to which child. But the spec doesn't currently endorse this resolution path.

Result today

The Python SDK at adcp/adagents.py:953-957 handles publisher_properties by returning the raw selector dicts:

if authorization_type == \"publisher_properties\":
    publisher_props = agent.get(\"publisher_properties\", [])
    if not isinstance(publisher_props, list):
        return []
    return [p for p in publisher_props if isinstance(p, dict)]

So get_properties_by_agent(cafemedia_data, \"https://interchange.io\") returns 1 dict (the selector), not the 6,843 actual properties. Downstream consumers (the Prebid Sales Agent's _count_total_properties at src/services/aao_lookup_service.py:249) get nonsense counts ("1 / 1 authorized" instead of "6843 / 6843").

Proposal — pick one

Option A (recommended): Extend the spec to recognize the inline-with-publisher_domain resolution path. When a parent file (a) contains a publisher_properties selector AND (b) has top-level properties[] entries with publisher_domain fields matching the selector's publisher_domains, the resolver MAY satisfy the selector from the parent file's inline properties — no per-child fetch required. Keeps federated resolution as a fallback for files that don't inline.

Option B: Spec stays as-is (strictly federated). Then cafemedia and every future managed network needs to either (i) restructure each of 6,800 child domains to publish their own adagents.json, or (ii) the SDK adds a pragmatic "check parent file first" extension that's nonconformant per spec. This is the worse outcome — pushes complexity onto every operator.

Option C: Spec defines an explicit "managed network" authorization_type that says "properties are inlined in this file with publisher_domain field" — distinct from cross-publisher federation. Cleanest but breaks cafemedia's current file shape and requires migration.

Why this is urgent

Cafemedia is the production reference. Their file has been static-ish since at least 2026-05. Every downstream consumer either:

• Reports broken property counts (current SDK behavior)
• Hits 6,800 HTTP fetches to enumerate the network (strict spec compliance)
• Forks the SDK with a private "parent file inline lookup" extension

The Prebid Sales Agent (prebid/salesagent#511) hit this trying to onboard Raptive.

Companion tickets

• feat(aao): inverse-lookup endpoint — given agent_url, return authorizing publishers #4823 — AAO directory inverse-lookup endpoint (orthogonal: "which publishers authorize me" vs. this issue's "what does cafemedia authorize me for")
• feat(adagents): fetch_agent_authorizations_from_directory — inverse lookup against AAO directory adcp-client-python#746 — SDK wrapper for inverse-lookup directory
• Implementation of whichever option lands here will need a companion SDK PR

References

• _resolve_agent_properties SDK gap: adcp/adagents.py:909-959
• Selector schema: https://adcontextprotocol.org/schemas/3.1.0-beta.1/core/publisher-property-selector.json
• Live cafemedia file: https://cafemedia.com/.well-known/adagents.json (HTTP 200, 2.6 MB)

[bokelley]

Triage

Classification: Feature request (spec extension)
Bucket(s): registry / discovery, spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Existing MUST NOT at docs/governance/property/adagents.mdx:498 ("The manager file MUST NOT inline copies of each represented publisher's properties") makes Option A unsound as proposed; any formal inline-resolution path is minor on main only and needs conflict-ordering rules and a revocation-lifecycle analysis before WG can approve — plus prior-art note that sellers.json deliberately chose federated for the same blast-radius reason.
• adtech-product-expert: The "1 / 1" symptom is a Python SDK bug — get_properties_by_agent() doesn't fan publisher_domains[] into N per-publisher fetch-and-resolve calls — not a spec gap; fixing the SDK may close the Raptive/Prebid onboarding gap without touching normative text, though whether cafemedia's inline shape already violates the MUST NOT is a separate WG policy call.

My take: Both experts converged on adagents.mdx:498's MUST NOT as the crux — removing it is a deliberate design reversal with security implications (bilateral verification model, blast-radius isolation), not a clarification. @bokelley, your call: does the WG want to formally open a new inline-resolution path (removing the MUST NOT, adding conflict-ordering and revocation rules), or does fixing the Python SDK's publisher_domains[] fan-out close the operational gap without touching normative text?

---

Option A — add inline-resolution MAY (requires removing the existing MUST NOT):

// adagents.mdx:498 — current
- The manager file MUST NOT inline copies of each represented publisher's properties;
- consumers fetch each listed publisher's own adagents.json to resolve the selector.
// proposed
+ When a parent file contains properties[] entries whose publisher_domain matches
+ the selector's publisher_domains, resolvers MAY satisfy the selector from those
+ inline entries. Federated per-child fetch remains the fallback. Inline entries
+ MUST NOT supersede a child's revoked_publisher_domains[] entry on the same domain.

Requires WG vote to remove MUST NOT. Needs new conflict-ordering rule + revocation lifecycle analysis. Minor changeset on main only.

SDK-fix path (narrows the gap without spec change):

# adcp/adagents.py — fix publisher_domains[] fan-out
if authorization_type == "publisher_properties":
    for sel in agent.get("publisher_properties", []):
        domains = [sel["publisher_domain"]] if sel.get("publisher_domain") else sel.get("publisher_domains", [])
        for domain in domains:
            yield from resolve_child_adagents(domain, sel)

Closes "1 / 1" bug in adcp-client-python. Cafemedia's inline properties[] may still violate the MUST NOT — that's a separate compliance question. SDK-only change, no spec amendment.

Option C — new authorization_type: "managed_network" (clean semantics, requires migration):

// cafemedia's adagents.json
{
  "url": "https://interchange.io",
- "authorization_type": "publisher_properties",
+ "authorization_type": "managed_network",
  "publisher_properties": [{ "selection_type": "by_tag", "property_tags": ["raptive_managed"], "publisher_domains": [...6800] }]
}

Additive (new enum value), so non-breaking by schema definition. But cafemedia must migrate a production 2.6 MB file and every resolver needs a new branch. Probably unnecessary friction given Option A + SDK fix covers the scenario.

Open questions for WG:

1. Is the MUST NOT's rationale (bilateral per-publisher verifiability) still load-bearing at managed-network scale, or does the authoritative_location delegation model already accept that publishers can defer their property catalog to a parent?
2. If inline resolution is endorsed, which file wins when the inline entry and the child's own adagents.json disagree — and does the spec need to say?
3. Does the revocation lifecycle (revoked_publisher_domains[]) work correctly when the property catalog is inline rather than per-child-fetched?

Companion: adcontextprotocol/adcp-client-python#746 (SDK inverse-lookup, orthogonal but same surface).

---

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

---

Generated by Claude Code

[bokelley]

Going with Option A — endorse parent-file inline resolution

The triage framed this as a fork: "open a new inline-resolution path (spec change)" vs "fix the SDK's publisher_domains[] fan-out." The fan-out fix is correct and should land independently in adcp-client-python — but it does not close the operational gap, because at managed-network scale 6,800 HTTP fetches per authorization check is a non-starter regardless of which side does the fanning. The Python SDK bug is real and orthogonal; the spec-text bar at adagents.mdx:498 is the binding constraint.

Cafemedia's production file (2.6 MB, 6,843 inline properties) already violates the current MUST NOT. Either the spec endorses the shape, or every conformant consumer reports cafemedia as broken — and the spec is the wrong answer.

Answers to the three WG open questions

1. Is the MUST NOT's rationale (bilateral per-publisher verifiability) still load-bearing at managed-network scale?

The safety property the MUST NOT was protecting is: the publisher whose inventory is being authorized must be explicitly named, so a manager can't silently authorize someone else's properties. That invariant is preserved by Option A's gating condition — each inline property MUST carry an explicit publisher_domain matching one in the selector's publisher_domains[]. The trust anchor moves from "the per-publisher adagents.json fetch named this property" to "the per-property publisher_domain field named this publisher" — both are publisher-naming, both refuse silent cross-publisher authorization.

This is the same anchor the managed-network-scale changeset already accepted for property_ids / property_tags selectors on the agent entry: top-level properties[] with publisher_domain is a recognized resolution surface. Option A extends the same pattern to publisher_properties selectors. It's not a new trust model — it's the existing one applied to one more selector type.

The MUST NOT's other rationale — blast-radius isolation when a child publisher is compromised — is also preserved: WG question #2 answers what happens when inline and federated diverge.

2. Which file wins when the inline entry and the child's own adagents.json disagree?

Federated wins. The per-publisher adagents.json remains the trust root; the inline path is an optimization the consumer MAY take, not a replacement for the child's own declaration. Spec text:

If a consumer resolves the same (publisher_domain, property_id) via both inline and federated paths and the results disagree, the federated result is authoritative. Consumers SHOULD log the divergence as a publisher-side data-integrity warning and MAY surface it to operators. Consumers that prefer strict federation MAY ignore the inline path entirely.

This keeps the bilateral-verification model available: any operator who wants strict per-child verification can still get it. Inline is permissive; federation is normative. A consumer that uses the inline path is accepting the parent file's declaration about each child's inventory; if that turns out to be wrong, the child's own file is the corrective signal.

3. Does the revocation lifecycle (revoked_publisher_domains[]) work correctly when the property catalog is inline?

Yes, with one normative addition: inline resolution MUST honor revoked_publisher_domains[] from both the parent file AND the child publisher's own adagents.json (when consulted). First match revokes. Concretely:

• Parent file lists publisher_X in revoked_publisher_domains[] → inline properties claiming publisher_domain: publisher_X resolve to empty set, regardless of tag match.
• Child publisher's own file lists itself revoked → inline properties for that publisher resolve to empty set when the consumer cross-checks.

A consumer using purely inline resolution can satisfy revocation from the parent file's revoked_publisher_domains[] alone — no per-child fetch required for the revocation lifecycle to work. A consumer that wants belt-and-braces can do the per-child cross-check.

Add to normative text:

Inline resolution MUST honor revoked_publisher_domains[] on the parent file. A publisher_domain listed as revoked at the parent level resolves to the empty set for that domain, regardless of whether matching properties exist in the parent's properties[]. Consumers that also resolve federated SHOULD cross-check the child's own revoked_publisher_domains[]; first match (parent or child) revokes.

Why not the SDK-fix-only path

The triage's "fix the SDK's publisher_domains[] fan-out" path closes the get_properties_by_agent "1/1 instead of 6843/6843" bug, which is real and should land separately. But it doesn't close the operational gap:

1. Strict federation costs 6,800 HTTP fetches. Even with the SDK doing the fanning correctly, no operator is going to fetch 6,800 publisher adagents.json files per agent-authorization check, per refresh cycle, per directory consumer. The cost was always the bottleneck; the SDK bug just hid it.
2. Cafemedia's file already violates the current MUST NOT. SDK-only path leaves the spec saying "the manager file MUST NOT inline" while the production reference inlines. Every consumer either reports cafemedia as broken or quietly forks. The spec needs to bless what production is doing or break it.
3. The AAO directory (feat(aao): inverse-lookup endpoint — given agent_url, return authorizing publishers #4823) depends on this. The directory computes properties_total per publisher row by resolving each publisher_properties selector. On cafemedia-shape files, with strict federation, the directory's refresh cycle is 6,800 fetches per indexed agent. With inline resolution, it's one parse. The directory cannot ship correct counts at managed-network scale without this rule settled.

The SDK fan-out fix lands in adcp-client-python regardless — it's correct behavior for the federated path. But it isn't a substitute for the spec change.

Proposed normative text

Replacing docs/governance/property/adagents.mdx:498:

Resolution paths. A publisher_properties selector resolves against properties in one of two ways:

1. Federated resolution (default). For each domain in publisher_domain or publisher_domains[], fetch that publisher's adagents.json and apply the selector predicate against the publisher's own top-level properties[]. This is the trust-root path.

2. Parent-file inline resolution (managed-network optimization). A consumer MAY satisfy the selector from the parent file's own top-level properties[] when all of the following hold:

   • The parent file has top-level properties[] entries.
   • Every matched property carries an explicit publisher_domain field whose value equals one of the domains in the selector's publisher_domain / publisher_domains[] set.
   • For selection_type: by_tag: the property's tags[] contains at least one of the selector's property_tags[].
   • For selection_type: by_id: the property's property_id is in the selector's property_ids[] AND the selector uses its singular publisher_domain form (the compact publisher_domains[] form remains rejected for by_id).
   • For selection_type: all: every parent-file properties[] entry with a matching publisher_domain is selected.

Inline resolution is a per-domain optimization: a consumer MAY use inline resolution for the listed domains that have matching inline properties in the parent file, AND federated resolution for the remainder. If inline and federated resolutions disagree on the same (publisher_domain, property_id), the federated result is authoritative; the consumer SHOULD log the divergence as a publisher-side data-integrity warning. Consumers that prefer strict federation MAY ignore the inline path entirely.

Inline resolution MUST honor revoked_publisher_domains[] on the parent file. A publisher_domain listed as revoked at the parent level resolves to the empty set for that domain, regardless of whether matching properties exist in the parent's properties[]. Consumers that also resolve federated SHOULD cross-check the child's own revoked_publisher_domains[]; first match (parent or child) revokes.

Why this is safe. The trust anchor for property authorization is the publisher whose domain is named on the property. By requiring publisher_domain on each inline property and matching against the selector's publisher_domains[], the inline path preserves the invariant that the publisher whose inventory is being authorized is explicitly named — the same invariant the managerdomain fallback safety rule protects. A manager file cannot use inline resolution to authorize inventory for a publisher it doesn't list.

Companion edits

• static/schemas/source/core/publisher-property-selector.json — extend the by_tag and all selector descriptions to note the inline resolution path.
• docs/governance/property/adagents.mdx:244 — tighten the reachability invariant clause to acknowledge publisher_properties selectors satisfied via parent-file inline.
• Existing .changeset/adagents-managed-network-scale.md work is unchanged; this lands as a follow-up changeset.

Proposed changeset

---
"@adcontextprotocol/adcp": minor
---

feat(adagents): permit parent-file inline resolution of `publisher_properties`
selectors when matched top-level properties carry a `publisher_domain` matching
the selector's `publisher_domain` / `publisher_domains[]`.

Federated per-child resolution remains the default and the trust root. Inline
is a per-domain optimization adopted because the production reference for the
managed-network pattern (cafemedia.com, ~6,800 represented domains) inlines
properties — strict federation requires N HTTP fetches per authorization
check, infeasible at managed-network scale.

Divergence rule: if inline and federated resolutions disagree, federated wins.
Revocation: inline path MUST honor parent-file `revoked_publisher_domains[]`;
consumers SHOULD also cross-check the child's own when federated.

Companion work (orthogonal but should land)

• adcp-client-python: fix _resolve_agent_properties to fan publisher_domains[] into per-domain resolution AND consult parent-file inline first when matching properties carry publisher_domain. The triage correctly identified the existing SDK bug; this lands alongside the spec change.
• Enhance GCP service account creation logging prebid/salesagent#511 — concrete downstream consumer hitting this gap onboarding Raptive.