sylius-api-catalog — the catalog and the way to it.

A catalog nobody finds is not a discovery mechanism

Catalog and Link headers are deliberately in one package. In §3, RFC 9727 defines the Link header as the way a client discovers the catalog in the first place — it is the same data in two serialisations, not two features. Split across two packages, either half could be installed on its own: a catalog nothing points to, or headers that point to nothing. Both cases look like a broken implementation when checked from the outside.

The catalog lists what the installed bundles register, without knowing them. That means there is no central list to be updated for every new endpoint — and no coupling in the wrong direction, where the generic catalog package would have to hard-reference its own consumers. A bundle added later shows up in the catalog without this package being changed.

Link headers are appended, never replaced. Sylius and API Platform set their own Link headers, among other things for Hydra and preload hints. A header that overwrites is a bug that establishes one discovery path while destroying another — and one that goes unnoticed in an isolated test, because there simply are no other headers there.