Address review feedback: restore validation, scope aggregation to queryset

- Restore the document_count_source_field validation helper dropped during
  the refactor -- misconfiguring a viewset (document_count_through set
  without document_count_source_field) now fails fast with a clear error
  again instead of an obscure runtime failure.
- Restrict annotate_document_count_for_related_queryset()'s through-table
  aggregation to rows whose related_object_field is one of the annotated
  queryset's pks. No-op for the main tag-list call site (queryset is all
  tags), but avoids unnecessary work for narrower callers like the tag
  descendants branch in TagViewSet.list().

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

src-ui/messages.xlf

@@ -11515,21 +11515,21 @@
         <source>Successfully completed one-time migratration of settings to the database!</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/services/settings.service.ts</context>
-          <context context-type="linenumber">636</context>
+          <context context-type="linenumber">635</context>
         </context-group>
       </trans-unit>
       <trans-unit id="5558341108007064934" datatype="html">
         <source>Unable to migrate settings to the database, please try saving manually.</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/services/settings.service.ts</context>
-          <context context-type="linenumber">637</context>
+          <context context-type="linenumber">636</context>
         </context-group>
       </trans-unit>
       <trans-unit id="1168781785897678748" datatype="html">
         <source>You can restart the tour from the settings page.</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/services/settings.service.ts</context>
-          <context context-type="linenumber">709</context>
+          <context context-type="linenumber">708</context>
         </context-group>
       </trans-unit>
       <trans-unit id="3852289441366561594" datatype="html">

src-ui/src/app/components/chat/chat/chat.component.html

