@open-mercato/core 0.6.7-develop.6696.1.4236709f7e → 0.6.7-develop.6725.1.07a748cfc2

package/src/modules/dashboards/services/widgetDataService.ts

@@ -13,19 +13,42 @@ import {
   determineChangeDirection,
   isValidDateRangePreset,
 } from '@open-mercato/ui/backend/date-range'
+import { parseDecryptedFieldValue } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TenantDek } from '@open-mercato/shared/lib/encryption/kms'
+import { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'
 import {
   type AggregateFunction,
   type DateGranularity,
   buildAggregationQuery,
+  buildGroupSourceRowsQuery,
+  resolveGroupExpression,
 } from '../lib/aggregations'
+import {
+  type ExactDecimal,
+  EXACT_DECIMAL_ZERO,
+  addExactDecimal,
+  compareExactDecimal,
+  exactDecimalToNumber,
+  parseExactDecimal,
+} from '../lib/exactDecimal'
 import type { AnalyticsRegistry } from './analyticsRegistry'
 
 const WIDGET_DATA_CACHE_TTL = 120_000
 const WIDGET_DATA_SEGMENT_TTL = 86_400_000
 const WIDGET_DATA_SEGMENT_KEY = 'widget-data:__segment__'
 
+/**
+ * Encrypted group sources cannot be grouped by the database, so the rows are scanned and
+ * aggregated in application code. The cap keeps that scan bounded; overflowing it fails loudly
+ * instead of charting a silently truncated result (#4622).
+ */
+const ENCRYPTED_GROUP_SCAN_LIMIT = 20_000
+
 const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
 
+const logger = createLogger('dashboards').child({ component: 'widget-data' })
+
 export class WidgetDataValidationError extends Error {
   constructor(message: string) {
     super(message)
@@ -33,12 +56,120 @@ export class WidgetDataValidationError extends Error {
   }
 }
 
+export class WidgetDataScanLimitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataScanLimitError'
+  }
+}
+
+/**
+ * Raised when encryption is configured but the group source cannot currently be resolved — an
+ * unhealthy KMS, an unreadable encryption map, or a missing tenant DEK. Grouping would either read
+ * ciphertext in SQL or silently collapse every encrypted row into "Unknown", so the request fails
+ * closed instead (#4622).
+ */
+export class WidgetDataEncryptionUnavailableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataEncryptionUnavailableError'
+  }
+}
+
+type EncryptedGroupSource = {
+  entityId: string
+  dbColumn: string
+  jsonPath: string | null
+}
+
 function assertSafeIdentifier(value: string, name: string): void {
   if (!SAFE_IDENTIFIER_PATTERN.test(value)) {
     throw new Error(`Invalid ${name}: ${value}`)
   }
 }
 
