feat(aao): re-introduce ?include=properties on directory inverse-lookup (#4890)

[bokelley]

Summary

Re-introduces the ?include=properties query parameter deferred from #4836's counts-only v1. When set, each PublisherEntry in GET /v1/agents/{agent_url}/publishers carries a property_ids: list[string] field — the canonical IDs the agent's selectors resolve to under that publisher.

Closes #4890.

Why

Count-equality is not set-equality. A publisher rotating N properties leaves properties_authorized unchanged while the underlying set is entirely different. The SDK divergence detector (adcp-client-python#752) currently short-circuits to "no divergence" on count match — missing routine rotations against managed-network parent files (the cafemedia ~6,800-publisher shape).

property_ids[] lets divergence detectors run full set-diff against a federated fetch.

Scope

Spec-only (schema + docs + changeset), parallel to the #4823 → #4836 pattern. Server implementation tracked as a follow-up.

• static/schemas/source/aao/agent-publishers.json — add property_ids: array<string> to PublisherEntry, optional (present iff include=properties).
• docs/aao/directory-api.mdx — document the include query parameter, worked example, response shape, field reference, and recommended workflow for divergence detectors. Update "Out of scope" since ?include=properties is no longer deferred.

Follow-ups

• Server impl: thread include=properties through getPublishersForAgentDetail in server/src/db/federated-index-db.ts and the route handler in server/src/routes/registry-api.ts. Update the Zod response schema (AgentPublishersEntrySchema) and regenerate static/openapi/registry.yaml. Integration test parallel to the existing detail-row tests.
• SDK companions: upgrade detect_publisher_properties_divergence to populate PublisherDivergence.missing_in_inline / .missing_in_federated from property_ids. Mirror in adcp-client (TS/JS) and adcp-go.

Test plan

• Schema JSON parses (verified locally).
• Docs render with new include row in the query-parameters table and the worked example.
• Changeset present.

🤖 Generated with Claude Code

[aao-release-bot]

Spec-only re-introduction of a deferred field, correctly scoped. Closing a count-vs-set false-negative trap in the divergence detector is the right primitive at the right layer.

Things I checked

• Schema/docs/example/changeset coherence — the worked example (docs/aao/directory-api.mdx:130-142), the field-reference row (:164), the schema description (static/schemas/source/aao/agent-publishers.json:78-82), and the changeset prose all agree on shape, gating, scope, and order-unspecified. No drift, no required-flip, no type change.
• property_ids correctly omitted from PublisherEntry.required[] — conditional on ?include=properties, absent otherwise. additionalProperties: false stays in place at PublisherEntry (line 115).
• Field naming matches canonical AdCP usage — property_ids is what core/publisher-property-selector.json, adagents.json selectors, and applies_to_property_ids already use. No properties[] / property_id_list drift.
• Empty-frontmatter changeset (---\n---) matches the sibling AAO PR convention (#4823, #4836, #4855). Intentional, not a defect.
• Query-parameter encoding inherits the repeated-key rule pinned in #4855 (?include=properties repeats the key, same as ?status=). Unknown values return 400. Consistent.
• "Out of scope" entry correctly narrowed from "Inline property detail" (which deferred ?include=properties entirely) to "Full property objects inline" — accurate now that IDs are in scope and only the full objects are deferred.
• Wire-compatibility: adding an optional response field gated by an opt-in query parameter is non-breaking. No in-production client is exposed; minor change shape is correct.

Follow-ups (non-blocking — file as issues or fold into the server impl PR)

1. Add uniqueItems: true to property_ids. static/schemas/source/aao/agent-publishers.json:78-82. The description asserts "treat as a set; order is unspecified" four times across docs and schema, but the schema doesn't encode it. Sibling selector arrays do — core/publisher-property-selector.json:26-27,93-94 and adagents.json:265-266,288-289 both pin uniqueItems: true. Without it, two conforming directories can emit ["p-001","p-001","p-002"] vs ["p-001","p-002"] and SDKs running raw set-diff disagree. The whole PR is about removing this class of inconsistency at the count layer; leaving it open at the ID layer reproduces it one level down. (ad-tech-protocol-expert flagged.)

2. Pin empty-array semantics. When properties_authorized: 0 and ?include=properties is set, is property_ids [], absent, or null? Docs imply []. One sentence in the field-reference row.

3. Server impl is the load-bearing follow-up — getPublishersForAgentDetail in server/src/db/federated-index-db.ts, route handler in server/src/routes/registry-api.ts, Zod AgentPublishersEntrySchema, regenerated static/openapi/registry.yaml. Integration test parallel to the existing detail-row tests. Mirror in adcp-client (TS/JS), adcp-client-python, adcp-go.

Minor nit (non-blocking)

Three checkboxes in the PR body's test plan, zero check marks. The claims behind them ("Schema JSON parses," "Docs render," "Changeset present") are all visible-in-diff or asserted in prose — not a substantive gap, but the boxes themselves are paper trail worth ticking.

LGTM. Follow-ups noted below.