fix: align collection queries and pagination with v2 contracts

Author: stefan-ernst

docs/collection-query-contract.md

@@ -0,0 +1,51 @@
+# Collection query and pagination contract
+
+A saved collection is a query over the caller's accessible workspaces. An empty
+or whitespace-only query adds no restriction. A collection's workspace location
+does not replace its query scope; explicit workspace restrictions belong in CQL.
+Completion filters and other sub-filters narrow that same scope before counting
+and pagination. Removing a sub-filter must not turn an unrestricted collection
+into an empty result.
+
+Item lists and backlog resolve saved queries through `resolveItemListQLContext`.
+Delta membership checks use the item list service. Board metadata projects the
+matching workspace IDs through the same CQL evaluator and permission scope,
+including when the query is empty.
+
+The v2 response contract uses `page`, `page_size`, `total_items`, and `total_pages`.
+`collectionService.js` adapts `page_size` to the collection store's existing
+`limit` option once, for both items and backlog. Continuations must use that
+effective server size, especially when the server caps a requested size.
+Headers, pagination controls, and remaining counts all use `total_items`.
+The collection query editor opts into empty searches and consumes canonical v2
+pagination directly. The general search page still waits for a query.
+
+Regression coverage lives in the sibling `core-tests` repository:
+
+- `tests/collection_empty_query_test.go`: empty and whitespace queries,
+  completion sub-filters, page contents and totals, board metadata, and
+  inaccessible workspace exclusion.
+- `frontend/src/lib/features/collections/collectionService.test.js`: the v2
+  pagination response adapter for item and backlog continuation.
+- `e2e/tests/collection-empty-query.spec.ts`: navigation beyond fifty rows,
+  both list and query-editor pagination, toggling completion visibility from
+  page two, and preference persistence.
+- `frontend/src/lib/stores/searchStore.test.js`: unrestricted empty collection
+  searches and the general search page's initial idle state.
+
+## Validation commands
+
+Run from `core`:
+
+```sh
+../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestEmptyCollection|TestCollectionMetadata|TestItemsBatch' ./tests
+TEST_DB_TYPE=postgres TEST_POSTGRES_DSN='postgresql://localhost:5432/postgres?sslmode=disable' ../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestEmptyCollection|TestCollectionMetadata|TestItemsBatch' ./tests
+../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestItemCRUDService|TestCollection.*Board|TestBoardConfiguration' ./internal/services
+../core-tests/run-overlay-script.sh . scripts/run-frontend-tests.sh src/lib/features/collections src/lib/stores/collectionContext.test.js src/lib/stores/collectionCompletion.test.js src/lib/stores/searchStore.test.js
+E2E_KEEP_ARTIFACTS=1 ../core-tests/run-e2e.sh tests/collection-empty-query.spec.ts tests/collection-completed-visibility.spec.ts tests/collection-search-columns.spec.ts --retries=0
+./scripts/run-golangci-lint.sh run --timeout=5m
+```
+
+Go files are formatted with `gofmt`. Changed JavaScript and TypeScript files are
+checked with Biome using `frontend/biome.json`; Svelte files are excluded.
+Full repository suites are outside this focused validation.

frontend/src/lib/components/Pagination.svelte

@@ -102,6 +102,7 @@
           variant="default"
           size="small"
           icon={ChevronLeft}
+          dataTestid="pagination-previous"
           onclick={() => goToPage(currentPage - 1)}
           disabled={isFirstPage}
           class="px-2"
@@ -134,6 +135,7 @@
           variant="default"
           size="small"
           icon={ChevronRight}
+          dataTestid="pagination-next"
           onclick={() => goToPage(currentPage + 1)}
           disabled={isLastPage}
           class="px-2"
@@ -152,4 +154,4 @@
   .pagination-container.compact .flex {
     gap: 0.5rem;
   }
-</style>
+</style>

frontend/src/lib/features/collections/CollectionBacklog.svelte