@@ -16,7 +16,7 @@
               @if (message.role === 'assistant' && message.references?.length) {
                 <div class="chat-references list-group mt-3">
                   @for (reference of message.references; track reference.id) {
-                    <a class="list-group-item list-group-item-action text-primary" [routerLink]="['/documents', reference.id]">
+                    <a class="list-group-item list-group-item-action d-flex text-primary text-break" [routerLink]="['/documents', reference.id]">
                       <i-bs width="0.9em" height="0.9em" name="file-text" class="me-1"></i-bs><span>{{ reference.title }}</span>
                     </a>
                   }

src-ui/src/app/services/settings.service.ts

@@ -17,7 +17,7 @@ import {
   estimateBrightnessForColor,
   hexToHsl,
 } from 'src/app/utils/color'
-import { environment } from 'src/environments/environment'
+import { DEFAULT_APP_TITLE, environment } from 'src/environments/environment'
 import { DEFAULT_DISPLAY_FIELDS, DisplayField } from '../data/document'
 import { SavedView } from '../data/saved-view'
 import {
@@ -359,9 +359,8 @@ export class SettingsService {
       }),
       tap((uisettings) => {
         this.assignSafeSettings(uisettings.settings)
-        if (this.get(SETTINGS_KEYS.APP_TITLE)?.length) {
-          environment.appTitle = this.get(SETTINGS_KEYS.APP_TITLE)
-        }
+        environment.appTitle =
+          this.get(SETTINGS_KEYS.APP_TITLE) || DEFAULT_APP_TITLE
         this.maybeMigrateSettings()
         // to update lang cookie
         if (this.settings['language']?.length)

src-ui/src/environments/environment.prod.ts

@@ -1,10 +1,12 @@
 const base_url = new URL(document.baseURI)
 
+export const DEFAULT_APP_TITLE = 'Paperless-ngx'
+
 export const environment = {
   production: true,
   apiBaseUrl: document.baseURI + 'api/',
   apiVersion: '10', // match src/paperless/settings.py
-  appTitle: 'Paperless-ngx',
+  appTitle: DEFAULT_APP_TITLE,
   tag: 'prod',
   version: '3.0.0',
   webSocketHost: window.location.host,

src-ui/src/environments/environment.ts

@@ -2,11 +2,13 @@
 // `ng build --configuration production` replaces `environment.ts` with `environment.prod.ts`.
 // The list of file replacements can be found in `angular.json`.
 
+export const DEFAULT_APP_TITLE = 'Paperless-ngx'
+
 export const environment = {
   production: false,
   apiBaseUrl: 'http://localhost:8000/api/',
   apiVersion: '10',
-  appTitle: 'Paperless-ngx',
+  appTitle: DEFAULT_APP_TITLE,
   tag: 'dev',
   version: 'DEVELOPMENT',
   webSocketHost: 'localhost:8000',

src/documents/permissions.py

@@ -4,14 +4,14 @@ from django.contrib.auth.models import Group
 from django.contrib.auth.models import Permission
 from django.contrib.auth.models import User
 from django.contrib.contenttypes.models import ContentType
+from django.db.models import Case
 from django.db.models import Count
 from django.db.models import IntegerField
-from django.db.models import OuterRef
 from django.db.models import Q
 from django.db.models import QuerySet
-from django.db.models import Subquery
+from django.db.models import Value
+from django.db.models import When
 from django.db.models.functions import Cast
-from django.db.models.functions import Coalesce
 from guardian.core import ObjectPermissionChecker
 from guardian.models import GroupObjectPermission
 from guardian.models import UserObjectPermission
@@ -204,20 +204,24 @@ def _permitted_document_ids(user):
     ).values_list("id", flat=True)
 
 
-def get_document_count_filter_for_user(user):
+def get_document_count_filter_for_user(user, related_name: str = "documents"):
     """
     Return the Q object used to filter document counts for the given user.
 
     The filter is expressed as an ``id__in`` against a small subquery of permitted
     document IDs to keep the generated SQL simple and avoid large OR clauses.
+
+    ``related_name`` is the ORM path from the annotated model to Document (e.g.
+    ``"documents"`` for Tag's direct M2M, or ``"fields__document"`` for CustomField,
+    which only reaches Document via the CustomFieldInstance through-model).
     """
 
     if getattr(user, "is_superuser", False):
         # Superuser: no permission filtering needed
-        return Q(documents__deleted_at__isnull=True)
+        return Q(**{f"{related_name}__deleted_at__isnull": True})
 
     permitted_ids = _permitted_document_ids(user)
-    return Q(documents__id__in=permitted_ids)
+    return Q(**{f"{related_name}__id__in": permitted_ids})
 
 
 def annotate_document_count_for_related_queryset(
@@ -228,14 +232,33 @@ def annotate_document_count_for_related_queryset(
     user: User | None = None,
 ) -> QuerySet[Any]:
     """
-    Annotate a queryset with permissions-aware document counts using a subquery
-    against a relation table.
+    Annotate a queryset with a permissions-aware document count for a relation
+    to Document that goes through an M2M/through-model table (e.g. Tag via
+    ``Document.tags.through``, or CustomField via ``CustomFieldInstance``).
+
+    Counts are computed via a single, independent GROUP BY over the relation
+    table -- with the permission filter expressed as a plain ``WHERE`` rather
+    than an aggregate ``FILTER`` -- then injected via ``Case``/``When``. This
+    deliberately avoids two slower alternatives found while building this:
+
+    - A per-outer-row correlated subquery (one execution per row of the
+      annotated queryset): fine at a handful of rows, catastrophic once the
+      queryset has hundreds/thousands of rows.
+    - ``Count(..., filter=Q(id__in=permitted_ids), distinct=True)`` applied
+      directly to the M2M relation: Postgres can fail to plan the ``id__in``
+      check as a semi-join and instead re-checks subquery membership once per
+      row of the (much larger) M2M join -- worse than the correlated subquery.
+
+    Aggregation is restricted to rows whose ``related_object_field`` is one of
+    ``queryset``'s pks, so passing a subset (e.g. a handful of tag descendants)
+    doesn't pay the cost of counting for every row matching the permission
+    filter.
 
     Args:
         queryset: base queryset to annotate (must contain pk)
         through_model: model representing the relation (e.g., Document.tags.through
                        or CustomFieldInstance)
-        source_field: field on the relation pointing back to queryset pk
+        related_object_field: field on the relation pointing back to queryset pk
         target_field: field on the relation pointing to Document id
         user: the user for whom to filter permitted document ids
     """
@@ -244,15 +267,27 @@ def annotate_document_count_for_related_queryset(
     counts = (
         through_model.objects.filter(
             **{
-                related_object_field: OuterRef("pk"),
+                f"{related_object_field}__in": queryset.values("pk"),
                 f"{target_field}__in": permitted_ids,
             },
         )
         .values(related_object_field)
-        .annotate(c=Count(target_field))
-        .values("c")
+        .annotate(c=Count(target_field, distinct=True))
+    )
+    counts_by_pk = {row[related_object_field]: row["c"] for row in counts}
+
+    if not counts_by_pk:
+        return queryset.annotate(
+            document_count=Value(0, output_field=IntegerField()),
+        )
+
+    return queryset.annotate(
+        document_count=Case(
+            *(When(pk=pk, then=Value(count)) for pk, count in counts_by_pk.items()),
+            default=Value(0),
+            output_field=IntegerField(),
+        ),
     )
-    return queryset.annotate(document_count=Coalesce(Subquery(counts[:1]), 0))
 
 
 def get_objects_for_user_owner_aware(

src/documents/serialisers.py

@@ -392,15 +392,34 @@ class OwnedObjectSerializer(
         }
 
     def get_user_can_change(self, obj) -> bool:
-        checker = ObjectPermissionChecker(self.user) if self.user is not None else None
-        return (
-            obj.owner is None
-            or obj.owner == self.user
-            or (
-                self.user is not None
-                and checker.has_perm(f"change_{obj.__class__.__name__.lower()}", obj)
+        if obj.owner is None or obj.owner == self.user:
+            return True
+        if self.user is None:
+            return False
+        if self.user.is_active and self.user.is_superuser:
+            # Mirrors guardian's own ObjectPermissionChecker.has_perm() shortcut --
+            # superusers aren't necessarily granted explicit object permissions,
+            # so the batched context below would otherwise incorrectly say no.
+            return True
+
+        # Prefer the page-level batch computed by BulkPermissionMixin
+        # (get_serializer_context) over a fresh per-object guardian check,
+        # which would otherwise query the permission tables once per row.
+        users_change_perms = self.context.get("users_change_perms")
+        groups_change_perms = self.context.get("groups_change_perms")
+        if users_change_perms is not None and groups_change_perms is not None:
+            if self.user.pk in users_change_perms.get(obj.pk, []):
+                return True
+            user_group_ids = getattr(self, "_user_group_ids", None)
+            if user_group_ids is None:
+                user_group_ids = set(self.user.groups.values_list("id", flat=True))
+                self._user_group_ids = user_group_ids
+            return bool(
+                user_group_ids.intersection(groups_change_perms.get(obj.pk, [])),
             )
-        )
+
+        checker = ObjectPermissionChecker(self.user)
+        return checker.has_perm(f"change_{obj.__class__.__name__.lower()}", obj)
 
     @staticmethod
     def get_shared_object_pks(objects: Iterable):

src/documents/tests/test_api_permissions.py

@@ -568,6 +568,30 @@ class TestApiAuth(DirectoriesMixin, APITestCase):
         self.assertNotIn("user_can_change", results[0])
         self.assertNotIn("is_shared_by_requester", results[0])
 
+    def test_superuser_user_can_change_without_explicit_grant(self) -> None:
+        """
+        A superuser has implicit change access to every document, even one
+        owned by someone else with no explicit guardian grant -- mirrors
+        guardian's own ObjectPermissionChecker.has_perm() superuser shortcut.
+        """
+        superuser = User.objects.create_superuser(username="admin")
+        other_user = User.objects.create_user(username="user2")
+        Document.objects.create(
+            title="Test",
+            content="content",
+            checksum="1",
+            owner=other_user,
+        )
+
+        self.client.force_authenticate(superuser)
+
+        response = self.client.get("/api/documents/", format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        results = response.json()["results"]
+        self.assertEqual(len(results), 1)
+        self.assertTrue(results[0]["user_can_change"])
+
     @mock.patch("allauth.mfa.adapter.DefaultMFAAdapter.is_mfa_enabled")
     def test_basic_auth_mfa_enabled(self, mock_is_mfa_enabled) -> None:
         """

src/documents/views.py

@@ -431,14 +431,12 @@ class BulkPermissionMixin:
         This avoid fetching permissions object by object in database.
         """
         context = super().get_serializer_context()
-        try:
-            full_perms = get_boolean(
-                str(self.request.query_params.get("full_perms", "false")),
-            )
-        except ValueError:
-            full_perms = False
 
-        if not full_perms:
+        if getattr(self, "action", None) != "list":
+            # Batching only pays off across a page of objects; for single-object
+            # actions (retrieve, update, ...) the per-object fallback in
+            # get_user_can_change()/_get_perms() is cheap and avoids scanning
+            # the whole queryset here.
             return context
 
         # Check which objects are being paginated
@@ -484,7 +482,15 @@ class BulkPermissionMixin:
 class PermissionsAwareDocumentCountMixin(BulkPermissionMixin, PassUserMixin):
     """Mixin to add document count to queryset, permissions-aware if needed"""
 
-    # Default is simple relation path, override for through-table/count specialization.
+    # Direct FK/M2M relation name from this model to Document, used for the
+    # cheap Count(filter=...) path (Correspondent, DocumentType, StoragePath).
+    document_count_related_name: str = "documents"
+
+    # Set both of these instead, for models that only reach Document through
+    # an M2M/through-model table (Tag, CustomField). A plain Count(filter=...)
+    # over such a relation is fine for a direct FK, but forces a much more
+    # expensive plan once an M2M bridge table is involved -- see
+    # annotate_document_count_for_related_queryset() for why.
     document_count_through: type[Model] | None = None
     document_count_source_field: str | None = None
 
@@ -500,12 +506,14 @@ class PermissionsAwareDocumentCountMixin(BulkPermissionMixin, PassUserMixin):
     def get_document_count_filter(self):
         request = getattr(self, "request", None)
         user = getattr(request, "user", None) if request else None
-        return get_document_count_filter_for_user(user)
+        return get_document_count_filter_for_user(
+            user,
+            related_name=self.document_count_related_name,
+        )
 
     def get_queryset(self):
         base_qs = super().get_queryset()
 
-        # Use optimized through-table counting when configured.
         if self.document_count_through:
             user = getattr(getattr(self, "request", None), "user", None)
             return annotate_document_count_for_related_queryset(
@@ -515,10 +523,13 @@ class PermissionsAwareDocumentCountMixin(BulkPermissionMixin, PassUserMixin):
                 user=user,
             )
 
-        # Fallback: simple Count on relation with permission filter.
         filter = self.get_document_count_filter()
         return base_qs.annotate(
-            document_count=Count("documents", filter=filter),
+            document_count=Count(
+                self.document_count_related_name,
+                filter=filter,
+                distinct=True,
+            ),
         )
 
 
@@ -943,6 +954,7 @@ class EmailDocumentDetailSchema(EmailSerializer):
     ),
 )
 class DocumentViewSet(
+    BulkPermissionMixin,
     PassUserMixin,
     RetrieveModelMixin,
     UpdateModelMixin,
@@ -2291,6 +2303,15 @@ class UnifiedSearchViewSet(DocumentViewSet):
             return SearchResultSerializer
         return DocumentSerializer
 
+    def get_serializer_context(self):
+        if self._is_search_request():
+            # BulkPermissionMixin.get_serializer_context() (inherited via
+            # DocumentViewSet) assumes it's batching permissions for a page of
+            # real Document instances. Tantivy search results are SearchHit/
+            # dict-like objects instead, so skip straight past it here.
+            return super(BulkPermissionMixin, self).get_serializer_context()
+        return super().get_serializer_context()
+
     def _get_active_search_params(self, request: Request | None = None) -> list[str]:
         request = request or self.request
         return [

src/locale/en_US/LC_MESSAGES/django.po

@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: paperless-ngx\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-07-22 15:44+0000\n"
+"POT-Creation-Date: 2026-07-23 04:03+0000\n"
 "PO-Revision-Date: 2022-02-17 04:17\n"
 "Last-Translator: \n"
 "Language-Team: English\n"
@@ -1351,49 +1351,49 @@ msgstr ""
 msgid "workflow runs"
 msgstr ""
 
-#: documents/serialisers.py:503 documents/serialisers.py:855
-#: documents/serialisers.py:2744 documents/views.py:297 documents/views.py:2500
+#: documents/serialisers.py:522 documents/serialisers.py:874
+#: documents/serialisers.py:2763 documents/views.py:297 documents/views.py:2508
 #: paperless_mail/serialisers.py:155
 msgid "Insufficient permissions."
 msgstr ""
 
-#: documents/serialisers.py:691
+#: documents/serialisers.py:710
 msgid "Invalid color."
 msgstr ""
 
-#: documents/serialisers.py:2216
+#: documents/serialisers.py:2235
 #, python-format
 msgid "File type %(type)s not supported"
 msgstr ""
 
-#: documents/serialisers.py:2260
+#: documents/serialisers.py:2279
 #, python-format
 msgid "Custom field id must be an integer: %(id)s"
 msgstr ""
 
-#: documents/serialisers.py:2267
+#: documents/serialisers.py:2286
 #, python-format
 msgid "Custom field with id %(id)s does not exist"
 msgstr ""
 
-#: documents/serialisers.py:2284 documents/serialisers.py:2294
+#: documents/serialisers.py:2303 documents/serialisers.py:2313
 msgid ""
 "Custom fields must be a list of integers or an object mapping ids to values."
 msgstr ""
 
-#: documents/serialisers.py:2289
+#: documents/serialisers.py:2308
 msgid "Some custom fields don't exist or were specified twice."
 msgstr ""
 
-#: documents/serialisers.py:2436
+#: documents/serialisers.py:2455
 msgid "Invalid variable detected."
 msgstr ""
 
-#: documents/serialisers.py:2800
+#: documents/serialisers.py:2819
 msgid "Duplicate document identifiers are not allowed."
 msgstr ""
 
-#: documents/serialisers.py:2830 documents/views.py:4459
+#: documents/serialisers.py:2849 documents/views.py:4467
 #, python-format
 msgid "Documents not found: %(ids)s"
 msgstr ""
@@ -1661,36 +1661,36 @@ msgstr ""
 msgid "Unable to parse URI {value}"
 msgstr ""
 
-#: documents/views.py:290 documents/views.py:2497
+#: documents/views.py:290 documents/views.py:2505
 msgid "Invalid more_like_id"
 msgstr ""
 
-#: documents/views.py:1524
+#: documents/views.py:1523
 msgid "Invalid AI configuration."
 msgstr ""
 
-#: documents/views.py:1533
+#: documents/views.py:1532
 msgid "AI backend request timed out."
 msgstr ""
 
-#: documents/views.py:2322 documents/views.py:2643
+#: documents/views.py:2330 documents/views.py:2651
 msgid "Specify only one of text, title_search, query, or more_like_id."
 msgstr ""
 
-#: documents/views.py:4471
+#: documents/views.py:4479
 #, python-format
 msgid "Insufficient permissions to share document %(id)s."
 msgstr ""
 
-#: documents/views.py:4517
+#: documents/views.py:4525
 msgid "Bundle is already being processed."
 msgstr ""
 
-#: documents/views.py:4578
+#: documents/views.py:4586
 msgid "The share link bundle is still being prepared. Please try again later."
 msgstr ""
 
-#: documents/views.py:4588
+#: documents/views.py:4596
 msgid "The share link bundle is unavailable."
 msgstr ""