fix(a2a): set each refusal reason at its raise site, not by matching prose (ent#397)

[dolho]

Stacked on #2181 (ent#399) → #2180 (ent#398). All three touch url_validation /
_same_origin. The reviewable diff is the last commit; bases collapse to dev as the
stack merges.

What this fixes

validate_a2a_endpoint_url derived its machine-readable reason by substring-matching its
own human message — the fragility A2AEndpointUrlError's docstring explicitly warns about.
The DNS-failure message interpolates the hostname, and canonical_host passes hosts
containing spaces, so https://an internal address.example/a2a — a host that merely failed
to resolve — was reported endpoint_private_address.

No bypass: both refusals map to the same HTTP status. The cost is diagnostic, and structural
— the operator is told the opposite of what happened, any consumer branching on reason
branches wrongly, and a code reconstructed from prose is not machine-readable.

Changes

• PublicUrlRefusal(kind, message), raised at all nine refusal sites in
  _validate_public_https_url: invalid, not_https, credentials, private_address,
  dns_failure.
• The A2A wrapper maps kind → reason through one table (_A2A_REASON_BY_KIND) with no
  string inspection. credentials keeps mapping to endpoint_invalid — the code it has
  always carried; inventing a new one would change the route's HTTP mapping under a bug fix.
• PublicUrlRefusal subclasses ValueError, so the template-registry validator (which
  lets it propagate) is unchanged in type and message text — pinned by test.
• A ValueError without a kind still becomes endpoint_invalid — honest about not
  knowing which refusal it was, rather than guessing from the prose.

Verification on real code

                                                          dev                      this branch
DNS-fails, name contains "internal address"   endpoint_private_address   endpoint_dns_failure
DNS-fails, name contains "could not be…"      endpoint_dns_failure       endpoint_dns_failure
ordinary DNS failure                          endpoint_dns_failure       endpoint_dns_failure
really resolves to 10.0.0.7                   endpoint_private_address   endpoint_private_address
http:// endpoint                              endpoint_not_https         endpoint_not_https
junk port                                     endpoint_invalid           endpoint_invalid

Only the defective cell moves.

Tests

tests/unit/test_ent397_refusal_reasons.py — 23 cases:

• test_D12_a_dns_failure_is_never_misreported_as_a_private_address — the AC-named test,
  plain. The sibling pin is on the PR fix(security): mapped-CGNAT bypassed the SSRF destination predicate (ent#393) #2178 branch, not on dev; it must be un-xfailed
  when fix(security): mapped-CGNAT bypassed the SSRF destination predicate (ent#393) #2178 lands. This file holds the property meanwhile.
• every phrase the old matcher keyed on, spelled as a hostname (must use HTTPS.example,
  could not be resolved.example, …)
• one case per refusal path: empty, whitespace, over the length cap, http://, non-https
  scheme, embedded credentials, junk port, out-of-range port, missing host, unparseable
  resolver record, empty resolver result
• an AST guard that no raise site in _validate_public_https_url reverts to a bare
  ValueError — the defect's return path
• a kind→reason coverage check (no kind may reach the endpoint_invalid default by accident)
• the template-registry caller's unchanged type/text
• the topology-oracle property (test_refusal_message_never_echoes_the_resolved_address,
  named in the AC) plus the counterpart: the DNS message still names the host the operator
  typed, since that interpolation is the vector, not the defect

Green: 23 new, 1198 across every A2A / URL-validation / registry / skills-library / template
suite.

Related observation (not fixed here)

https:// peer.example.com/a2a — an authority with a leading space — is accepted on dev
and on this branch: canonical_host strips it, so the connection goes to the right host
while the stored URL keeps the space. That is the same "canonical_host passes hosts
containing spaces" property this issue names as its vector, but tightening it is a separate
behaviour change and out of scope here. Happy to file it.

Related to trinity-enterprise#397

[vybe]

Validated via /validate-pr, plus merge-integration work.

The fix is right and the reasoning in the description holds up. Deriving a machine-readable code by substring-matching a human message that interpolates an attacker-influenced hostname is the fragility A2AEndpointUrlError's own docstring warns against; PublicUrlRefusal(kind, message) set at all nine raise sites, mapped through one table with no string inspection, is the correct shape. Three details I checked specifically:

• PublicUrlRefusal subclasses ValueError, so the template-registry validator — which lets it propagate — is unchanged in both type and message text.
• credentials → endpoint_invalid preserves the code that refusal has always carried, so no route's HTTP mapping moves under a bug fix.
• The bare-ValueError fallback still answers endpoint_invalid rather than guessing from prose, which is the honest answer.

Verified at runtime that _A2A_REASON_BY_KIND covers every declared kind and that its values, A2A_URL_REASONS and the router's status map all agree.

Security clean, no packaging gaps, 3 files.

Three things needed to land it:

1. Retargeted to dev and merged dev in. url_validation.py and mcp.md were add-vs-nothing (kept ours; FR-3a sits after #2181's FR-4b, no duplication). test_ent399_ipv6_origin.py came through add/add because #2181 landed as a squash, so the stacked commit and the merged one are different objects — took dev's copy verbatim, since this PR doesn't touch that file.

2. Un-xfailed F3 in test_736_a2a_outbound_edges.py — #2178 pins it strict=True, so this fix made it XPASS and CI would have gone red. Per the file's own convention: marker deleted, tracker row FIXED.

3. H1 needed the same treatment, and this one is worth a look. _endpoint_url_reasons() regex-scans url_validation.py for literal A2AEndpointUrlError("...") raise sites — which is precisely the shape this PR removes. With two reasons now produced via the table, the literals-only scan under-reported and H1 declared endpoint_private_address a dead map entry while the router still maps it correctly. I taught the helper to read both production sites, so it measures what the module emits rather than how it spells it. Flagging because it's the sort of guard that looks like it caught a regression when it actually caught its own assumption.

Green locally: 1366 passed across the a2a / url-validation / registry / template suites; lint 169/240, no new violations.

Note: Related to trinity-enterprise#397 is cross-tracker, so ent#397 won't auto-promote — bumping it manually.

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.