@@ -832,7 +832,7 @@
               >
                 {collectionStore.backlogLoadingMore ? t('common.loading') : t('common.loadMore')}
                 {#if collectionStore.backlogPagination?.total_items}
-                  ({collectionStore.backlogPagination.total - collectionStore.backlogItems.length} {t('common.remaining')})
+                  ({collectionStore.backlogPagination.total_items - collectionStore.backlogItems.length} {t('common.remaining')})
                 {/if}
               </button>
             </div>

frontend/src/lib/features/collections/CollectionList.svelte

@@ -456,11 +456,11 @@
         </div>
 
         <!-- Pagination -->
-        {#if itemsPagination && itemsPagination.total > 0 && workItems.length > 0}
+        {#if itemsPagination && itemsPagination.total_items > 0 && workItems.length > 0}
           <div class="mt-6">
             <Pagination
               currentPage={itemsPagination.page}
-              totalItems={itemsPagination.total}
+              totalItems={itemsPagination.total_items}
               itemsPerPage={itemsPagination.limit}
               maxItems={10000}
               onpageChange={handlePageChange}

frontend/src/lib/features/collections/Collections.svelte

@@ -34,7 +34,7 @@
   let { collectionId = null } = $props();
 
   // Each Collections instance owns a fresh search store — no cross-page leakage.
-  const store = createWorkItemSearchStore();
+  const store = createWorkItemSearchStore({ allowEmptyQuery: true });
   /** @type {Record<string, any>} */
   let storeState = $state({});
   const unsubscribeStore = store.subscribe((value) => (storeState = value));
@@ -154,7 +154,8 @@
 
   async function loadBoardConfiguration(id) {
     try {
-      const config = await api.collections.getBoardConfiguration(id);
+      const bootstrap = await api.collections.getBoardConfigurationBootstrap(id);
+      const config = bootstrap?.board_configuration ?? null;
       boardConfig = config;
       listColumns = listColumnsFromConfig(config);
     } catch (error) {
@@ -506,12 +507,12 @@
         rowAttrs={(item) => ({ 'data-testid': `collection-result-${item.id}` })}
       />
 
-      {#if itemsPagination && itemsPagination.total > 0}
+      {#if itemsPagination && itemsPagination.total_items > 0}
         <div class="mt-6">
           <Pagination
             currentPage={itemsPagination.page}
-            totalItems={itemsPagination.total}
-            itemsPerPage={itemsPagination.limit}
+            totalItems={itemsPagination.total_items}
+            itemsPerPage={itemsPagination.page_size}
             maxItems={10000}
             onpageChange={handlePageChange}
             onpageSizeChange={handlePageSizeChange}

frontend/src/lib/features/collections/collectionService.js

@@ -1,5 +1,11 @@
 import { api } from '../../api.js';
 
+function collectionPagination(pagination) {
+  if (!pagination) return null;
+  // Store continuations use limit; v2 responses name the effective size page_size.
+  return { ...pagination, limit: pagination.page_size };
+}
+
 /**
  * Fetches items for a collection (or all workspace items if no collection).
  * Handles QL query resolution and correct API parameter naming.
@@ -42,7 +48,7 @@ export async function fetchCollectionItems(
 
   const response = await api.items.getAll(filters);
   const items = response?.data ?? [];
-  const pagination = response?.pagination ?? null;
+  const pagination = collectionPagination(response?.pagination);
   const sortableFields = response?.meta?.sortable_fields ?? [];
   const watermark = response?.meta?.watermark ?? 0;
 
@@ -80,7 +86,7 @@ export async function fetchCollectionBacklog(
     include_watermark: true,
   });
   const items = response?.data ?? [];
-  const pagination = response?.pagination ?? null;
+  const pagination = collectionPagination(response?.pagination);
   const watermark = response?.meta?.watermark ?? 0;
   return { items, collectionName, pagination, watermark };
 }

frontend/src/lib/stores/searchStore.svelte.js

@@ -15,7 +15,7 @@ import { warningToast } from './toasts.svelte.js';
  * URL round-trip, and the polished raw-mode UX (confirm-then-snapshot,
  * tryParseToBuilder on reset, warning toast for dropped clauses).
  */
-export function createWorkItemSearchStore() {
+export function createWorkItemSearchStore({ allowEmptyQuery = false } = {}) {
   // ===== Filter state =====
   const searchQuery = writable('');
   const selectedWorkspaces = writable([]);
@@ -174,7 +174,7 @@ export function createWorkItemSearchStore() {
   // ===== Search execution =====
   async function executeSearch({ page = 1, limit = 50 } = {}) {
     const finalQl = get(qlQuery);
-    if (!finalQl?.trim()) {
+    if (!allowEmptyQuery && !finalQl?.trim()) {
       workItems.set([]);
       pagination.set(null);
       qlError.set(null);

internal/services/collection_application_service.go

@@ -541,13 +541,10 @@ func (s *CollectionApplicationService) GetBoardConfigurationBootstrap(ctx contex
 	if err != nil {
 		return nil, err
 	}
-	referencedWorkspaceIDs := []int{}
-	if collection.QLQuery != "" {
-		referencedWorkspaceIDs, err = s.items.ListDistinctWorkspaceIDsWithQLContext(ctx, collection.QLQuery, accessibleWorkspaceIDs, userID)
-		if err != nil {
-			slog.Warn("board configuration bootstrap: collection CQL workspace projection failed", "collection_id", collection.ID, "error", err)
-			referencedWorkspaceIDs = []int{}
-		}
+	referencedWorkspaceIDs, err := s.items.ListDistinctWorkspaceIDsWithQLContext(ctx, collection.QLQuery, accessibleWorkspaceIDs, userID)
+	if err != nil {
+		slog.Warn("board configuration bootstrap: collection CQL workspace projection failed", "collection_id", collection.ID, "error", err)
+		referencedWorkspaceIDs = []int{}
 	}
 	if len(referencedWorkspaceIDs) == 0 {
 		candidate := fallbackWorkspaceID

internal/services/item_crud_service.go

@@ -606,12 +606,6 @@ func (s *ItemCRUDService) ListWithQLPageContext(ctx context.Context, params List
 		filters.QLArgs = resolvedQL.args
 	}
 
-	// If collection was resolved but produced no effective query, return empty results.
-	// A collection with no filter means "nothing to show yet."
-	if resolvedQL.collectionResolved && filters.QLQuery == "" {
-		return repository.ItemListPage{Items: []models.Item{}}, nil
-	}
-
 	// Apply workspace_id filter only when no collection was resolved
 	if !resolvedQL.collectionResolved && params.WorkspaceID > 0 {
 		filters.WorkspaceID = &params.WorkspaceID
@@ -666,11 +660,11 @@ func (s *ItemCRUDService) ListDistinctWorkspaceIDsWithQLContext(
 	workspaceIDs []int,
 	userID int,
 ) ([]int, error) {
-	if len(workspaceIDs) == 0 || strings.TrimSpace(qlQuery) == "" {
+	if len(workspaceIDs) == 0 {
 		return []int{}, nil
 	}
 
-	qlSQL, qlArgs, err := s.evaluateQLContext(ctx, qlQuery, cql.UserContext(userID))
+	qlSQL, qlArgs, err := s.evaluateQLContext(ctx, strings.TrimSpace(qlQuery), cql.UserContext(userID))
 	if err != nil {
 		return nil, err
 	}