feat(openapi): describe the property-catalog fact-contribution endpoints

[bokelley]

The prerequisite that makes the SDK "send us facts" surface typeable — the "canonical registry spec" that adcontextprotocol/adcp-client#2317 explicitly defers to.

Problem

The catalog fact endpoints (POST /api/registry/resolve, /catalog/disputes) are live and serve real traffic, but catalog-api.ts registered zero OpenAPI paths — the whole router was absent from static/openapi/registry.yaml. Since SDK clients generate their types from the published OpenAPI (adcp-client's types.generated.ts sources https://agenticadvertising.org/openapi/registry.yaml), the primary fact-contribution surface (reportIdentifiers/disputeFact in #5782) couldn't be typed at all.

Change (documentation of live endpoints — no behavior change)

• New server/src/schemas/catalog-openapi.ts (mirrors the member-agents-openapi.ts pattern — standalone so the generator imports it without route-factory deps). Registers:
  • resolveIdentifiers — POST /api/registry/resolve (the primary fact funnel)
  • fileCatalogDispute — POST /api/registry/catalog/disputes
  • getCatalogDispute — GET /api/registry/catalog/disputes/{id}
• Schemas mirror the live Zod validators + result types exactly: the provenance enum, identifiers[1..10000] cap, ResolveResponse.summary's five fields (incl not_found), and the dispute TriageResult ({dispute_id, action_taken, reason}).
• property_rid documented as a non-authoritative join/match handle, never an authorization credential (the fix(registry): enforce identity-not-authorization on property-save (#5749 gap #2) #5750 identity-not-authorization lesson).
• Wired into scripts/generate-openapi.ts + a "Property Catalog" tag; regenerated registry.yaml.

Where it fits

• Migrate test kits to declare auth.api_key / auth.probe_task for security_baseline #2317 (adcp-client): saveProperty identity facts — the identity contribute-back slice.
• This PR (adcp): the OpenAPI landing Migrate test kits to declare auth.api_key / auth.probe_task for security_baseline #2317 defers to; once published, the SDK regenerates types.
• Next (adcp-client): add reportIdentifiers() / disputeFact() on top — the primary "send us facts" funnel from RFC docs(specs): RFC for the SDK fact-contribution surface #5782, which this unblocks.

Read-side OpenAPI (browse/sync) is a fast follow-on. Validated: npm run build:openapi regenerates cleanly; typecheck clean; unit suite green.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jul 1, 2026, 1:13 PM

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

[aao-release-bot]

Accurate documentation of three already-live endpoints — the schemas mirror the runtime, which is the whole job of an OpenAPI-registration PR. Approving: this makes the fact-contribution surface typeable for SDK codegen without touching a single wire behavior.

Things I checked

• Request validators mirror the routes exactly. ResolveRequest (identifiers.min(1).max(10000), the 8-value provenance enum, mode default resolve) matches catalog-api.ts:58-70; CatalogDisputeRequest (claim 10–2000, evidence ≤5000 optional) matches catalog-api.ts:72-78.
• Response shapes mirror the result types. ResolveResponse/ResolvedEntry — nullable property_rid/source, status enum existing|created|excluded, the five-field summary including not_found — matches catalog-db.ts:72-90 and the return at :298-308. CatalogDisputeTriageResult's action_taken enum matches catalog-governance.ts:29-33.
• Auth annotations match the handlers. Resolve documents security + a 401 and requires req.user only in resolve mode (catalog-api.ts:169-171); disputes POST requires auth (catalog-api.ts:533); GET dispute is correctly annotation-free because the handler has no gate.
• No changeset required. static/openapi/** and scripts/generate-openapi.ts are deliberately outside the release/versioning path (.github/workflows/release.yml:65 scopes it to static/schemas/source/, static/compliance/source/, and named build scripts). This is the registry REST surface, not the AdCP wire schemas — static/schemas/source/** is untouched.
• property_rid framing is load-bearing and consistent. Documented as a non-authoritative join/match handle, never an authorization credential, in both the field and operation descriptions — the #5750 identity-not-authorization lesson, correctly carried.

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

• Public GET on /catalog/disputes/{id} returns reporter PII. The handler does SELECT * and returns the row verbatim (catalog-api.ts:559-570), so reported_by_email ships on an unauthenticated read. CatalogDisputeRecord doesn't document that field, so .passthrough() hides the leak from the contract rather than fixing it. Pre-existing route behavior, not introduced here — so not a block on a docs PR — but this is the moment the endpoint becomes a published surface. Route should stop returning reporter email on the public path; keep it out of the documented schema either way. Worth its own issue.
• CatalogDisputeRecord under-specifies the read. The row carries stable columns (resolution, resolved_by, resolved_at, updated_at; catalog-disputes-db.ts:8-23) that .passthrough() leaves untyped for SDK consumers. Pinning them (minus PII, per above) would give the disputes-read surface a real generated type.
• summary.resolved double-counts created. It's computed as existing + created (catalog-db.ts:296-306), so an SDK author summing resolved + created + excluded against total will be off. One line on the field description prevents the misuse.

Minor nits (non-blocking)

1. status example 'suspended' can never occur. DisputeRecordSchema.status uses example: 'suspended', but a dispute status is open|investigating|resolved|rejected|escalated (catalog-disputes-db.ts:26), and fileDispute sets it to investigating (catalog-governance.ts:60/71/82). link_suspended is an action_taken value on the triage result — the example crossed the two surfaces. Change it to investigating.

LGTM. Follow-ups noted below — the PII one deserves a separate fix, not a comment on this PR.