Add first-class FacetData type for OPDS feed facet groups (PP-3675)

[jonathangreen]

Description

Introduce a FacetData dataclass that groups facet links by their facet group, moving group-level metadata (group name, type) out of individual Link objects and into a dedicated container. This eliminates redundant per-link fields (facet_group, facet_group_type, active_sort) and removes the need to reconstruct groups at serialization time (e.g. via defaultdict in the OPDS2 serializer).

Key changes:

• New FacetData type in feed/types.py with group, type, and links fields
• FeedData.facet_links: list[Link] replaced by FeedData.facets: list[FacetData]
• Facet grouping now happens in acquisition.py at construction time, not at serialization time
• OPDS facet rel (http://opds-spec.org/facet) moved from data layer into OPDS1 serializer where it belongs
• active-sort attribute extracted into an ACTIVE_SORT_ATTR constant
• Removed dead code: is_sort_facet(), palace_active_sort property, active_sort link field
• OPDS2 sort facets now render in the facets array (with @type) instead of as top-level feed links

OPDS2 Breaking Changes

Sort facets moved from top-level links[] to facets[]

Previously, sort options were serialized as individual top-level links with rel: "http://palaceproject.io/terms/rel/sort" and a palace_active_sort property. They now appear as a facet group inside the facets[] array, identified by "@type": "http://palaceproject.io/terms/rel/sort" in the facet metadata. The active sort option is indicated by "rel": "self" on its link (consistent with how all other active facets are marked).

// Before
{
  "links": [
    { "href": "...", "rel": "http://palaceproject.io/terms/rel/sort", "title": "Title",
      "properties": { "http://palaceproject.io/terms/properties/active-sort": true } }
  ]
}

// After
{
  "facets": [
    {
      "metadata": { "title": "Sort by", "@type": "http://palaceproject.io/terms/rel/sort" },
      "links": [
        { "href": "...", "rel": "self", "title": "Title",
          "properties": { "http://palaceproject.io/terms/properties/default": true } }
      ]
    }
  ]
}

Removed palace_active_sort link property

The http://palaceproject.io/terms/properties/active-sort property has been removed from OPDS2 link properties. Active sort/facet state is now uniformly communicated via "rel": "self" on the active link within a facet group.

Impact

These changes only affect the OPDS2 feed format. The only current OPDS2 consumer is Aspen, which does not use sort or entrypoint facet links, so these changes should have no practical impact. OPDS1 v1 and v2 feeds are unaffected by the structural changes (sort links and facet attributes are serialized as before).

Motivation and Context

The previous design stored group-level metadata (group name, group type) redundantly on every individual facet Link. This meant serializers had to reconstruct the grouping by inspecting link attributes, and format-specific concerns (like the OPDS1 facet rel) leaked into the shared data layer. The new FacetData type models the one-to-many relationship between a facet group and its links directly, making the code cleaner and less error-prone.

How Has This Been Tested?

• All existing tests updated to use the new FacetData structure
• New test assertions verify facet rel is set by the OPDS1 serializer
• Tests cover OPDS1 v1, OPDS1 v2, and OPDS2 serialization paths

Checklist

• I have updated the documentation accordingly.
• All new and existing tests passed.

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.24%. Comparing base (94fba06) to head (3393a8c).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/palace/manager/feed/acquisition.py	94.44%	0 Missing and 1 partial ⚠️
src/palace/manager/feed/serializer/opds.py	95.65%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3109   +/-   ##
=======================================
  Coverage   93.23%   93.24%           
=======================================
  Files         492      492           
  Lines       45429    45404   -25     
  Branches     6250     6245    -5     
=======================================
- Hits        42357    42335   -22     
+ Misses       1984     1983    -1     
+ Partials     1088     1086    -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jonathangreen]

This works, but there is some duplication here, that I want to resolve. I'm going to handle this by doing a bit of a refactor in a follow up PR. So I kept the changes here minimal for now.

Edit: PR here: #3119

[tdilauro]

This looks good! 🎉

[tdilauro]

Minor - The PR description mentioned that active_sort was extracted into an ACTIVE_SORT_ATTR constant. Although, looking through at least the changes on this PR, it looks like this is the only occurrence left.

[jonathangreen]

Yah, I changed this up after I opened the PR and forgot to update the description. I think whats here is more consistent with the existing code.