@open-mercato/core 0.6.7-develop.6706.1.b3a4c759bb → 0.6.7-develop.6725.1.07a748cfc2

package/src/modules/auth/lib/backendChrome.tsx

@@ -22,6 +22,7 @@ import { resolveRegisteredLucideIconNode } from '@open-mercato/ui/backend/icons/
 import { profilePathPrefixes, profileSections } from './profile-sections'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { filterGrantsByEnabledModules } from '@open-mercato/shared/security/enabledModulesRegistry'
+import { getNavGroupOrderOverride } from '@open-mercato/shared/modules/overrides'
 import {
   getSelectedOrganizationFromRequest,
   resolveFeatureCheckContext,
@@ -147,19 +148,35 @@ async function serializeNavItem(item: AdminNavItem): Promise<ResolvedNavItem> {
   }
 }
 
+const defaultGroupOrder = [
+  'customers.nav.group',
+  'catalog.nav.group',
+  'customers~sales.nav.group',
+  'wms.nav.group',
+  'resources.nav.group',
+  'staff.nav.group',
+  'entities.nav.group',
+  'directory.nav.group',
+  'attachments.nav.group',
+]
+
+/**
+ * Group ids ranked ahead of everything else, most significant first.
+ *
+ * An app may prepend its own ids via `overrides.nav.groupOrder` in `modules.ts`; ids it does not name
+ * keep the ordering they have today. With no override configured this returns `defaultGroupOrder`
+ * itself, so ordering is unchanged for every existing install.
+ */
+function resolveGroupOrder(): string[] {
+  const override = getNavGroupOrderOverride()
+  if (!override || override.length === 0) return defaultGroupOrder
+  const overridden = new Set(override)
+  return [...override, ...defaultGroupOrder.filter((id) => !overridden.has(id))]
+}
+
 function normalizeGroupWeights(groups: NavGroupWithWeight[]): NavGroupWithWeight[] {
-  const defaultGroupOrder = [
-    'customers.nav.group',
-    'catalog.nav.group',
-    'customers~sales.nav.group',
-    'wms.nav.group',
-    'resources.nav.group',
-    'staff.nav.group',
-    'entities.nav.group',
-    'directory.nav.group',
-    'attachments.nav.group',
-  ]
-  const groupOrderIndex = new Map(defaultGroupOrder.map((id, index) => [id, index]))
+  const groupOrder = resolveGroupOrder()
+  const groupOrderIndex = new Map(groupOrder.map((id, index) => [id, index]))
   groups.sort((a, b) => {
     const aIndex = groupOrderIndex.get(a.id)
     const bIndex = groupOrderIndex.get(b.id)
@@ -171,7 +188,7 @@ function normalizeGroupWeights(groups: NavGroupWithWeight[]): NavGroupWithWeight
     if (a.weight !== b.weight) return a.weight - b.weight
     return a.name.localeCompare(b.name)
   })
-  const defaultGroupCount = defaultGroupOrder.length
+  const defaultGroupCount = groupOrder.length
   groups.forEach((group, index) => {
     const rank = groupOrderIndex.get(group.id)
     const fallbackWeight = typeof group.weight === 'number' ? group.weight : 10_000
@@ -275,6 +292,11 @@ export async function resolveBackendChromePayload({
 
   let scopedOrganizationId: string | null = auth.orgId ?? null
   let scopedTenantId: string | null = auth.tenantId ?? null
+  // The organization the caller actually *selected*, as distinct from the one the scope resolver fell
+  // back to. `resolveFeatureCheckContext` resolves `organizationId` to `auth.orgId` when no concrete
+  // organization is selected — which is precisely what an all-organizations view produces — so the
+  // resolved id cannot answer "which organization am I viewing".
+  let concretelySelectedOrganizationId: string | null = null
   let allowNavigation = true
 
   try {
@@ -287,12 +309,14 @@ export async function resolveBackendChromePayload({
     })
     scopedOrganizationId = organizationId
     scopedTenantId = scope.tenantId ?? auth.tenantId ?? null
+    concretelySelectedOrganizationId = scope.selectedId ?? null
     if (Array.isArray(allowedOrganizationIds) && allowedOrganizationIds.length === 0) {
       allowNavigation = false
     }
   } catch {
     scopedOrganizationId = auth.orgId ?? null
     scopedTenantId = auth.tenantId ?? null
+    concretelySelectedOrganizationId = null
   }
 
   const acl = allowNavigation
@@ -411,6 +435,11 @@ export async function resolveBackendChromePayload({
     ?? (fallbackOrganizationId && !isAllOrganizationsSelection(fallbackOrganizationId) ? fallbackOrganizationId : null)
 
   let brand: BackendChromePayload['brand'] = null
+  // Resolved here rather than left to callers. `brand` only populates when the organization has a
+  // logo, so it is a branding channel, not a dependable "which organization am I viewing" source.
+  // Without this field every downstream app has to fetch `/api/directory/organization-switcher` and
+  // walk its tree for the selected id. The row is already loaded below, so the name costs nothing.
+  let currentOrganization: BackendChromePayload['currentOrganization'] = null
   if (brandOrganizationId && scopedTenantId) {
     try {
       const organization = await findOneWithDecryption(
@@ -420,6 +449,12 @@ export async function resolveBackendChromePayload({
         undefined,
         { tenantId: scopedTenantId, organizationId: brandOrganizationId },
       )
+      // Only when a concrete organization was selected. Under an all-organizations view
+      // `brandOrganizationId` still resolves (to the caller's own organization, which is what keeps
+      // branding working), so gating on the loaded row alone would misreport the scope.
+      if (organization && concretelySelectedOrganizationId === brandOrganizationId) {
+        currentOrganization = { id: String(organization.id), name: organization.name }
+      }
       if (organization?.logoUrl) {
         brand = {
           name: organization.name,
@@ -430,7 +465,9 @@ export async function resolveBackendChromePayload({
         }
       }
     } catch {
+      // Fail soft, as before: a failed organization lookup must not take down the nav payload.
       brand = null
+      currentOrganization = null
     }
   }
 
@@ -443,5 +480,6 @@ export async function resolveBackendChromePayload({
     grantedFeatures,
     roles: Array.isArray(auth.roles) ? auth.roles : [],
     brand,
+    currentOrganization,
   }
 }

package/src/modules/customers/api/utils.ts

@@ -4,8 +4,7 @@ import { sql } from 'kysely'
 import type { CrudCtx } from '@open-mercato/shared/lib/crud/factory'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { QueryCustomFieldSource, QueryJoinEdge, QueryEngine } from '@open-mercato/shared/lib/query/types'
-import { resolveSearchConfig } from '@open-mercato/shared/lib/search/config'
-import { tokenizeText } from '@open-mercato/shared/lib/search/tokenize'
+import { findEntityIdsBySearchTokensCompat, type SearchTokenDatabase } from '@open-mercato/shared/lib/search/tokenLookup'
 import { SortDir } from '@open-mercato/shared/lib/query/types'
 
 const { withScopedPayload, parseScopedCommandInput } = createScopedApiHelpers({
@@ -106,36 +105,18 @@ async function findSearchTokenEntityIds({
   fields,
   query,
 }: SearchTokenMatchInput): Promise<string[] | null> {
-  const trimmed = query.trim()
-  if (!trimmed) return null
-
-  const tokens = tokenizeText(trimmed, resolveSearchConfig())
-  if (!tokens.hashes.length) return []
-
   const em = ctx.container.resolve('em') as EntityManager
-  const db = em.getKysely<any>() as any
-  let searchQuery = db
-    .selectFrom('search_tokens')
-    .select('entity_id')
-    .where('entity_type', '=', entityType)
-    .where('field', 'in', fields)
-    .where('token_hash', 'in', tokens.hashes)
-    .groupBy('entity_id')
-    .having(sql<boolean>`count(distinct token_hash) >= ${tokens.hashes.length}`)
-
-  if (ctx.auth?.tenantId !== undefined) {
-    searchQuery = searchQuery.where(sql<boolean>`tenant_id is not distinct from ${ctx.auth?.tenantId ?? null}`)
-  }
-  if (ctx.selectedOrganizationId) {
-    searchQuery = searchQuery.where('organization_id', '=', ctx.selectedOrganizationId)
-  } else if (Array.isArray(ctx.organizationIds) && ctx.organizationIds.length > 0) {
-    searchQuery = searchQuery.where('organization_id', 'in', ctx.organizationIds)
-  }
-
-  const rows = await searchQuery.execute() as Array<{ entity_id?: unknown }>
-  return rows
-    .map((row) => (typeof row.entity_id === 'string' ? row.entity_id : null))
-    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+  return findEntityIdsBySearchTokensCompat({
+    db: em.getKysely<SearchTokenDatabase>(),
+    entityType,
+    query,
+    fields,
+    scope: {
+      tenantId: ctx.auth?.tenantId !== undefined ? ctx.auth?.tenantId ?? null : undefined,
+      organizationId: ctx.selectedOrganizationId ?? undefined,
+      organizationIds: ctx.organizationIds,
+    },
+  })
 }
 
 async function mapScopedEntityIds({

package/src/modules/customers/cli.ts

@@ -12,6 +12,7 @@ import { E as CoreEntities } from '#generated/entities.ids.generated'
 import { createProgressBar } from '@open-mercato/shared/lib/cli/progress'
 import { buildIndexDocument, type IndexCustomFieldValue } from '@open-mercato/core/modules/query_index/lib/document'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { resolveSearchConfig } from '@open-mercato/shared/lib/search/config'
 import type { QueryEngine } from '@open-mercato/shared/lib/query/types'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import {
@@ -1994,6 +1995,7 @@ async function seedCustomerStressTest(
       updated_at: Date
       deleted_at: null
     }> = []
+    const searchConfig = resolveSearchConfig()
     for (const [entityType, bucket] of pendingIndexDocs.entries()) {
       for (const entry of bucket.values()) {
         if (!entry.baseRow || Object.keys(entry.baseRow).length === 0) continue
@@ -2002,10 +2004,15 @@ async function seedCustomerStressTest(
           entity_id: entry.recordId,
           organization_id: entry.organizationId,
           tenant_id: entry.tenantId,
-          doc: buildIndexDocument(entry.baseRow, entry.customFields, {
-            organizationId: entry.organizationId,
-            tenantId: entry.tenantId,
-          }),
+          doc: buildIndexDocument(
+            entry.baseRow,
+            entry.customFields,
+            {
+              organizationId: entry.organizationId,
+              tenantId: entry.tenantId,
+            },
+            { entityType, config: searchConfig },
+          ),
           index_version: 1,
           created_at: entry.createdAt,
           updated_at: entry.updatedAt,

package/src/modules/customers/components/detail/ScheduleActivityDialog.tsx

@@ -99,6 +99,8 @@ interface ScheduleActivityDialogProps {
   onActivityCreated?: () => void
   /** When provided, dialog opens in edit mode with pre-filled data */
   editData?: ScheduleActivityEditData | null
+  /** Default country ISO2 code for phone number input when value is empty/unparsed */
+  defaultCountryIso2?: string
 }
 
 export function ScheduleActivityDialog({
@@ -111,6 +113,7 @@ export function ScheduleActivityDialog({
   entityType,
   onActivityCreated,
   editData,
+  defaultCountryIso2,
 }: ScheduleActivityDialogProps) {
   const t = useT()
   const state = useScheduleFormState({ open, editData: editData ?? null })
@@ -689,6 +692,7 @@ export function ScheduleActivityDialog({
               externalError={callPhoneError}
               invalidLabel={callPhoneInvalidMessage}
               minDigits={7}
+              defaultCountryIso2={defaultCountryIso2}
             />
           </div>
         ) : (

package/src/modules/customers/components/formConfig.tsx

@@ -418,7 +418,7 @@ const companyDictionaryFieldDefinitions: DictionaryFieldDefinition[] = [
   },
 ]
 
-const createPrimaryPhoneField = (t: Translator): CrudField => ({
+const createPrimaryPhoneField = (t: Translator, defaultCountryIso2?: string): CrudField => ({
   id: 'primaryPhone',
   label: t('customers.people.form.primaryPhone'),
   type: 'custom',
@@ -447,6 +447,7 @@ const createPrimaryPhoneField = (t: Translator): CrudField => ({
         invalidLabel={t('customers.people.form.primaryPhone.invalid', 'Enter a valid phone number with country code (e.g. +1 212 555 1234)')}
         minDigits={7}
         onDuplicateLookup={!disabled && !error ? duplicateLookup : undefined}
+        defaultCountryIso2={defaultCountryIso2}
       />
     )
   },
@@ -869,7 +870,8 @@ export const createDisplayNameSection = (t: Translator) =>
     )
   }
 
-export const createPersonFormFields = (t: Translator): CrudField[] => {
+export const createPersonFormFields = (t: Translator, options?: { defaultCountryIso2?: string }): CrudField[] => {
+  const defaultCountryIso2 = options?.defaultCountryIso2
   const contactSection = createSectionHeadingField('__contactInformationSection', t('customers.people.form.sections.contactInformation'))
   const companySection = createSectionHeadingField('__companyInformationSection', t('customers.people.form.sections.companyInformation'))
   const dictionaryFields: CrudField[] = dictionaryFieldDefinitions.map((definition) => ({
@@ -930,7 +932,7 @@ export const createPersonFormFields = (t: Translator): CrudField[] => {
     },
     contactSection,
     createPrimaryEmailField(t),
-    createPrimaryPhoneField(t),
+    createPrimaryPhoneField(t, defaultCountryIso2),
     companySection,
     {
       id: 'companyEntityId',
@@ -1225,7 +1227,8 @@ export const createCompanyFormSchema = () =>
     })
     .passthrough()
 
-export const createCompanyFormFields = (t: Translator): CrudField[] => {
+export const createCompanyFormFields = (t: Translator, options?: { defaultCountryIso2?: string }): CrudField[] => {
+  const defaultCountryIso2 = options?.defaultCountryIso2
   const dictionaryFields: CrudField[] = companyDictionaryFieldDefinitions.map((definition) => ({
     id: definition.id,
     label: t(definition.labelKey),
@@ -1270,6 +1273,7 @@ export const createCompanyFormFields = (t: Translator): CrudField[] => {
           placeholder={t('customers.companies.form.primaryPhonePlaceholder', '+1 555 123 4567')}
           invalidLabel={t('customers.people.form.primaryPhone.invalid', 'Enter a valid phone number with country code (e.g. +1 212 555 1234)')}
           minDigits={7}
+          defaultCountryIso2={defaultCountryIso2}
         />
       ),
     } as CrudField,
@@ -1651,8 +1655,8 @@ const buildIndustryLabels = (t: Translator): DictionarySelectLabels => ({
   manageTitle: t('customers.people.form.dictionary.manage'),
 })
 
-export const createCompanyEditFields = (t: Translator): CrudField[] => {
-  const baseFields = createCompanyFormFields(t)
+export const createCompanyEditFields = (t: Translator, options?: { defaultCountryIso2?: string }): CrudField[] => {
+  const baseFields = createCompanyFormFields(t, options)
   const industryLabels = buildIndustryLabels(t)
 
   return baseFields.map((field) => {
@@ -1676,8 +1680,8 @@ export const createCompanyEditFields = (t: Translator): CrudField[] => {
   })
 }
 
-export const createPersonEditFields = (t: Translator): CrudField[] => {
-  const baseFields = createPersonFormFields(t)
+export const createPersonEditFields = (t: Translator, options?: { defaultCountryIso2?: string }): CrudField[] => {
+  const baseFields = createPersonFormFields(t, options)
   return [
     ...baseFields,
     {

package/src/modules/dashboards/api/widgets/data/batch/route.ts

@@ -9,6 +9,8 @@ import {
   createWidgetDataService,
   type WidgetDataRequest,
   WidgetDataValidationError,
+  WidgetDataScanLimitError,
+  WidgetDataEncryptionUnavailableError,
 } from '../../../../services/widgetDataService'
 import { runWidgetDataBatch } from '../../../../lib/widgetDataBatch'
 import type { AnalyticsRegistry } from '../../../../services/analyticsRegistry'
@@ -125,6 +127,8 @@ export async function POST(req: Request) {
       fetchOne: (request) => service.fetchWidgetData(request),
       describeError: (error) =>
         error instanceof WidgetDataValidationError
+        || error instanceof WidgetDataScanLimitError
+        || error instanceof WidgetDataEncryptionUnavailableError
           ? error.message
           : 'An error occurred while processing your request',
     })

package/src/modules/dashboards/api/widgets/data/route.ts

@@ -8,6 +8,8 @@ import {
   createWidgetDataService,
   type WidgetDataRequest,
   WidgetDataValidationError,
+  WidgetDataScanLimitError,
+  WidgetDataEncryptionUnavailableError,
 } from '../../../services/widgetDataService'
 import type { AnalyticsRegistry } from '../../../services/analyticsRegistry'
 import { runApiInterceptorsBefore } from '@open-mercato/shared/lib/crud/interceptor-runner'
@@ -129,6 +131,15 @@ export async function POST(req: Request) {
     if (err instanceof WidgetDataValidationError) {
       return NextResponse.json({ error: err.message }, { status: 400 })
     }
+    // The dataset is too large to group in application code; surface why rather than a masked 500.
+    if (err instanceof WidgetDataScanLimitError) {
+      return NextResponse.json({ error: err.message }, { status: 422 })
+    }
+    // Encryption is configured but currently unresolvable. Refusing the request keeps ciphertext and
+    // silently-wrong buckets out of the response, and 503 tells the client it is worth retrying.
+    if (err instanceof WidgetDataEncryptionUnavailableError) {
+      return NextResponse.json({ error: err.message }, { status: 503 })
+    }
     return NextResponse.json(
       { error: 'An error occurred while processing your request' },
       { status: 500 },
@@ -156,8 +167,18 @@ const widgetDataPostDoc: OpenApiMethodDoc = {
   errors: [
     { status: 400, description: 'Invalid request payload', schema: dashboardsErrorSchema },
     { status: 401, description: 'Authentication required', schema: dashboardsErrorSchema },
+    {
+      status: 422,
+      description: 'Too many rows to group an encrypted field in application code',
+      schema: dashboardsErrorSchema,
+    },
     { status: 403, description: 'Missing analytics.view feature', schema: dashboardsErrorSchema },
     { status: 500, description: 'Internal server error', schema: dashboardsErrorSchema },
+    {
+      status: 503,
+      description: 'Encryption is configured but the group source cannot currently be resolved',
+      schema: dashboardsErrorSchema,
+    },
   ],
 }
 

package/src/modules/dashboards/lib/aggregations.ts

@@ -97,54 +97,56 @@ export type BuildAggregationQueryOptions = {
   registry: AnalyticsRegistry
 }
 
-export function buildAggregationQuery(options: BuildAggregationQueryOptions): AggregationQuery | null {
-  const { registry } = options
-  const config = registry.getEntityTypeConfig(options.entityType)
-  if (!config) return null
-
-  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
-  if (!metricMapping) return null
-
-  const params: unknown[] = []
+export type ResolvedGroupExpression = {
+  expression: string
+  /** Column the group expression reads from — the encryption map is keyed by this. */
+  dbColumn: string
+  /** JSONB path below `dbColumn`, when the groupBy field used path notation. */
+  jsonPath: string | null
+}
 
-  const tableName = config.schema ? `"${config.schema}"."${config.tableName}"` : `"${config.tableName}"`
-  const aggregateExpr = buildAggregateExpression(options.metric.aggregate, metricMapping.dbColumn)
+/**
+ * Resolves the SQL expression a groupBy field maps to, together with the underlying column so
+ * callers can decide whether the source is encrypted at rest before grouping over it (#4622).
+ */
+export function resolveGroupExpression(
+  registry: AnalyticsRegistry,
+  entityType: string,
+  groupBy: { field: string; granularity?: DateGranularity },
+): ResolvedGroupExpression | null {
+  const groupMapping = registry.getFieldMapping(entityType, groupBy.field)
 
-  let selectClause = `SELECT ${aggregateExpr} AS value`
-  let groupByClause = ''
-  let orderByClause = ''
-  let limitClause = ''
-
-  if (options.groupBy) {
-    let groupMapping = registry.getFieldMapping(options.entityType, options.groupBy.field)
-    let groupExpr: string | null = null
-
-    // Handle JSONB path notation (e.g., shippingAddressSnapshot.region)
-    if (!groupMapping && options.groupBy.field.includes('.')) {
-      const [baseField, ...pathParts] = options.groupBy.field.split('.')
-      const baseMapping = registry.getFieldMapping(options.entityType, baseField)
-      if (baseMapping?.type === 'jsonb') {
-        groupExpr = buildJsonbFieldExpression(baseMapping.dbColumn, pathParts.join('.'))
-      }
-    } else if (groupMapping) {
-      if (groupMapping.type === 'timestamp' && options.groupBy.granularity) {
-        groupExpr = buildDateTruncExpression(groupMapping.dbColumn, options.groupBy.granularity)
-      } else {
-        groupExpr = groupMapping.dbColumn
-      }
+  // Handle JSONB path notation (e.g., shippingAddressSnapshot.region)
+  if (!groupMapping && groupBy.field.includes('.')) {
+    const [baseField, ...pathParts] = groupBy.field.split('.')
+    const baseMapping = registry.getFieldMapping(entityType, baseField)
+    if (baseMapping?.type !== 'jsonb') return null
+    const jsonPath = pathParts.join('.')
+    return {
+      expression: buildJsonbFieldExpression(baseMapping.dbColumn, jsonPath),
+      dbColumn: baseMapping.dbColumn,
+      jsonPath,
     }
+  }
 
-    if (groupExpr) {
-      selectClause = `SELECT ${groupExpr} AS group_key, ${aggregateExpr} AS value`
-      groupByClause = `GROUP BY ${groupExpr}`
-      orderByClause = `ORDER BY value DESC`
+  if (!groupMapping) return null
 
-      if (options.groupBy.limit && options.groupBy.limit > 0) {
-        limitClause = `LIMIT ${Math.min(options.groupBy.limit, 100)}`
-      }
+  if (groupMapping.type === 'timestamp' && groupBy.granularity) {
+    return {
+      expression: buildDateTruncExpression(groupMapping.dbColumn, groupBy.granularity),
+      dbColumn: groupMapping.dbColumn,
+      jsonPath: null,
     }
   }
 
+  return { expression: groupMapping.dbColumn, dbColumn: groupMapping.dbColumn, jsonPath: null }
+}
+
+function buildWhereClause(
+  options: Pick<BuildAggregationQueryOptions, 'entityType' | 'dateRange' | 'filters' | 'scope' | 'registry'>,
+): { clause: string; params: unknown[] } {
+  const { registry } = options
+  const params: unknown[] = []
   const whereClauses: string[] = []
 
   whereClauses.push(`tenant_id = ?`)
@@ -215,11 +217,88 @@ export function buildAggregationQuery(options: BuildAggregationQueryOptions): Ag
     }
   }
 
-  const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : ''
+  return { clause: whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '', params }
+}
+
+function resolveTableName(config: EntityTypeConfig): string {
+  return config.schema ? `"${config.schema}"."${config.tableName}"` : `"${config.tableName}"`
+}
+
+export function buildAggregationQuery(options: BuildAggregationQueryOptions): AggregationQuery | null {
+  const { registry } = options
+  const config = registry.getEntityTypeConfig(options.entityType)
+  if (!config) return null
+
+  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
+  if (!metricMapping) return null
+
+  const tableName = resolveTableName(config)
+  const aggregateExpr = buildAggregateExpression(options.metric.aggregate, metricMapping.dbColumn)
+
+  let selectClause = `SELECT ${aggregateExpr} AS value`
+  let groupByClause = ''
+  let orderByClause = ''
+  let limitClause = ''
+
+  if (options.groupBy) {
+    const resolved = resolveGroupExpression(registry, options.entityType, options.groupBy)
+
+    if (resolved) {
+      selectClause = `SELECT ${resolved.expression} AS group_key, ${aggregateExpr} AS value`
+      groupByClause = `GROUP BY ${resolved.expression}`
+      // NULLS LAST is stated explicitly (PostgreSQL defaults DESC to NULLS FIRST) so a group limit
+      // keeps the highest-value buckets instead of the empty ones, and so the application-side
+      // encrypted path can mirror the same ordering (#4622).
+      orderByClause = `ORDER BY value DESC NULLS LAST`
+
+      if (options.groupBy.limit && options.groupBy.limit > 0) {
+        limitClause = `LIMIT ${Math.min(options.groupBy.limit, 100)}`
+      }
+    }
+  }
+
+  const where = buildWhereClause(options)
+
+  const sql = [selectClause, `FROM ${tableName}`, where.clause, groupByClause, orderByClause, limitClause]
+    .filter(Boolean)
+    .join(' ')
+
+  return { sql, params: where.params }
+}
+
+export type BuildGroupSourceRowsQueryOptions = Omit<BuildAggregationQueryOptions, 'groupBy'> & {
+  /** Column holding the (encrypted) group source, resolved via `resolveGroupExpression`. */
+  groupColumn: string
+  /** Hard cap on scanned rows; callers fetch `rowLimit + 1` to detect overflow. */
+  rowLimit: number
+}
+
+/**
+ * Builds a per-row query for group sources that cannot be grouped in SQL because the column is
+ * encrypted at rest. Returns the raw group source alongside the metric value so the caller can
+ * decrypt, then aggregate in application code (#4622).
+ */
+export function buildGroupSourceRowsQuery(options: BuildGroupSourceRowsQueryOptions): AggregationQuery | null {
+  const { registry } = options
+  const config = registry.getEntityTypeConfig(options.entityType)
+  if (!config) return null
+
+  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
+  if (!metricMapping) return null
+
+  if (!isSafeIdentifier(options.groupColumn)) {
+    throw new Error(`Invalid group column: ${options.groupColumn}`)
+  }
 
-  const sql = [selectClause, `FROM ${tableName}`, whereClause, groupByClause, orderByClause, limitClause]
+  const where = buildWhereClause(options)
+  const sql = [
+    `SELECT ${options.groupColumn} AS group_source, ${metricMapping.dbColumn} AS metric_value`,
+    `FROM ${resolveTableName(config)}`,
+    where.clause,
+    `LIMIT ${Math.max(1, Math.floor(options.rowLimit)) + 1}`,
+  ]
     .filter(Boolean)
     .join(' ')
 
-  return { sql, params }
+  return { sql, params: where.params }
 }