docs: HTTPRoute attachment contract for Datum gateways (spec.hostnames rejected)

[ecv]

Problem

A consumer attaching an HTTPRoute to a Datum Gateway the normal Gateway-API way — with spec.hostnames set — gets rejected by the admission webhook:

spec.hostnames: Forbidden: hostnames are not permitted

This is intentional and temporary (the validator notes hostnames "will be allowed in the future"), but it is undocumented. There is no docs/api/httproutes.md, so the HTTPRoute attachment contract for Datum gateways lives only in code:

https://github.com/datum-cloud/network-services-operator/blob/main/internal/validation/httproute_validation.go

A consumer reading only this repo's docs cannot tell this rejection from a bug. It cost real time diagnosing it live against a gateway custom-hostname cert e2e (datum-cloud/infra#3473), and it is the same class of "model only lived as tribal infra knowledge" gap called out in #269.

What to document

A short docs/api/httproutes.md (or a section in the gateway docs) covering the HTTPRoute-to-Gateway attachment contract, at minimum:

• spec.hostnames is currently rejected (hostnames are not permitted) — the route inherits the hostname from the Gateway listener it attaches to; do not set it on the route. Note this is a temporary restriction.
• Any other Datum-specific deviations the validator enforces beyond upstream Gateway API (worth a pass over internal/validation/httproute_validation.go and internal/webhook/v1/gateway_webhook.go).

Related

#269
#219
https://github.com/datum-cloud/infra/issues/3473