feat(ra): AI Catalog generation, FQDN exclusivity, and seal-before-success activation

[csnitker-godaddy]

Summary

Adds producer-side AI Catalog artifact generation to the RA, plus the two invariants it depends on. Every byte is derived from the registration aggregate — nothing crawled, nothing fetched — and the registration request and 202 response are untouched.

What's in this PR

1. AI Catalog generation (IMPL slices 1–2)

• internal/catalog (pure, no I/O): the per-agent CatalogEntry and the host-complete ai-catalog.json document. Eligibility gates (versioned, ACTIVE, an A2A/MCP endpoint with a policy-passing metaDataUrl), single vs nested entries, leftmost-DNS-label URN, Cc/Cf text sanitization, and an emitted-URL policy (absolute https, host == agentHost, no userinfo/query/fragment).
• Routes (owner-scoped via ReadOwnership):
  • GET /v2/ans/agents/{agentId}/catalog-entry — the bare entry (application/json).
  • GET /v2/ans/agents/{agentId}/ai-catalog — the host-complete document (application/ai-catalog+json) with a strong ETag + If-None-Match/304. This is the literal ai-catalog.json an Agent-Host Provider republishes at https://{agentHost}/.well-known/ai-catalog.json.
• spec/api-spec-v2.yaml and the embedded docsui copy updated.

2. FQDN exclusivity (one-host-one-owner)

Once a registration is live (ACTIVE/DEPRECATED) on an FQDN, a different owner may not register or activate on it — checked at register, verify-acme, and verify-dns. On activation the winner cancels losing pending registrations (no TL event, ANS-1 §4.4).

3. Seal-before-success activation (ANS-1 §12.3)

verify-dns seals the single terminal AGENT_REGISTERED event inline and reports ACTIVE only after the TL acknowledges. A failing or unconfigured sealer fails closed: 503 TL_UNAVAILABLE, the agent stays PENDING_DNS, nothing is committed, no outbox row. Revocation still rides the outbox. This is what guarantees a catalogued agent's SCITT-receipt and badge links point at TL records that actually exist.

The ai-catalog.json (the deliverable)

scripts/demo/ai-catalog.sh builds one host with a mixed population and saves the validated document to data/demo/ai-catalog.json:

agent	status	in document
v1.0.0 MCP + metaDataUrl	ACTIVE, eligible	✅
v2.0.0 A2A + metaDataUrl	ACTIVE, eligible	✅
v3.0.0 HTTP-API (no card)	ACTIVE, ineligible	❌
v4.0.0 MCP	PENDING	❌
eligible agent on a different host	ACTIVE	❌

It asserts host-completeness, the host object, sorted-by-version, per-card mediaType, the agent-scoped alias (byte-identical via any agentId), a deterministic ETag, and 304.

Quality gates

• make check green at 90.2% coverage (internal/catalog at 100%); go test -race clean on the affected packages.
• Demos pass end-to-end: run-lifecycle.sh (V2), run-lifecycle-v1.sh (V1), catalog.sh (per-agent entry), ai-catalog.sh (host document).
• Pre-push adversarial review across five dimensions (shape/contract, correctness, security, quality-bar, tests) with each finding independently verified; confirmed findings addressed in this PR (mostly comment/test accuracy), refuted findings documented.

Known limitations / follow-ups