+/**
+ * Encryption maps may register a field in either casing (`findKey` in the encryption service
+ * accepts both), so match the analytics column tolerantly rather than by exact snake_case.
+ */
+function matchesColumn(fieldName: string, dbColumn: string): boolean {
+  const normalize = (value: string) => value.replace(/_/g, '').toLowerCase()
+  return normalize(fieldName) === normalize(dbColumn)
+}
+
+function readJsonPath(value: unknown, path: string): unknown {
+  let current = value
+  for (const part of path.split('.')) {
+    if (current === null || typeof current !== 'object') return null
+    current = (current as Record<string, unknown>)[part]
+  }
+  return current
+}
+
+/**
+ * Running aggregate state for one group. Values are folded in as they are scanned — the bucket
+ * never holds the row set — so the scan cost stays linear and independent of the row cap.
+ */
+type GroupBucket = {
+  /** Rows with a non-null metric column, mirroring SQL `COUNT(column)`. */
+  count: number
+  /** Rows whose metric parsed as a decimal, mirroring the row set SQL aggregates operate on. */
+  numericCount: number
+  /** Exact running sum, so money never accumulates in binary floating point. */
+  sum: ExactDecimal
+  min: ExactDecimal | null
+  max: ExactDecimal | null
+}
+
+function createGroupBucket(): GroupBucket {
+  return { count: 0, numericCount: 0, sum: EXACT_DECIMAL_ZERO, min: null, max: null }
+}
+
+function foldMetricValue(bucket: GroupBucket, value: ExactDecimal): void {
+  bucket.numericCount += 1
+  bucket.sum = addExactDecimal(bucket.sum, value)
+  if (bucket.min === null || compareExactDecimal(value, bucket.min) < 0) bucket.min = value
+  if (bucket.max === null || compareExactDecimal(value, bucket.max) > 0) bucket.max = value
+}
+
+/**
+ * Mirrors the SQL semantics of `buildAggregateExpression` for application-side aggregation. That
+ * expression wraps `SUM`/`AVG` in `COALESCE(..., 0)`, so an empty value set aggregates to `0` on
+ * both paths, while the uncoalesced `MIN`/`MAX` keep PostgreSQL's `NULL`. An encrypted group source
+ * must not report a different value than the same data would report in plaintext (#4622).
+ */
+function aggregateBucket(aggregate: AggregateFunction, bucket: GroupBucket): number | null {
+  switch (aggregate) {
+    case 'count':
+      return bucket.count
+    case 'sum':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum)
+    case 'avg':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum) / bucket.numericCount
+    case 'min':
+      return bucket.min === null ? null : exactDecimalToNumber(bucket.min)
+    case 'max':
+      return bucket.max === null ? null : exactDecimalToNumber(bucket.max)
+    default:
+      return bucket.count
+  }
+}
+
+/**
+ * Mirrors the SQL path's `ORDER BY value DESC NULLS LAST`. PostgreSQL defaults DESC to NULLS FIRST,
+ * which would let empty buckets displace real ones under a group limit, so both paths state the
+ * policy explicitly: highest value first, buckets without a value last.
+ */
+function compareWidgetDataItemsByValueDesc(
+  left: { value: number | null },
+  right: { value: number | null },
+): number {
+  if (left.value === null && right.value === null) return 0
+  if (left.value === null) return 1
+  if (right.value === null) return -1
+  return right.value - left.value
+}
+
 export type WidgetDataRequest = {
   entityType: string
   metric: {
@@ -229,6 +360,13 @@ export class WidgetDataService {
     request: WidgetDataRequest,
     dateRange?: { start: Date; end: Date },
   ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    if (request.groupBy) {
+      const encryptedSource = await this.resolveEncryptedGroupSource(request.entityType, request.groupBy)
+      if (encryptedSource) {
+        return this.executeEncryptedGroupQuery(request, encryptedSource, dateRange)
+      }
+    }
+
     const query = buildAggregationQuery({
       entityType: request.entityType,
       metric: request.metric,
@@ -264,6 +402,193 @@ export class WidgetDataService {
     return { value: singleValue, data: [] }
   }
 
+  /**
+   * Reports the encrypted column a groupBy field reads from, or null when the source is stored in
+   * plaintext and can be grouped by the database. Grouping over an encrypted column in SQL buckets
+   * ciphertext and renders it to the user (#4622).
+   */
+  private async resolveEncryptedGroupSource(
+    entityType: string,
+    groupBy: NonNullable<WidgetDataRequest['groupBy']>,
+  ): Promise<EncryptedGroupSource | null> {
+    // Encryption is not configured for this deployment, so no column can hold ciphertext and the
+    // database may group the source directly.
+    if (!isTenantDataEncryptionEnabled()) return null
+
+    const resolved = resolveGroupExpression(this.registry, entityType, groupBy)
+    if (!resolved) return null
+
+    const tableName = this.registry.getEntityTypeConfig(entityType)?.tableName
+    if (!tableName) return null
+
+    // Without an encryption entity id the table is outside the encryption map entirely, which is
+    // the same state the encrypting subscriber sees when it skips the row.
+    const entityId = this.resolveEncryptionEntityId(tableName)
+    if (!entityId) return null
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    if (!encryptionService) {
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption service unavailable`,
+      )
+    }
+
+    const organizationId = this.resolveOrganizationId()
+    let encryptedFields: string[]
+    try {
+      // Deliberately independent of KMS health: the map describes how the rows were written, and
+      // an unhealthy KMS must not be read as "this column is plaintext" (#4622).
+      encryptedFields = await encryptionService.getEncryptedFieldNames(
+        entityId,
+        this.scope.tenantId,
+        organizationId,
+        { ignoreRuntimeHealth: true },
+      )
+    } catch (err) {
+      logger.error('Failed to resolve encrypted fields for widget grouping', { err, entityId, entityType })
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption map lookup failed`,
+      )
+    }
+
+    if (!encryptedFields.some((field) => matchesColumn(field, resolved.dbColumn))) return null
+
+    if (resolved.jsonPath === null && groupBy.granularity) {
+      throw new WidgetDataValidationError(
+        `Cannot group encrypted field by granularity: ${groupBy.field}`,
+      )
+    }
+
+    return { entityId, dbColumn: resolved.dbColumn, jsonPath: resolved.jsonPath }
+  }
+
+  /**
+   * Aggregates an encrypted group source in application code: rows are scanned, the group column is
+   * decrypted, and only the resulting plaintext keys are grouped. Values that cannot be decrypted
+   * collapse into the null ("Unknown") bucket so ciphertext never reaches the response.
+   */
+  private async executeEncryptedGroupQuery(
+    request: WidgetDataRequest,
+    source: EncryptedGroupSource,
+    dateRange?: { start: Date; end: Date },
+  ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    const query = buildGroupSourceRowsQuery({
+      entityType: request.entityType,
+      metric: request.metric,
+      dateRange: dateRange && request.dateRange ? { field: request.dateRange.field, ...dateRange } : undefined,
+      filters: request.filters,
+      scope: this.scope,
+      registry: this.registry,
+      groupColumn: source.dbColumn,
+      rowLimit: ENCRYPTED_GROUP_SCAN_LIMIT,
+    })
+
+    if (!query) {
+      throw new Error('Failed to build aggregation query')
+    }
+
+    const rows = await this.em.getConnection().execute(query.sql, query.params)
+    const results = Array.isArray(rows) ? rows : []
+
+    if (results.length > ENCRYPTED_GROUP_SCAN_LIMIT) {
+      throw new WidgetDataScanLimitError(
+        `Too many rows to group encrypted field ${request.groupBy?.field} (limit ${ENCRYPTED_GROUP_SCAN_LIMIT})`,
+      )
+    }
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    let dek: TenantDek | null = null
+    try {
+      dek = encryptionService ? await encryptionService.getDek(this.scope.tenantId) : null
+    } catch (err) {
+      logger.error('Failed to resolve the tenant DEK for widget grouping', { err, entityId: source.entityId })
+      dek = null
+    }
+
+    const buckets = new Map<string | null, GroupBucket>()
+    let undecryptableRows = 0
+
+    for (const row of results as Array<Record<string, unknown>>) {
+      const resolvedKey = this.resolveDecryptedGroupKey(row.group_source, source, dek?.key ?? null)
+      // An undecryptable source joins the null ("Unknown") bucket rather than being dropped, so the
+      // widget total still matches the underlying rows.
+      if (resolvedKey === undefined) undecryptableRows += 1
+      const groupKey = resolvedKey === undefined ? null : resolvedKey
+
+      let bucket = buckets.get(groupKey)
+      if (!bucket) {
+        bucket = createGroupBucket()
+        buckets.set(groupKey, bucket)
+      }
+
+      const metricValue = row.metric_value
+      if (metricValue === null || metricValue === undefined) continue
+      bucket.count += 1
+      const numeric = parseExactDecimal(metricValue)
+      if (numeric) foldMetricValue(bucket, numeric)
+    }
+
+    if (undecryptableRows > 0) {
+      // No DEK at all means every ciphertext row would collapse into "Unknown" and the widget would
+      // report a confidently wrong distribution, so fail closed rather than chart it (#4622).
+      if (!dek) {
+        throw new WidgetDataEncryptionUnavailableError(
+          `Cannot group encrypted field ${request.groupBy?.field}: tenant encryption key is unavailable`,
+        )
+      }
+      logger.warn('Grouped rows with an undecryptable group source as unknown', {
+        entityId: source.entityId,
+        column: source.dbColumn,
+        rows: undecryptableRows,
+      })
+    }
+
+    let data: WidgetDataItem[] = Array.from(buckets.entries())
+      .map(([groupKey, bucket]) => ({ groupKey, value: aggregateBucket(request.metric.aggregate, bucket) }))
+      .sort(compareWidgetDataItemsByValueDesc)
+
+    if (request.groupBy?.limit && request.groupBy.limit > 0) {
+      data = data.slice(0, Math.min(request.groupBy.limit, 100))
+    }
+
+    if (request.groupBy?.resolveLabels) {
+      data = await this.resolveGroupLabels(data, request.entityType, request.groupBy.field)
+    }
+
+    const totalValue = data.reduce((sum: number, item: WidgetDataItem) => sum + (item.value ?? 0), 0)
+    return { value: totalValue, data }
+  }
+
+  /**
+   * Returns the plaintext group key for a scanned row, `null` for an empty/absent value, or
+   * `undefined` when the source is ciphertext that could not be decrypted.
+   */
+  private resolveDecryptedGroupKey(
+    rawValue: unknown,
+    source: EncryptedGroupSource,
+    dek: string | null,
+  ): string | null | undefined {
+    if (rawValue === null || rawValue === undefined) return null
+
+    let value: unknown = rawValue
+    if (typeof value === 'string' && this.isEncryptedPayload(value)) {
+      if (!dek) return undefined
+      const decrypted = this.decryptWithDek(value, dek)
+      if (decrypted === null) return undefined
+      value = parseDecryptedFieldValue(decrypted)
+    }
+
+    if (source.jsonPath !== null) {
+      value = readJsonPath(value, source.jsonPath)
+    }
+
+    if (value === null || value === undefined || value === '') return null
+    if (typeof value === 'object') return null
+    const key = String(value)
+    // Defense in depth: a nested value that is itself ciphertext must never reach the response.
+    return this.isEncryptedPayload(key) ? undefined : key
+  }
+
   private async resolveGroupLabels(
     data: WidgetDataItem[],
     entityType: string,
@@ -272,10 +597,13 @@ export class WidgetDataService {
     const config = this.registry.getLabelResolverConfig(entityType, groupByField)
 
     if (!config) {
-      return data.map((item) => ({
-        ...item,
-        groupLabel: item.groupKey != null && item.groupKey !== '' ? String(item.groupKey) : undefined,
-      }))
+      return data.map((item) => {
+        if (item.groupKey == null || item.groupKey === '') return { ...item, groupLabel: undefined }
+        const label = String(item.groupKey)
+        // A ciphertext group key has no meaningful label; echoing it would render encrypted data
+        // into the chart legend (#4622).
+        return { ...item, groupLabel: this.isEncryptedPayload(label) ? undefined : label }
+      })
     }
 
     const ids = data
@@ -468,6 +796,16 @@ export class WidgetDataService {
     }
   }
 
+  /**
+   * Resolves the encryption entity id for an analytics table. A request-scoped `EntityManager` fork
+   * frequently reports an empty metadata registry, which used to make every group source look
+   * unencrypted and send the request back to the ciphertext-grouping SQL path (#4622). The table
+   * name alone is enough for the entity-id lookup, so it is the fallback.
+   */
+  private resolveEncryptionEntityId(tableName: string): string | null {
+    return this.resolveEntityId(this.resolveEntityMetadata(tableName)) ?? this.resolveEntityId({ tableName })
+  }
+
   private isEncryptedPayload(value: string): boolean {
     const parts = value.split(':')
     return parts.length === 4 && parts[3] === 'v1'

package/src/modules/feature_toggles/components/FeatureGuard.tsx

@@ -8,23 +8,30 @@ export type FeatureGuardProps = {
   children: React.ReactNode
   fallback?: React.ReactNode
   loadingFallback?: React.ReactNode
+  defaultValue?: boolean
 }
 
 /**
  * FeatureGuard component that conditionally renders children based on feature toggle state.
- * 
+ *
  * @param id - The feature toggle identifier
  * @param children - Content to render when the feature is enabled
  * @param fallback - Optional content to render when the feature is disabled
  * @param loadingFallback - Optional content to render while loading the feature state
+ * @param defaultValue - Toggle value assumed when the check cannot be resolved
+ *   (undefined toggle, type mismatch, network or permission failure). Defaults
+ *   to `false`; pass `true` to keep guarded UI visible when the check fails.
+ *   Distinct from `fallback`, which is what gets rendered once the feature is
+ *   known to be disabled.
  */
 export function FeatureGuard({
   id,
   children,
   fallback = null,
   loadingFallback = null,
+  defaultValue = false,
 }: FeatureGuardProps) {
-  const { enabled, isLoading } = useFeatureFlagBoolean({ id })
+  const { enabled, isLoading } = useFeatureFlagBoolean({ id, defaultValue })
 
   if (isLoading) {
     return <>{loadingFallback}</>

package/src/modules/feature_toggles/components/hooks/staleTime.ts

@@ -0,0 +1,5 @@
+// Mirrors the server-side toggle resolution cache TTL in
+// `lib/feature-flag-check.ts`, so several components reading the same toggle
+// share one request instead of refetching a value the server would not have
+// re-resolved anyway.
+export const FEATURE_FLAG_STALE_TIME_MS = 60_000

package/src/modules/feature_toggles/components/hooks/useFeatureFlagBoolean.ts

@@ -2,9 +2,19 @@
 
 import { useQuery } from '@tanstack/react-query'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { FEATURE_FLAG_STALE_TIME_MS } from './staleTime'
 
 export type UseFeatureFlagOptions = {
   id: string
+  /**
+   * Value used while the check is in flight and whenever the toggle cannot be
+   * resolved (undefined toggle, type mismatch, network or permission failure).
+   *
+   * Defaults to `false` so an unresolved toggle keeps a feature switched off.
+   * Pass `true` for toggles that hide existing UI — there a failed check must
+   * not make the feature disappear.
+   */
+  defaultValue?: boolean
 }
 
 export type UseFeatureFlagResult = {
@@ -21,6 +31,7 @@ type Result<T> = {
 }
 
 export function useFeatureFlagBoolean(options: UseFeatureFlagOptions): UseFeatureFlagResult {
+  const defaultValue = options.defaultValue ?? false
   const query = useQuery({
     queryKey: ['featureToggles', 'check', options?.id],
     queryFn: async () => {
@@ -37,9 +48,10 @@ export function useFeatureFlagBoolean(options: UseFeatureFlagOptions): UseFeatur
       return result
     },
     enabled: !!options.id,
+    staleTime: FEATURE_FLAG_STALE_TIME_MS,
   })
 
-  const enabled = query.data?.ok ? query.data.value : false
+  const enabled = query.data?.ok ? query.data.value : defaultValue
   const isLoading = query.isLoading
 
   return {

package/src/modules/feature_toggles/components/hooks/useFeatureFlagJson.ts

@@ -2,9 +2,16 @@
 
 import { useQuery } from '@tanstack/react-query'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { FEATURE_FLAG_STALE_TIME_MS } from './staleTime'
 
-export type UseFeatureFlagJsonOptions = {
+export type UseFeatureFlagJsonOptions<T = unknown> = {
     id: string
+    /**
+     * Value used while the check is in flight and whenever the toggle cannot be
+     * resolved (undefined toggle, type mismatch, network or permission failure).
+     * Defaults to `null`.
+     */
+    defaultValue?: T | null
 }
 
 export type UseFeatureFlagJsonResult<T = unknown> = {
@@ -20,7 +27,8 @@ type Result<T> = {
     error: unknown
 }
 
-export function useFeatureFlagJson<T = unknown>(options: UseFeatureFlagJsonOptions): UseFeatureFlagJsonResult<T> {
+export function useFeatureFlagJson<T = unknown>(options: UseFeatureFlagJsonOptions<T>): UseFeatureFlagJsonResult<T> {
+    const defaultValue = options.defaultValue ?? null
     const query = useQuery({
         queryKey: ['featureToggles', 'check', 'json', options?.id],
         queryFn: async () => {
@@ -37,9 +45,10 @@ export function useFeatureFlagJson<T = unknown>(options: UseFeatureFlagJsonOptio
             return result
         },
         enabled: !!options.id,
+        staleTime: FEATURE_FLAG_STALE_TIME_MS,
     })
 
-    const value = query.data?.ok ? query.data.value : null
+    const value = query.data?.ok ? query.data.value : defaultValue
     const isLoading = query.isLoading
 
     return {

package/src/modules/feature_toggles/components/hooks/useFeatureFlagNumber.ts

@@ -2,9 +2,16 @@
 
 import { useQuery } from '@tanstack/react-query'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { FEATURE_FLAG_STALE_TIME_MS } from './staleTime'
 
 export type UseFeatureFlagNumberOptions = {
     id: string
+    /**
+     * Value used while the check is in flight and whenever the toggle cannot be
+     * resolved (undefined toggle, type mismatch, network or permission failure).
+     * Defaults to `null`.
+     */
+    defaultValue?: number | null
 }
 
 export type UseFeatureFlagNumberResult = {
@@ -21,6 +28,7 @@ type Result<T> = {
 }
 
 export function useFeatureFlagNumber(options: UseFeatureFlagNumberOptions): UseFeatureFlagNumberResult {
+    const defaultValue = options.defaultValue ?? null
     const query = useQuery({
         queryKey: ['featureToggles', 'check', 'number', options?.id],
         queryFn: async () => {
@@ -37,9 +45,10 @@ export function useFeatureFlagNumber(options: UseFeatureFlagNumberOptions): UseF
             return result
         },
         enabled: !!options.id,
+        staleTime: FEATURE_FLAG_STALE_TIME_MS,
     })
 
-    const value = query.data?.ok ? query.data.value : null
+    const value = query.data?.ok ? query.data.value : defaultValue
     const isLoading = query.isLoading
 
     return {

package/src/modules/feature_toggles/components/hooks/useFeatureFlagString.ts

@@ -2,9 +2,16 @@
 
 import { useQuery } from '@tanstack/react-query'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { FEATURE_FLAG_STALE_TIME_MS } from './staleTime'
 
 export type UseFeatureFlagStringOptions = {
     id: string
+    /**
+     * Value used while the check is in flight and whenever the toggle cannot be
+     * resolved (undefined toggle, type mismatch, network or permission failure).
+     * Defaults to `null`.
+     */
+    defaultValue?: string | null
 }
 
 export type UseFeatureFlagStringResult = {
@@ -21,6 +28,7 @@ type Result<T> = {
 }
 
 export function useFeatureFlagString(options: UseFeatureFlagStringOptions): UseFeatureFlagStringResult {
+    const defaultValue = options.defaultValue ?? null
     const query = useQuery({
         queryKey: ['featureToggles', 'check', 'string', options?.id],
         queryFn: async () => {
@@ -37,9 +45,10 @@ export function useFeatureFlagString(options: UseFeatureFlagStringOptions): UseF
             return result
         },
         enabled: !!options.id,
+        staleTime: FEATURE_FLAG_STALE_TIME_MS,
     })
 
-    const value = query.data?.ok ? query.data.value : null
+    const value = query.data?.ok ? query.data.value : defaultValue
     const isLoading = query.isLoading
 
     return {

package/src/modules/inbox_ops/api/proposals/route.ts

@@ -4,6 +4,8 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import type { FilterQuery } from '@mikro-orm/postgresql'
 import { findAndCountWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { findEntityIdsBySearchTokens, type SearchTokenDatabase } from '@open-mercato/shared/lib/search/tokenLookup'
+import { E } from '#generated/entities.ids.generated'
 import { InboxProposal, InboxEmail, InboxProposalAction, InboxDiscrepancy, type InboxProposalCategory } from '../../data/entities'
 import { proposalListQuerySchema } from '../../data/validators'
 import { resolveRequestContext, UnauthorizedError } from '../routeHelpers'
@@ -47,7 +49,24 @@ export async function GET(req: Request) {
       }
     }
     if (query.search) {
-      where.summary = { $ilike: `%${escapeLikePattern(query.search)}%` }
+      // `summary` is covered by the inbox_ops encryption map, so an ILIKE alone
+      // compares the pattern against ciphertext and matches nothing once
+      // encryption is on. Union it with the token index, which stores hashes of
+      // the plaintext. Issue #2990.
+      const searchOr: FilterQuery<InboxProposal>[] = [
+        { summary: { $ilike: `%${escapeLikePattern(query.search)}%` } },
+      ]
+      const tokenMatch = await findEntityIdsBySearchTokens({
+        db: ctx.em.getKysely<SearchTokenDatabase>(),
+        entityType: E.inbox_ops.inbox_proposal,
+        query: query.search,
+        fields: ['summary'],
+        scope: { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+      })
+      if (tokenMatch.matched && tokenMatch.ids.length) {
+        searchOr.push({ id: { $in: tokenMatch.ids } })
+      }
+      where.$or = searchOr
     }
 
     const offset = (query.page - 1) * query.pageSize

package/src/modules/inbox_ops/subscribers/search-reindex-proposal-created.ts

@@ -0,0 +1,39 @@
+export const metadata = {
+  event: 'inbox_ops.proposal.created',
+  persistent: false,
+  id: 'inbox_ops:query-index-reindex-proposal-created',
+}
+
+type Payload = {
+  proposalId?: string
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+type EventBus = { emitEvent: (name: string, body: unknown, options?: unknown) => Promise<void> }
+type HandlerContext = { resolve: <T = unknown>(name: string) => T }
+
+export default async function handle(payload: Payload, ctx: HandlerContext): Promise<void> {
+  const recordId = typeof payload.proposalId === 'string' ? payload.proposalId : null
+  const tenantId = typeof payload.tenantId === 'string' ? payload.tenantId : null
+  if (!recordId || !tenantId) return
+
+  let eventBus: EventBus | null = null
+  try {
+    eventBus = ctx.resolve<EventBus>('eventBus')
+  } catch {
+    return
+  }
+
+  await eventBus.emitEvent('query_index.upsert_one', {
+    entityType: 'inbox_ops:inbox_proposal',
+    recordId,
+    organizationId: payload.organizationId ?? null,
+    tenantId,
+    crudAction: 'created',
+    coverageBaseDelta: 1,
+  }, {
+    tenantId,
+    organizationId: payload.organizationId ?? null,
+  }).catch(() => undefined)
+}

package/src/modules/integrations/widgets/injection/external-ids/widget.client.tsx

@@ -87,8 +87,3 @@ export default function ExternalIdsWidget({ data }: InjectionWidgetComponentProp
   )
 }
 
-ExternalIdsWidget.metadata = {
-  id: 'integrations.injection.external-ids',
-  title: 'External IDs',
-  features: ['integrations.view'],
-}