feat(openapi): add community mirror lifecycle endpoints

[bokelley]

Adds the community-mirror lifecycle endpoints and schemas to the generated registry OpenAPI spec so SDKs can generate typed mirror DTOs.

This also tightens related registry metadata for /api/adagents/create, captures mirror-specific invariants like HTTPS superseded_by URLs and empty authorized_agents, extends OpenAPI coverage to the mirror router, and adds a minor changeset.

Checks run: npm run build:openapi, npm run typecheck, npx vitest run server/tests/unit/openapi-coverage.test.ts --config server/vitest.config.ts, npx vitest run server/tests/integration/community-mirrors.test.ts --config server/vitest.config.ts, DATABASE_URL=postgresql://adcp:localdev@localhost:5432/adcp_test npx vitest run server/tests/integration/adagents-create-catalog-only.test.ts --config server/vitest.config.ts, plus the commit hook suite.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jun 6, 2026, 9:09 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[aao-release-bot]

Approving. Documents four already-live mirror endpoints by hand-modeling their wire shape — the right move for SDK codegen, and the schemas track the real handler instead of an aspirational one.

Things I checked

• Schemas match the unchanged handler. CommunityMirrorGetResponse/PublishResponse/DeleteResponse/ListResponse line up field-for-field with community-mirrors.ts:135-142, :234-241, :286, and the list() DB projection. Nothing documented that the handler doesn't return.
• authorized_agents: [] is load-bearing, not cosmetic. CommunityMirrorAdagentsJsonSchema enforces .max(0) (registry.ts:292), matching the handler forcing authorized_agents: [] at community-mirrors.ts:196 so a mirror can never assert sales authorization. ad-tech-protocol-expert confirmed an empty array is valid per canonical adagents.json:227 and the anyOf guard at 718-727 — the .max(0) tightening stays inside the published envelope.
• The 5-way publish union is the right shape. CommunityMirrorPublishRequestSchema requires exactly one non-empty formats|properties|placements|collections|signals (.min(1) per arm), correctly modeling the handler's hasCatalogContent check at community-mirrors.ts:176-181 and correctly excluding catalog_etag-only / tag-only bodies.
• Coverage test mount prefixes are correct. ROUTE_SOURCES maps registry-api.ts→/api and community-mirrors.ts→/api/registry, matching the actual mounts; all four mirror routes resolve after :param→{param} normalization. Test will pass.
• adagents.json enum fidelity. authorization_type, delegation_type, and publisher_properties.selection_type enums all match the canonical discriminator consts. superseded_by HTTPS-only matches adagents.json:175-179.
• Changeset present and minor — correct for additive, non-breaking OpenAPI documentation. Not a static/schemas/source/** change, so the oneOf audit and spec-drift gates don't apply.

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

• DTO is over-permissive vs. the canonical oneOf. AdagentsAuthorizedAgentSchema flattens all six authorization arms into one optional-everything object and doesn't enforce the per-arm companion requireds (e.g. property_ids required when authorization_type: property_ids, adagents.json:308-311), and leaves authorization_type optional where canonical requires it. Fine for a codegen DTO — just don't let any validator lean on this shape as authoritative.
• Reference-variant coverage. The model omits revoked_publisher_domains (adagents.json:99) and the authoritative_location URL-reference arm. Community mirrors are inline-only so this is almost certainly fine — worth a one-line note in the schema stating mirrors never emit the pointer variant.

Minor nits (non-blocking)

1. z.string().datetime() on timestamps. created_at/updated_at (registry.ts, Summary/Get/Publish) mandate strict ISO-8601. pg may surface a non-strict string; a generated client doing strict datetime parsing could reject a valid response. Harmless today (docs-only, never validates live), but z.string() mirrors reality more closely.
2. Changeset filename is 5384-community-mirror-openapi.md on PR #5385. Off by one. The contents are right; the name just points at a different number.

code-reviewer: no Blocker/Major, schemas faithfully match runtime. ad-tech-protocol-expert: sound-with-caveats, no wire divergence.

LGTM. Follow-ups noted below.