• FQDN exclusivity is best-effort under concurrency. Two different owners each holding a PENDING_DNS registration on the same FQDN can race verify-dns and both reach ACTIVE (the check runs before the inline seal and outside the activation tx). An in-tx re-check would trade this for a sealed-but-not-activated orphan under seal-before-success, so the proper fix is a pre-seal host claim (mirroring the identity lane's nonce claim) — deferred. Documented in preflightRegistrationConflicts. The owner-scoped catalog read contains the blast radius.
• Public discovery route not built. IMPL §6 models the catalog routes as public/unauthenticated; per an earlier maintainer call these are owner-scoped behind auth. The genuinely public host-discovery route GET /v2/ans/catalog?agentHost= (IMPL slice 3) is unbuilt — that's the surface an AHP fetches without owner credentials.
• Catalog updatedAt uses registration/last-renewal time as a documented proxy for the spec's "activation/latest seal timestamp" (the RA persists no activation timestamp; the field is optional).

🤖 Generated with Claude Code

[liady]

One small note - ARD spec v0.9 specifies urn:air: as the identifier prefix instead ofurn:ai:.

[Copilot]

Pull request overview

This PR adds producer-side AI Catalog artifact generation to the RA (per-agent entry + host-complete document), and introduces two supporting invariants: FQDN exclusivity across owners and seal-before-success activation (inline TL seal before reporting ACTIVE).

Changes:

• Add internal/catalog (pure generation) plus authenticated RA routes to serve a CatalogEntry and host-complete ai-catalog.json with ETag/304.
• Enforce one-host-one-owner for live (ACTIVE/DEPRECATED) registrations and cancel conflicting pending registrations on winner activation.
• Change activation (verify-dns) to seal AGENT_REGISTERED inline (fail closed with TL_UNAVAILABLE) and update demos/tests/spec accordingly.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
spec/api-spec-v2.yaml	OpenAPI updates for AI Catalog routes, new schemas, and new 409/503 semantics.
internal/adapter/docsui/openapi/ra.yaml	DocsUI OpenAPI mirror of the v2 spec changes.
internal/catalog/catalog.go	New core types/constants for AI Catalog entry/document shapes.
internal/catalog/generate.go	Build CatalogEntry from registration aggregate with eligibility gates and sanitization.
internal/catalog/document.go	Build host-complete document and deterministic sorting for stable ETags.
internal/catalog/sanitize.go	Strip Cc/Cf runes from emitted text and sanitize tags.
internal/catalog/urlpolicy.go	Enforce emitted metaDataUrl policy (https, same host, no userinfo/query/fragment).
internal/catalog/generate_test.go	Tests for entry generation, nesting, gating, sanitization, and TL base URL behavior.
internal/catalog/document_test.go	Tests for host document inclusion rules and deterministic ordering.
internal/catalog/sanitize_test.go	Tests for Cc/Cf stripping and tag de-duplication.
internal/catalog/urlpolicy_test.go	Tests for emitted URL policy enforcement.
internal/ra/handler/catalog.go	New authenticated handlers for /catalog-entry and /ai-catalog including ETag/304.
internal/ra/handler/catalog_test.go	HTTP-level tests for catalog routes, ownership scoping, and conditional GET behavior.
internal/ra/handler/sealer_test.go	Test sealer implementation to capture inline-sealed agent events at the handler layer.
internal/ra/handler/lifecycle_test.go	Update lifecycle tests for inline sealing; add FQDN exclusivity and 503-on-seal-failure tests.
internal/ra/handler/v1lifecycle_test.go	Update V1 lifecycle tests to expect inline sealing (outbox empty for activation).
internal/ra/service/registration.go	Add conflict preflight (ANS name + host), host exclusivity helpers, and inline activation sealing plumbing.
internal/ra/service/lifecycle.go	Implement inline TL seal-before-success on verify-dns; cancel conflicting pending registrations in-tx.
internal/ra/service/sealer_test.go	Test sealer implementation to capture inline-sealed agent events at the service layer.
internal/ra/service/registration_test.go	Fixture updates to wire the new agent sealer into service tests.
internal/ra/service/order_flow_test.go	Update tests to read sealed activation events from the sealer instead of the outbox.
internal/ra/service/lifecycle_test.go	Update activation tests for inline sealing; add fail-closed coverage for seal failures / nil sealer.
internal/ra/service/hostcatalog_test.go	White-box tests for owner-scoped HostRegistrations and host exclusivity helpers.
internal/domain/agent.go	Add CancelForHostConflict to cancel pending registrations without emitting a TL event.
internal/domain/agent_test.go	Tests for CancelForHostConflict semantics (no event, pending-only).
internal/adapter/tlclient/client.go	Add SealAgentEvent client method with transient/permanent error mapping.
cmd/ans-ra/main.go	Wire TL sealer and TL public base URL into services; register catalog routes.
scripts/demo/common.sh	Add shared AI catalog demo helpers and TL public base env var.
scripts/demo/run-lifecycle.sh	Demo updates for inline sealing confirmation and catalog route validation.
scripts/demo/run-lifecycle-v1.sh	Demo updates for inline sealing confirmation on the V1 lane.
scripts/demo/catalog.sh	New demo script for per-agent catalog-entry scenarios (eligible/ineligible).
scripts/demo/ai-catalog.sh	New demo script for host-complete document generation + ETag/304 assertions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kperry-godaddy]

Connor — this is a strong PR. The seal-before-success mechanics are genuinely well built (fail-closed nil-sealer handling, the seal running outside the write lock, byte-exact payload persisted onto the pre-delivered feed row), the host document is correctly owner-scoped at both the handler and service layers, the byte-pinned golden test against the spec is exactly how we keep wire shapes honest, and the test-enforced docsui sync eliminated a whole class of review work. The comments in the tricky spots are candid about their trade-offs, which made this a pleasure to review.

I've left seven inline comments on things I'd like us to resolve before merge: two correctness edges on the new exclusivity invariant (the race window has consequences beyond the documented one, including a certificate-lifecycle gap), two observability gaps on the new activation lane, and three wire-contract items. Every one of them looks like a contained, mechanical fix — no redesign anywhere. Happy to pair on any of them.

[kperry-godaddy]

Approving — this is excellent follow-through, Connor. Every item landed as a real fix rather than a patch-over:

• commitActivation makes host exclusivity authoritative at commit time, and the new race tests pin both interleavings (including the no-wedge retry) via the seal-round-trip hook — really nice test design.
• The loser certificate lifecycle now mirrors cancelPending end to end, and the self-healing sweep turns the previously-unreachable state into a repair path.
• internal/ard is the right structural answer to the duplication: the one-identifier invariant is now enforced by the import graph instead of by comments.
• The seal/cancellation logging (with the transport cause preserved at the client boundary) and the Problem schema both landed exactly where they needed to.

Verified on my side: make check green at 90.7% coverage, go test -race clean across every touched package, and the docsui copy still byte-identical to spec/.

Two tiny non-blocking notes so they're recorded for a follow-up: (1) a rival whose verify-acme commits inside the window between the pre-tx CA pass and the activation transaction gets its cert rows correctly flipped in-store but misses the CA-side revocation — and the sweep can't see that case, since it keys on store-VALID rows. Having commitActivation return the certs it flipped and CA-revoking exactly that set post-commit (idempotent) would close it completely. (2) A concurrent duplicate verify-dns for the same agent now surfaces the second commit as AGENT_HOST_TAKEN, which reads as "another operator" for your own now-ACTIVE agent — cosmetic, and a retry self-corrects via the idempotent branch. Neither needs to hold this up. And yes to your offer on pulling sanitizeText into internal/ard — that finishes the trio.

Great work. 🚢