feat(aao directory): re-introduce ?include=properties for full set-diff divergence detection

[bokelley]

Background

adcp#4836 (server implementation of GET /v1/agents/{agent_url}/publishers) explicitly deferred ?include=properties from v1 — "Counts-only v1." That decision was correct for shipping the directory endpoint, but it now constrains downstream SDKs.

Problem — count-only divergence is a false-negative trap

The SDK divergence detector (adcp-client-python#752, Part 3 of adcp-client-python#749) compares the directory's properties_authorized count against a per-child federated fetch result. When the counts match, the comparison returns "no divergence" — but count-equality is not set-equality.

Worked example (the cafemedia replacement-of-3 case):

Time	Directory thinks publisher has	Publisher actually has	Divergence detected?
T0	{p-001, p-002, p-003} (count = 3)	{p-001, p-002, p-003} (count = 3)	✓ correct, no divergence
T1	{p-001, p-002, p-003} (count = 3, stale)	{p-004, p-005, p-006} (count = 3, after publisher rotation)	✗ false negative — counts still match, set is entirely different

A publisher rotating three properties is a routine operation. Today's directory makes this rotation undetectable to operators relying on the divergence detector — which is exactly the population the directory is meant to serve.

Proposal

Add ?include=properties to GET /v1/agents/{agent_url}/publishers. When set, each PublisherEntry in the response carries a property_ids: list[string] field — the canonical list of property_ids the agent's selectors resolve to under that publisher.

{
  "publishers": [
    {
      "publisher_domain": "site.example.com",
      "discovery_method": "adagents_authoritative",
      "manager_domain": "cafemedia.com",
      "properties_authorized": 3,
      "property_ids": ["p-001", "p-002", "p-003"],
      ...
    }
  ]
}

Schema delta in static/schemas/source/aao/agent-publishers.json:

• PublisherEntry.property_ids: array of string, optional, present iff include=properties

Cost

• Response payload grows roughly linearly in property count. For cafemedia at ~6,800 publishers × avg 1 property each = ~7 KB of additional IDs per page — small.
• Directory index already computes the resolved property ID set during properties_authorized count derivation (per feat(server): implement /v1/agents/{agent_url}/publishers directory endpoint #4836 §"Per-publisher property counts"). Surfacing it is mostly serialization.

Out of scope

• Returning full property objects (not just IDs). Operators with the IDs can fetch detail via existing per-domain primitives.
• Pagination semantics for very-large-per-publisher lists (defer to v3 if it becomes a real shape).

Acceptance

• ?include=properties query parameter accepted; default off (preserves current envelope).
• When set, every PublisherEntry in response carries property_ids: list[string].
• Schema updated in static/schemas/source/aao/agent-publishers.json.
• Docs updated in docs/aao/directory-api.mdx.
• SDK divergence detectors (adcp-client-python, adcp-client TS, adcp-go) can be upgraded from count-only to full set-diff once this lands. Track the SDK upgrade in companion issues.

Companion SDK work

• adcontextprotocol/adcp-client-python — upgrade detect_publisher_properties_divergence to full set-diff (PublisherDivergence.missing_in_inline / .missing_in_federated populated from property_ids, not None).
• adcontextprotocol/adcp-client (TS/JS) — mirror.
• adcontextprotocol/adcp-go — mirror.

References

• Deferred from: feat(server): implement /v1/agents/{agent_url}/publishers directory endpoint #4836 ("Counts-only v1")
• SDK consumer: feat(adagents): divergence detector + ?include=properties for directory inverse-lookup (#749 Part 3, adcp#4894) adcp-client-python#752
• Resolution-paths spec: docs/governance/property/adagents.mdx §Resolution-paths

[bokelley]

Triage

Classification: Feature request
Bucket(s): registry / discovery, schema
Status: drafting-pr
Milestone: 3.1.0 (minor bump → main; ships as 3.1.0-beta.N while pre-mode is active)

What the experts said:

• ad-tech-protocol-expert: ?include=properties follows the established status repeated-key encoding convention; $ref /schemas/core/property-id.json is correct; minor bump confirmed; MUST len(property_ids) == properties_authorized is accurate prose but not machine-enforceable in JSON Schema draft-07 — flagged as a conformance-storyboard follow-up.
• adtech-product-expert: Opt-in design is correct; payload size estimate (~7 KB/page for cafemedia) is plausible; SDK upgrade path should be coordinated so operators migrate together rather than indefinitely running count-only detection — tracked in the SDK companion issues listed in acceptance criteria.
• code-reviewer (pre-PR): No blockers. Schema change correct (additionalProperties: false satisfied, property_ids absent from required, $ref path matches $id). Nit: worked example reuses a domain already in the existing docs; nit: property_ids could be placed adjacent to properties_total in schema and table.

My take: Clean non-breaking additive change — optional query param, optional response field, default off. Draft PR #4892 adds the schema field with the normative MUST consistency guarantee and the docs section with a worked example and divergence-detection rationale.

Draft PR: #4892

---

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

---

Generated by Claude Code

[bokelley]

Reopening: current main already has the docs/schema for ?include=properties, but the registry endpoint does not yet parse include=properties or serialize property_ids. The open draft PR #4892 is stale/dirty and only carries the docs/schema portion, so the remaining work should be implementation-only against current main.