@open-mercato/core 0.6.8-develop.7029.1.a1bb3363af → 0.6.8-develop.7031.1.005201cd70

package/src/modules/query_index/lib/engine.ts

@@ -1,4 +1,4 @@
-import type { QueryEngine, QueryOptions, QueryResult, QueryResultMeta, EncryptedSortRowCapWarning, FilterOp, Filter, QueryCustomFieldSource, PartialIndexWarning, QueryExtensionsConfig, Sort } from '@open-mercato/shared/lib/query/types'
+import type { QueryEngine, QueryOptions, QueryResult, QueryResultMeta, EncryptedSortRowCapWarning, ListCountCapWarning, FilterOp, Filter, QueryCustomFieldSource, PartialIndexWarning, QueryExtensionsConfig, Sort } from '@open-mercato/shared/lib/query/types'
 import { SortDir } from '@open-mercato/shared/lib/query/types'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -34,6 +34,7 @@ import { tokenizeText } from '@open-mercato/shared/lib/search/tokenize'
 import { runBeforeQueryPipeline, runAfterQueryPipeline, type QueryExtensionContext } from '@open-mercato/shared/lib/query/query-extension-runner'
 import { warnOnCiphertextLikeFallback } from '@open-mercato/shared/lib/query/ciphertext-search-warning'
 import { resolveEncryptedSortFields, resolveEncryptedSortMaxRows, sortRowsInMemory } from '@open-mercato/shared/lib/query/encrypted-sort'
+import { resolveListCountCap } from '@open-mercato/shared/lib/query/count-cap'
 import { mapWithConcurrency } from '@open-mercato/shared/lib/query/bounded-decrypt'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
@@ -844,10 +845,9 @@ export class HybridQueryEngine implements QueryEngine {
         return next
       }
 
