feat(aao): define directory inverse-lookup endpoint spec (#4823)

[bokelley]

Summary

Spec for GET /v1/agents/{agent_url}/publishers — the AAO directory's inverse-lookup endpoint. Returns the set of publishers whose adagents.json authorizes a given agent_url, with provenance, per-publisher property counts, and lifecycle status.

Scope of this PR is spec-only. Server implementation is non-trivial (new discovery_method / manager_domain columns, per-publisher selector resolution to compute counts, signing_keys_pinned lookup) and tracked separately — see Follow-ups below.

Files

• static/schemas/source/aao/agent-publishers.json — response envelope schema. New static/schemas/source/aao/ subdirectory.
• docs/aao/directory-api.mdx — full API reference: endpoint shape, query params, response, field reference, HTTP semantics, pagination, relationship to existing SDK primitives.
• docs.json — adds docs/aao/directory-api to the "Using AAO" nav group.
• .changeset/4823-aao-directory-inverse-lookup-endpoint.md.

Design decisions (from issue triage)

Status enum scoped to authorized + revoked for v1

Triage Decision 1. The richer unbound / pending states presuppose crawler state the directory doesn't have today — and pending in particular requires snapshot semantics around publishers whose files we've fetched but don't list this agent (a separate indexing pass). Ship what's queryable; leave room to add states later.

revoked is cheap to surface: when a publisher's adagents.json newly lists this publisher_domain in revoked_publisher_domains[], the directory emits one tombstone row on the next sync, then drops it.

Counts kept, scoped per-publisher, renamed

Triage Decision 2. The "12/12 reads as full auth but really means 12-of-6800-network" critique is real, but the directory's whole value-add is that it ran the resolution once so operators don't all hammer 6,800 publishers in parallel. Fix is naming + scoping, not dropping counts.

properties_authorized — properties under THIS publisher_domain the agent's selector resolves to
properties_total     — properties under THIS publisher_domain in the publisher's file

Both scoped to the row's publisher, never network-wide. recipeswithessentialoils.com returns { properties_authorized: 1, properties_total: 1 }, and the operator sees 6,800 such rows summing to the network total — correct mental model, no ambiguity.

discovery_method distinguishes four trust profiles

Per the protocol expert: direct, authoritative_location, adagents_authoritative, ads_txt_managerdomain. The managerdomain path is the weakest (the safety rule is the only positive cross-check); the directory does that bilateral check once, for everyone — main value-add over a per-operator ads.txt crawl.

signing_keys_pinned: bool per row

Cheap to surface, useful at sync time: tells the operator whether this publisher pins their JWKS, which is the signal that the agent's published keys must match. No new crawler state required.

No auth in v1

Publishers are public; the inverse map is public. Rate-limiting keyed on agent_url + IP. Identity-bound limits via RFC 9421 request signing arrive in a separate RFC if needed.

Dependency on #4825

properties_total on managed-network-shape parent files depends on #4825's inline-resolution rule (PR #4827). Strict federation at managed-network scale requires N HTTP fetches per directory refresh per publisher — the same scale problem operators have, moved one layer up. With inline resolution endorsed, the directory computes per-publisher counts from the parent file's inline properties[] filtered by matching publisher_domain.

The docs page links to #4825 as a soft dependency; the schema is independent (works with either resolution path).

Follow-ups

• Server implementation in server/src/routes/registry-api.ts, backed by server/src/db/federated-index-db.ts. The existing getDomainsForAgent returns (agent_url, publisher_domain, authorized_for, property_ids, source, discovered_at, last_validated) — needs extension to surface discovery_method (vs the existing source evidence enum), manager_domain, per-publisher property counts (via expandPublisherPropertiesToIdentifiers), and signing_keys_pinned. Will file as a separate issue.
• SDK companion: fetch_agent_authorizations_from_directory in adcp-client-python (#746) and TS/Go/Java mirrors.
• ?include=properties for inline property detail — out of scope for v1; add later if operators ask.

Resolves #4823.

Test plan

• npm run build:schemas clean — schema bundles to dist/schemas/latest/aao/agent-publishers.json
• precommit (vitest run, typecheck, dynamic-imports) passes
• Reviewer: check nav placement under "Using AAO" — directory API is API-reference territory, may want its own group later
• Reviewer: re-read discovery_method enum semantics against existing crawler's actual discovery paths to ensure naming aligns
• Reviewer: cross-check the dependency note on feat(adagents): clarify publisher_properties resolution — managed-network pattern needs inlined-properties path #4825 — PR feat(adagents): endorse parent-file inline resolution of publisher_properties (#4825) #4827 needs to land before the server implementation can compute correct properties_total on managed-network files

🤖 Generated with Claude Code

[aao-release-bot]

LGTM. Follow-ups noted below. Right shape for an inverse-lookup: discovery, not authorization — the publisher's adagents.json stays the trust root and the directory tells you which trust roots to hit.

Things I checked

• Schema validity (static/schemas/source/aao/agent-publishers.json). Draft-07, additionalProperties: false at both envelope and PublisherEntry, next_cursor correctly typed ["string", "null"], properties_authorized/properties_total integer with minimum: 0, conditional if/then enforces manager_domain on the three non-direct discovery methods.
• Schema-vs-docs parity. Required sets, enum values (4 discovery methods, 2 statuses), and optional-ness flags (signing_keys_pinned, next_cursor) all match docs/aao/directory-api.mdx:80-116 field reference tables.
• Wire dependencies resolve against existing AdCP spec. signing_keys[] exists at static/schemas/source/core/authorized-agent-base.json:19. revoked_publisher_domains[] exists at static/schemas/source/adagents.json:93-126 with matching tombstone semantics. managerdomain safety rule anchor #safety-rules-for-this-fallback resolves at docs/governance/property/adagents.mdx:237. No hidden cross-PR dependency.
• Soft dep on #4825 (inline resolution) is disclosed in prose (directory-api.mdx:160-162, changeset). Schema works either way; only properties_total count semantics differ.
• Changeset categorization. Empty frontmatter is consistent with sibling AAO endpoint changesets (aao-hosted-adagents-json-route.md, aao-measurement-vendor-discovery.md). Spec-only directory addition, no SDK wire surface today.
• No oneOf added — no audit-walker regression. Confirmed static/schemas/source/aao/agent-publishers.json has zero oneOf.

Follow-ups (non-blocking — file as issues)

• Schema accepts {discovery_method: "direct", manager_domain: "evil.com"}. agent-publishers.json:93-109 has only the non-direct if/then; no else clause restricts manager_domain to null on the direct case. Field description and docs both say "Null or absent when direct." Add a second if/then with then: { properties: { manager_domain: { type: "null" } } }, or convert to a oneOf over the four discovery_method values. Small validator drift today, easy to close before any SDK starts consuming this.
• Dead anchor. directory-api.mdx:107 and :162 link to /docs/governance/property/adagents#resolution-paths. No such heading in adagents.mdx. Either add ### Resolution paths to adagents.mdx as part of #4825 landing, or repoint to #authorization-patterns / the existing fan-out section.
• discovery_method naming overlap. authoritative_location is both an enum value here and a field name in static/schemas/source/adagents.json:15. adagents_authoritative reads as near-synonym to authoritative_location for skim-readers. You flagged this in your own test plan. Worth considering authoritative_location_pointer / manager_inline / similar — non-blocking; happy to leave to a follow-up RFC if you'd rather not churn the enum before the server lands.
• since is under-specified for incremental sync. directory-api.mdx:29 says "filter by last_verified_at ≥ since" but documents no sort order, no relationship to cursor (do they compose? does pagination preserve since?). Tighten before clients write resume logic.
• URL canonicalization. directory-api.mdx:23 and the schema description compress the canonicalization rule in prose. There's already docs/reference/url-canonicalization.mdx — link to it rather than re-paraphrasing, otherwise server/SDK drift as that doc evolves.
• Enum extensibility policy. status (2 values) and discovery_method (4 values) are closed enums. Brand-new endpoint, no cost today. Before adding unbound/pending/etc., decide whether enum extension is additive-only (clients tolerate unknowns) or requires a minor bump. Wire it into the changeset bar before the second wave.
• Nav placement. docs.json puts this under "Using AAO" with the org/user how-tos. It reads like an API reference. Reasonable to graduate to its own subgroup (mirroring the Signals "Reference" subgroup at docs.json:1106-1114) once a second endpoint lands.

Minor nits (non-blocking)

1. 404-vs-200-empty distinction (directory-api.mdx:126). Sound but commits the directory to "have I ever indexed this agent_url" state. Worth a sentence acknowledging the storage commitment, or relax to "directory MAY return 404 to signal never-indexed" so non-stateful implementations stay conforming.
2. status query param is comma-separated and not modeled in any request schema. Fine for now; flag for the server-implementation PR to add request validation.

Safe to merge. Schema is additive, no implementation, no consumer to break — the if/then gap and the dead anchor are both one-line fixes that can chase in the server-implementation PR.