-      // Also used by the optimized count path, which builds from a bare base table with
-      // no index/custom-field joins. Emitting a cf predicate there would reference an
-      // alias that query has never joined, so this stays safe only while
-      // `canOptimizeCount` is false whenever any cf filter exists (see `hasCustomFieldFilters`).
+      // Also used by the count shape: cf leaves (and doc-based base leaves) reference
+      // the index rowset aliases, so any group containing one routes the whole
+      // disjunction inside the seeded-rowset EXISTS, where those aliases exist.
       const applyOrGroupedBaseFilters = (q: AnyBuilder): AnyBuilder => {
         if (orGroupFilters.length === 0 && orGroupCfFilters.length === 0) return q
         // `BaseFilter` here is just the normalized-leaf shape; the `cf` bucket holds
@@ -996,6 +996,101 @@ export class HybridQueryEngine implements QueryEngine {
       const hasCustomFieldFilters = cfFilters.length > 0
       const canOptimizeCount = !hasCustomFieldFilters && !hasNonBaseSearchSource
 
+      // ── Count shape (#4552 Phase 2) ─────────────────────────────────
+      // The count query is rebuilt rather than derived from the display shape:
+      // base scope + filters only. Predicates that read the left-joined index
+      // rowset (cf filters, doc filters, or-groups with doc members, token
+      // searches over joined sources) evaluate against the *same* rowset as the
+      // display query, but confined inside a single correlated EXISTS built
+      // from a one-row seed — so the per-base-row rowset is identical, yet a
+      // semi-join cannot multiply base rows. The count therefore needs no
+      // DISTINCT or GROUP BY, and an outer LIMIT actually bounds the scan (no
+      // blocking aggregate between the LIMIT and the scan).
+      const isRowsetDependentFilter = (filter: BaseFilter): boolean => {
+        const baseField = resolveBaseColumn(String(filter.field))
+        if (!baseField) return true
+        // Token search may probe joined sources' record ids, which only exist
+        // on the index rowset.
+        if (
+          (filter.op === 'like' || filter.op === 'ilike') &&
+          searchRuntime.enabled &&
+          typeof filter.value === 'string' &&
+          hasNonBaseSearchSource
+        ) return true
+        return false
+      }
+      const rowsetRegularFilters = regularBaseFilters.filter((filter) => isRowsetDependentFilter(filter))
+      const outerRegularFilters = regularBaseFilters.filter((filter) => !isRowsetDependentFilter(filter))
+      // Or-groups are disjuncts of one $or, so they cannot be split between the
+      // outer query and the rowset — one doc-dependent member moves them all in.
+      const orGroupsRowsetDependent =
+        orGroupCfFilters.length > 0 ||
+        orGroupFilters.some((filter) => isRowsetDependentFilter(filter))
+      const hasInnerTypedCfSource = preparedCfSources.some((source) =>
+        ((opts.customFieldSources ?? []).find((s) => s && (s.alias ?? undefined) === source.alias)?.join?.type ?? 'left') === 'inner')
+      const needsIndexRowset =
+        hasCustomFieldFilters ||
+        rowsetRegularFilters.length > 0 ||
+        orGroupsRowsetDependent ||
+        hasInnerTypedCfSource
+
+      const applyCountShape = async (q: AnyBuilder): Promise<AnyBuilder> => {
+        let next = applyBaseScope(q)
+        for (const filter of outerRegularFilters) {
+          const baseField = resolveBaseColumn(String(filter.field))
+          if (!baseField) continue
+          next = this.applyColumnFilter(next, qualify(baseField), filter, {
+            ...searchRuntime, entity, field: String(filter.field), recordIdColumn: qualify('id'),
+          })
+        }
+        if (!orGroupsRowsetDependent) next = applyOrGroupedBaseFilters(next)
+        if (needsIndexRowset) {
+          // One seed row per base row, then the display query's own join
+          // builders — the rowset inside the EXISTS is the display rowset.
+          // Built from `db` (not the where-callback's expression builder),
+          // matching applyJoinFilters' detached-subquery idiom; correlated
+          // references to the outer base alias resolve at compile time.
+          let rowset: AnyBuilder = db
+            .selectFrom(sql`(select 1)`.as('om_count_seed'))
+            .select(sql<number>`1`.as('one'))
+          rowset = applyEntityIndexesJoin(rowset)
+          rowset = applyCustomFieldSourceJoins(rowset)
+          rowset = applyCfFilters(rowset)
+          for (const filter of rowsetRegularFilters) {
+            const baseField = resolveBaseColumn(String(filter.field))
+            if (!baseField) {
+              rowset = this.applyIndexDocFilterFromAlias(
+                rowset, 'ei', entity, String(filter.field), filter.op, filter.value, qualify('id'), searchRuntime,
+              )
+              continue
+            }
+            rowset = this.applyColumnFilter(rowset, qualify(baseField), filter, {
+              ...searchRuntime, entity, field: String(filter.field), recordIdColumn: qualify('id'),
+            })
+          }
+          if (orGroupsRowsetDependent) rowset = applyOrGroupedBaseFilters(rowset)
+          const capturedRowset = rowset
+          next = next.where((eb: any) => eb.exists(capturedRowset))
+        }
+        next = await applyJoinFilters({
+          db,
+          baseTable,
+          builder: next,
+          joinMap,
+          joinFilters,
+          aliasTables,
+          qualifyBase: (column) => qualify(column),
+          applyAliasScope: async (target: any, alias: string) => applyAliasScopes(target as AnyBuilder, alias),
+          applyFilterOp: (target, column, op, value) => applyJoinFilterOpFn(target as AnyBuilder, column, op, value),
+          applyJoinFilterOp: async (target, filter, qualified, join) => {
+            const applied = await applyJoinSearchFilterOp(target as AnyBuilder, filter, qualified, join)
+            return { applied, builder: target }
+          },
+          columnExists: (tbl, column) => this.columnExists(tbl, column),
+        })
+        return next
+      }
+
       // Selection (for data query)
       const selectFieldSet = new Set<string>((opts.fields && opts.fields.length) ? opts.fields.map(String) : Array.from(columns.keys()))
       if (requiresPlaintextSort) {
@@ -1056,33 +1151,23 @@ export class HybridQueryEngine implements QueryEngine {
       const pageSize = opts.page?.pageSize ?? 20
       const sqlDebugEnabled = this.isSqlDebugEnabled()
 
-      let total: number
+      const countCap = resolveListCountCap()
 
-      if (canOptimizeCount) {
-        // Optimized count: apply only base-scope + regular filters + or-group filters (no index joins).
-        const optimizedRoot = db.selectFrom(`${baseTable} as b` as any)
-        let countCore = applyBaseScope(optimizedRoot)
-        countCore = applyRegularBaseFilters(countCore)
-        countCore = applyOrGroupedBaseFilters(countCore)
-        // joinFilters still need to be re-applied in the optimized path
-        countCore = await applyJoinFilters({
-          db,
-          baseTable,
-          builder: countCore,
-          joinMap,
-          joinFilters,
-          aliasTables,
-          qualifyBase: (column) => qualify(column),
-          applyAliasScope: async (target: any, alias: string) => applyAliasScopes(target as AnyBuilder, alias),
-          applyFilterOp: (target, column, op, value) => applyJoinFilterOpFn(target as AnyBuilder, column, op, value),
-          applyJoinFilterOp: async (target, filter, qualified, join) => {
-            const applied = await applyJoinSearchFilterOp(target as AnyBuilder, filter, qualified, join)
-            return { applied, builder: target }
-          },
-          columnExists: (tbl, column) => this.columnExists(tbl, column),
-        })
-        const sub = countCore.select(sql.ref(qualify('id')).as('id')).groupBy(qualify('id')).as('sq')
-        const countQuery = db.selectFrom(sub as any).select(sql<string>`count(*)`.as('count'))
+      // Both count paths build the same rebuilt shape; for `canOptimizeCount`
+      // queries `needsIndexRowset` is false, so the shape degenerates to
+      // base-scope + filters exactly as the optimized path always had.
+      // `wasOptimizable` carries NO control flow — it only labels the debug
+      // timing so operators can keep telling the two shapes apart.
+      // TODO(2026-08-12): remove `canOptimizeCount` once the shape convergence
+      // has soaked (tracked in the #4552 spec as the Phase 2 follow-up).
+      const runBoundedCount = async (wasOptimizable: boolean): Promise<{ total: number; warning?: ListCountCapWarning }> => {
+        const countRoot = db.selectFrom(`${baseTable} as b` as any)
+        const shape = await applyCountShape(countRoot)
+        const countQuery = countCap !== null
+          ? db
+              .selectFrom(shape.select(sql<number>`1`.as('one')).limit(countCap + 1).as('om_count_probe') as any)
+              .select(sql<string>`count(*)`.as('count'))
+          : shape.select(sql<string>`count(*)`.as('count'))
         if (debugEnabled && sqlDebugEnabled) {
           const compiled = countQuery.compile()
           this.debug('query:sql:count', { entity, sql: compiled.sql, bindings: compiled.parameters })
@@ -1090,25 +1175,19 @@ export class HybridQueryEngine implements QueryEngine {
         const countRow = await this.captureSqlTiming(
           'query:sql:count', entity,
           () => countQuery.executeTakeFirst(),
-          { optimized: true }, profiler,
+          { optimized: wasOptimizable }, profiler,
         )
-        total = this.parseCount(countRow)
-      } else {
-        const countRoot = db.selectFrom(`${baseTable} as b` as any)
-        const countBuilder = (await applyQueryShape(countRoot))
-          .select(sql<string>`count(distinct ${sql.ref(qualify('id'))})`.as('count'))
-        if (debugEnabled && sqlDebugEnabled) {
-          const compiled = countBuilder.compile()
-          this.debug('query:sql:count', { entity, sql: compiled.sql, bindings: compiled.parameters })
+        const probed = this.parseCount(countRow)
+        if (countCap !== null && probed > countCap) {
+          return { total: countCap, warning: { entity, cap: countCap } }
         }
-        const countRow = await this.captureSqlTiming(
-          'query:sql:count', entity,
-          () => countBuilder.executeTakeFirst(),
-          { optimized: false }, profiler,
-        )
-        total = this.parseCount(countRow)
+        return { total: probed }
       }
 
+      const counted = await runBoundedCount(canOptimizeCount)
+      const total: number = counted.total
+      const listCountCapWarning: ListCountCapWarning | undefined = counted.warning
+
       const dekKeyCache = new Map<string | null, string | null>()
 
       const decryptRow = async (item: Record<string, unknown>): Promise<Record<string, unknown>> => {
@@ -1159,24 +1238,29 @@ export class HybridQueryEngine implements QueryEngine {
         const sortFieldNames = Array.from(new Set(['id', ...scopeFieldNames, ...resolvedSorts.map((s) => String(s.field))]))
         phase1 = applySelection(phase1, sortFieldNames)
         if (cap !== null) {
-          phase1 = phase1.limit(cap).orderBy(qualify('id'), 'asc' as any)
+          // Probe one row past the cap: truncation is detected from the candidate
+          // scan itself, not by comparing against `total` — which may itself be
+          // capped (`OM_LIST_COUNT_CAP`) and would then never exceed the sort cap.
+          phase1 = phase1.limit(cap + 1).orderBy(qualify('id'), 'asc' as any)
         }
         if (debugEnabled && sqlDebugEnabled) {
           const compiled = phase1.compile()
           this.debug('query:sql:data:phase1', { entity, sql: compiled.sql, bindings: compiled.parameters })
         }
-        const candidateRows = await this.captureSqlTiming(
+        const candidateRowsRaw = await this.captureSqlTiming(
           'query:sql:data:phase1', entity,
           () => phase1.execute(),
           { phase: 1 }, profiler,
         ) as Record<string, unknown>[]
+        const sortTruncated = cap !== null && candidateRowsRaw.length > cap
+        const candidateRows = sortTruncated && cap !== null ? candidateRowsRaw.slice(0, cap) : candidateRowsRaw
         const decryptedCandidates = await mapWithConcurrency(candidateRows, DECRYPT_CONCURRENCY, decryptRow)
         const orderedCandidates = sortRowsInMemory(decryptedCandidates, resolvedSorts)
         const pageIds = orderedCandidates
           .slice((page - 1) * pageSize, page * pageSize)
           .map((row) => row.id)
 
-        if (cap !== null && total > cap) {
+        if (sortTruncated && cap !== null) {
           encryptedSortRowCapWarning = {
             entity,
             sortFields: resolvedSorts.map((s) => String(s.field)),
@@ -1232,10 +1316,11 @@ export class HybridQueryEngine implements QueryEngine {
 
       const typedItems = items as unknown as T[]
       let result: QueryResult<T> = { items: typedItems, page, pageSize, total }
-      if (partialIndexWarning || encryptedSortRowCapWarning) {
+      if (partialIndexWarning || encryptedSortRowCapWarning || listCountCapWarning) {
         const meta: QueryResultMeta = {}
         if (partialIndexWarning) meta.partialIndexWarning = partialIndexWarning
         if (encryptedSortRowCapWarning) meta.encryptedSortRowCapWarning = encryptedSortRowCapWarning
+        if (listCountCapWarning) meta.listCountCapWarning = listCountCapWarning
         result.meta = meta
       }
 
@@ -2036,17 +2121,35 @@ export class HybridQueryEngine implements QueryEngine {
     const page = opts.page?.page ?? 1
     const pageSize = opts.page?.pageSize ?? 20
 
+    // Single-table count: `applyScope` adds only WHERE predicates (cf filters
+    // included — no join), and doc storage holds one row per record within a
+    // scope, so `count(*)` needs no DISTINCT and — when the cap is active — a
+    // LIMIT on the row-producing inner query bounds the scan (#4552 Phase 2).
+    const countCap = resolveListCountCap()
     const root = db.selectFrom(`custom_entities_storage as ${alias}`)
-    const countQuery = applyScope(root).select(sql<string>`count(distinct ${sql.ref(`${alias}.entity_id`)})`.as('count'))
+    const countShape = applyScope(root)
+    const countQuery = countCap !== null
+      ? db
+          .selectFrom(countShape.select(sql<number>`1`.as('one')).limit(countCap + 1).as('om_count_probe') as any)
+          .select(sql<string>`count(*)`.as('count'))
+      : countShape.select(sql<string>`count(*)`.as('count'))
     const countRow = await countQuery.executeTakeFirst()
-    const total = this.parseCount(countRow)
+    const probed = this.parseCount(countRow)
+    let total = probed
+    let listCountCapWarning: ListCountCapWarning | undefined
+    if (countCap !== null && probed > countCap) {
+      total = countCap
+      listCountCapWarning = { entity: entity as EntityId, cap: countCap }
+    }
 
     let dataQuery = applyScope(db.selectFrom(`custom_entities_storage as ${alias}`))
     dataQuery = applySelection(dataQuery)
     dataQuery = applySort(dataQuery)
     dataQuery = dataQuery.limit(pageSize).offset((page - 1) * pageSize)
     const items = await dataQuery.execute()
-    return { items, page, pageSize, total }
+    const result: QueryResult<T> = { items, page, pageSize, total }
+    if (listCountCapWarning) result.meta = { listCountCapWarning }
+    return result
   }
 
   private async tableExists(table: string): Promise<boolean> {

package/src/modules/resources/backend/resources/resource-types/page.tsx

@@ -45,6 +45,7 @@ type ResourceTypesResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 type ResourceTypesMutationContext = {
@@ -63,6 +64,7 @@ export default function ResourcesResourceTypesPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'name', desc: false }])
   const [search, setSearch] = React.useState('')
   const [isLoading, setIsLoading] = React.useState(true)
@@ -232,6 +234,7 @@ export default function ResourcesResourceTypesPage() {
       setRows(items.map(mapApiResourceType))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      setTotalIsCapped(payload?.totalIsCapped === true)
     } catch (error) {
       logger.error('Failed to list resource types', { err: error })
       flash(translations.errors.load, 'error')
@@ -308,7 +311,7 @@ export default function ResourcesResourceTypesPage() {
           sortable
           sorting={sorting}
           onSortingChange={setSorting}
-          pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, onPageChange: setPage }}
+          pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, totalIsCapped, onPageChange: setPage }}
           rowActions={(row) => (
             <RowActions
               items={[

package/src/modules/resources/backend/resources/resources/page.tsx

@@ -63,6 +63,7 @@ type ResourcesResponse = {
   total: number
   page: number
   totalPages: number
+  totalIsCapped?: boolean
 }
 
 type ResourceTypesResponse = {
@@ -81,6 +82,7 @@ export default function ResourcesResourcesPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
   const [isLoading, setIsLoading] = React.useState(true)
@@ -360,6 +362,7 @@ export default function ResourcesResourcesPage() {
           setRows(mapped)
           setTotal(payload.total || 0)
           setTotalPages(payload.totalPages || 1)
+          setTotalIsCapped(payload?.totalIsCapped === true)
         }
       } catch (error) {
         if (!cancelled) {
@@ -546,7 +549,7 @@ export default function ResourcesResourcesPage() {
               createLabel={t('resources.resources.list.actions.create', 'New resource')}
             />
           )}
-          pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, onPageChange: setPage }}
+          pagination={{ page, pageSize: PAGE_SIZE, total, totalPages, totalIsCapped, onPageChange: setPage }}
           isLoading={isLoading}
         />
       </PageBody>

package/src/modules/sales/backend/sales/channels/offers/page.tsx

@@ -29,6 +29,7 @@ type OffersResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 const PAGE_SIZE = 25
@@ -61,6 +62,7 @@ export default function SalesChannelOffersListPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'updatedAt', desc: true }])
   const [search, setSearch] = React.useState('')
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
@@ -271,6 +273,7 @@ export default function SalesChannelOffersListPage() {
       setRows(mapped)
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      setTotalIsCapped(payload?.totalIsCapped === true)
       const ids = mapped
         .map((row) => row.channelId)
         .filter((value): value is string => typeof value === 'string' && value.length > 0)
@@ -362,6 +365,7 @@ export default function SalesChannelOffersListPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           refreshButton={{

package/src/modules/sales/backend/sales/channels/page.tsx

@@ -37,6 +37,7 @@ type ChannelsResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 const PAGE_SIZE = 25
@@ -68,6 +69,7 @@ export default function SalesChannelsPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [sorting, setSorting] = React.useState<SortingState>([])
   const [search, setSearch] = React.useState('')
   const [isLoading, setLoading] = React.useState(true)
@@ -142,6 +144,7 @@ export default function SalesChannelsPage() {
       setRows(items.map(mapApiChannel))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      setTotalIsCapped(payload?.totalIsCapped === true)
     } catch (err) {
       logger.error('sales.channels.list', { err })
       flash(t('sales.channels.table.errors.load', 'Failed to load channels.'), 'error')
@@ -230,6 +233,7 @@ export default function SalesChannelsPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           refreshButton={{

package/src/modules/sales/components/channels/SalesChannelOffersPanel.tsx

@@ -25,6 +25,7 @@ type OffersResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 const PAGE_SIZE = 25
@@ -54,6 +55,7 @@ export function SalesChannelOffersPanel({ channelId, channelName }: { channelId:
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [isLoading, setLoading] = React.useState(true)
   const [sorting, setSorting] = React.useState<SortingState>([])
@@ -134,6 +136,7 @@ export function SalesChannelOffersPanel({ channelId, channelName }: { channelId:
       setRows(items.map(mapOfferRow))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      setTotalIsCapped(payload?.totalIsCapped === true)
     } catch (err) {
       logger.error('sales.channels.offers', { err })
       flash(t('sales.channels.offers.errors.load', 'Failed to load offers.'), 'error')
@@ -208,6 +211,7 @@ export function SalesChannelOffersPanel({ channelId, channelName }: { channelId:
         pageSize: PAGE_SIZE,
         total,
         totalPages,
+        totalIsCapped,
         onPageChange: setPage,
       }}
       refreshButton={{

package/src/modules/sales/components/documents/SalesDocumentsTable.tsx

@@ -71,6 +71,7 @@ type DocumentsResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 type SalesDocumentRow = {
@@ -173,6 +174,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'createdAt', desc: true }])
   const [search, setSearch] = React.useState('')
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
@@ -564,6 +566,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
         setRows([])
         setTotal(0)
         setTotalPages(1)
+        setTotalIsCapped(false)
         return
       }
       const payload = call.result ?? {}
@@ -575,6 +578,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
         ? payload.totalPages
         : Math.max(1, Math.ceil(count / PAGE_SIZE))
       setTotalPages(pages)
+      setTotalIsCapped(payload.totalIsCapped === true)
       setCacheStatus(call.cacheStatus ?? null)
     } catch (err) {
       logger.error('sales.documents.list', { err })
@@ -800,6 +804,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
             cacheStatus,
           }}

package/src/modules/staff/backend/staff/leave-requests/page.tsx

@@ -30,6 +30,7 @@ type LeaveRequestsResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 export default function StaffLeaveRequestsPage() {
@@ -40,6 +41,7 @@ export default function StaffLeaveRequestsPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [isLoading, setIsLoading] = React.useState(true)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'startDate', desc: true }])
@@ -123,6 +125,7 @@ export default function StaffLeaveRequestsPage() {
       setRows(items.map(mapLeaveRequest))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : 1)
+      setTotalIsCapped(payload?.totalIsCapped === true)
     } catch {
       setRows([])
       setTotal(0)
@@ -177,6 +180,7 @@ export default function StaffLeaveRequestsPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           onRowClick={(row) => {

package/src/modules/staff/backend/staff/my-leave-requests/page.tsx

@@ -29,6 +29,7 @@ type LeaveRequestsResponse = {
   total?: number
   totalPages?: number
   viewer?: { memberId?: string | null; canSend?: boolean }
+  totalIsCapped?: boolean
 }
 
 export default function StaffMyLeaveRequestsPage() {
@@ -39,6 +40,7 @@ export default function StaffMyLeaveRequestsPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [isLoading, setIsLoading] = React.useState(true)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'startDate', desc: true }])
@@ -118,6 +120,7 @@ export default function StaffMyLeaveRequestsPage() {
       setRows(items.map(mapLeaveRequest))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : 1)
+      setTotalIsCapped(payload?.totalIsCapped === true)
       const viewerMemberId = typeof payload.viewer?.memberId === 'string' ? payload.viewer.memberId : null
       setMemberId(viewerMemberId)
       setCanSend(payload.viewer?.canSend === true)
@@ -182,6 +185,7 @@ export default function StaffMyLeaveRequestsPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           onRowClick={(row) => {

package/src/modules/staff/backend/staff/team-members/page.tsx

@@ -47,6 +47,7 @@ type TeamMembersResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 type TeamsResponse = {
@@ -68,6 +69,7 @@ export default function StaffTeamMembersPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'displayName', desc: false }])
   const [search, setSearch] = React.useState('')
   const [isLoading, setIsLoading] = React.useState(true)
@@ -272,6 +274,9 @@ export default function StaffTeamMembersPage() {
         : typeof payload.totalPages === 'number'
           ? payload.totalPages
           : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      // A role filter is applied client-side over the fetched page, so the total
+      // shown is that array's length — exact by construction, never a capped floor.
+      setTotalIsCapped(!roleFilterApplied && payload.totalIsCapped === true)
     } catch (error) {
       logger.error('staff.team-members.list', { err: error })
       flash(labels.errors.load, 'error')
@@ -452,6 +457,7 @@ export default function StaffTeamMembersPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           rowActions={(row) => row.kind === 'member' ? (

package/src/modules/staff/backend/staff/team-roles/page.tsx

@@ -41,6 +41,7 @@ type TeamRolesResponse = {
   items?: Array<Record<string, unknown>>
   total?: number
   totalPages?: number
+  totalIsCapped?: boolean
 }
 
 type TeamsResponse = {
@@ -56,6 +57,7 @@ export default function StaffTeamRolesPage() {
   const [page, setPage] = React.useState(1)
   const [total, setTotal] = React.useState(0)
   const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
   const [search, setSearch] = React.useState('')
   const [isLoading, setIsLoading] = React.useState(true)
   const [reloadToken, setReloadToken] = React.useState(0)
@@ -203,6 +205,7 @@ export default function StaffTeamRolesPage() {
       setRows(buildTeamRoleRows(items.map(mapApiTeamRole), labels.groups.unassigned))
       setTotal(typeof payload.total === 'number' ? payload.total : items.length)
       setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : Math.max(1, Math.ceil(items.length / PAGE_SIZE)))
+      setTotalIsCapped(payload?.totalIsCapped === true)
     } catch (error) {
       logger.error('staff.team-roles.list', { err: error })
       flash(labels.errors.load, 'error')
@@ -329,6 +332,7 @@ export default function StaffTeamRolesPage() {
             pageSize: PAGE_SIZE,
             total,
             totalPages,
+            totalIsCapped,
             onPageChange: setPage,
           }}
           rowActions={(row) => row.kind === 'role' ? (