@open-mercato/core 0.6.7-develop.6725.1.07a748cfc2 → 0.6.7-develop.6744.1.0483b18565

package/src/modules/dashboards/widgets/dashboard/pipeline-summary/config.ts

@@ -1,11 +1,58 @@
 import { type DateRangePreset, isValidDateRangePreset } from '@open-mercato/ui/backend/date-range'
+import type { WidgetDataRequest } from '../../../services/widgetDataService'
+
+// Deal statuses that mean the deal is closed and must stop counting as current pipeline.
+//
+// This is a denylist, not an allowlist: `customer_deals.status` is a lenient `text` column
+// fed by the per-tenant `deal_status` dictionary, so a status unknown to code counts as OPEN
+// and keeps contributing to the chart. That keeps tenant-specific stages visible and mirrors
+// `customers/lib/interactionStatus.ts`, which treats an unknown interaction status as open.
+//
+// Every vocabulary that reaches the column has to be listed here:
+//   - `win` / `loose` are written by the deal closure UI and the kanban board.
+//   - `won` / `lost` are written verbatim by the `customers.update_deal_stage` AI tool, whose
+//     free-form `toStage` is passed straight through to `status`.
+//   - `closed` is a seeded `deal_status` dictionary value, persisted by the dashboards
+//     analytics seed and treated as terminal by the demo-data generator.
+export const CLOSED_DEAL_STATUSES = ['win', 'loose', 'won', 'lost', 'closed'] as const
+
+// A deal is also closed when `closure_outcome` records the outcome, which the deals-summary
+// KPI already treats as terminal: `api/deals/summary/route.ts` counts a deal as won or lost
+// when EITHER `status` OR `closure_outcome` says so. The two columns can disagree — the CRUD
+// API accepts `closureOutcome` on its own, and the AI tool writes `status` without ever setting
+// it — so the chart has to test both signals to agree with those KPI cards (#4668).
+//
+// The `closure_outcome` side is expressed as `IS NULL` rather than as a `neq` denylist for two
+// reasons, and swapping it for `neq` would be a silent regression:
+//   - `closure_outcome` is nullable, and every OPEN deal holds NULL there. `neq` renders as
+//     `column != ?`, and in SQL `NULL != 'won'` is NULL, not true — a `neq` filter would drop
+//     every open deal and empty the chart. `status` has no such problem: it is `text not null
+//     default 'open'`, which is why the status side stays a denylist.
+//   - Unlike `status`, this column is not fed by a per-tenant dictionary. Every write path
+//     validates it against the same closed `z.enum(['won', 'lost'])` (`data/validators.ts`,
+//     `api/deals/[id]/route.ts`, `api/deals/[id]/stats/route.ts`), so a non-null value always
+//     means closed and there is no tenant-specific vocabulary to keep visible.
+export const OPEN_DEAL_CLOSURE_OUTCOME_FILTER = {
+  field: 'closureOutcome',
+  operator: 'is_null',
+} as const
+
+export const PIPELINE_STATUS_SCOPES = ['open', 'all'] as const
+
+export type PipelineStatusScope = typeof PIPELINE_STATUS_SCOPES[number]
 
 export type PipelineSummarySettings = {
   dateRange: DateRangePreset
+  statusScope: PipelineStatusScope
 }
 
 export const DEFAULT_SETTINGS: PipelineSummarySettings = {
   dateRange: 'this_month',
+  statusScope: 'open',
+}
+
+function isValidStatusScope(value: unknown): value is PipelineStatusScope {
+  return typeof value === 'string' && (PIPELINE_STATUS_SCOPES as readonly string[]).includes(value)
 }
 
 export function hydrateSettings(raw: unknown): PipelineSummarySettings {
@@ -13,5 +60,44 @@ export function hydrateSettings(raw: unknown): PipelineSummarySettings {
   const obj = raw as Record<string, unknown>
   return {
     dateRange: isValidDateRangePreset(obj.dateRange) ? obj.dateRange : DEFAULT_SETTINGS.dateRange,
+    statusScope: isValidStatusScope(obj.statusScope) ? obj.statusScope : DEFAULT_SETTINGS.statusScope,
+  }
+}
+
+export function dehydrateSettings(settings: PipelineSummarySettings): Record<string, unknown> {
+  return {
+    dateRange: settings.dateRange,
+    statusScope: settings.statusScope,
+  }
+}
+
+export function buildPipelineDataRequest(settings: PipelineSummarySettings): WidgetDataRequest {
+  const request: WidgetDataRequest = {
+    entityType: 'customers:deals',
+    metric: {
+      field: 'valueAmount',
+      aggregate: 'sum',
+    },
+    groupBy: {
+      field: 'pipelineStage',
+      resolveLabels: true,
+    },
+    dateRange: {
+      field: 'createdAt',
+      preset: settings.dateRange,
+    },
+  }
+
+  if (settings.statusScope === 'open') {
+    request.filters = [
+      ...CLOSED_DEAL_STATUSES.map((status) => ({
+        field: 'status',
+        operator: 'neq' as const,
+        value: status,
+      })),
+      { ...OPEN_DEAL_CLOSURE_OUTCOME_FILTER },
+    ]
   }
+
+  return request
 }

package/src/modules/dashboards/widgets/dashboard/pipeline-summary/widget.client.tsx

@@ -10,7 +10,14 @@ import {
   InlineDateRangeSelect,
   type DateRangePreset,
 } from '@open-mercato/ui/backend/date-range'
-import { DEFAULT_SETTINGS, hydrateSettings, type PipelineSummarySettings } from './config'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import {
+  DEFAULT_SETTINGS,
+  buildPipelineDataRequest,
+  hydrateSettings,
+  type PipelineStatusScope,
+  type PipelineSummarySettings,
+} from './config'
 import type { WidgetDataResponse } from '../../../services/widgetDataService'
 import { formatCurrencyCompact } from '../../../lib/formatters'
 import { createLogger } from '@open-mercato/shared/lib/logger'
@@ -18,23 +25,7 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 const logger = createLogger('dashboards').child({ component: 'pipeline-summary' })
 
 async function fetchPipelineData(settings: PipelineSummarySettings, fetchWidgetData: WidgetDataFetcher): Promise<WidgetDataResponse> {
-  const body = {
-    entityType: 'customers:deals',
-    metric: {
-      field: 'valueAmount',
-      aggregate: 'sum',
-    },
-    groupBy: {
-      field: 'pipelineStage',
-      resolveLabels: true,
-    },
-    dateRange: {
-      field: 'createdAt',
-      preset: settings.dateRange,
-    },
-  }
-
-  return fetchWidgetData<WidgetDataResponse>(body)
+  return fetchWidgetData<WidgetDataResponse>(buildPipelineDataRequest(settings))
 }
 
 function formatStageLabel(stage: unknown, t: (key: string, fallback: string) => string): string {
@@ -97,6 +88,30 @@ const PipelineSummaryWidget: React.FC<DashboardWidgetComponentProps<PipelineSumm
           value={hydrated.dateRange}
           onChange={(dateRange: DateRangePreset) => onSettingsChange({ ...hydrated, dateRange })}
         />
+        <div className="space-y-1.5">
+          <label
+            htmlFor="pipeline-summary-status-scope"
+            className="text-xs font-semibold uppercase text-muted-foreground"
+          >
+            {t('dashboards.analytics.settings.dealStatusScope', 'Deals included')}
+          </label>
+          <Select
+            value={hydrated.statusScope}
+            onValueChange={(value) => onSettingsChange({ ...hydrated, statusScope: value as PipelineStatusScope })}
+          >
+            <SelectTrigger id="pipeline-summary-status-scope" size="sm">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="open">
+                {t('dashboards.analytics.settings.dealStatusScopeOpen', 'Open deals only')}
+              </SelectItem>
+              <SelectItem value="all">
+                {t('dashboards.analytics.settings.dealStatusScopeAll', 'All deals, including won and lost')}
+              </SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
       </div>
     )
   }

package/src/modules/dashboards/widgets/dashboard/pipeline-summary/widget.ts

@@ -1,5 +1,5 @@
 import { lazyDashboardWidget, type DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
-import { DEFAULT_SETTINGS, hydrateSettings, type PipelineSummarySettings } from './config'
+import { DEFAULT_SETTINGS, dehydrateSettings, hydrateSettings, type PipelineSummarySettings } from './config'
 const PipelineSummaryWidget = lazyDashboardWidget(() => import('./widget.client'))
 
 const widget: DashboardWidgetModule<PipelineSummarySettings> = {
@@ -18,7 +18,7 @@ const widget: DashboardWidgetModule<PipelineSummarySettings> = {
   },
   Widget: PipelineSummaryWidget,
   hydrateSettings,
-  dehydrateSettings: (s) => ({ dateRange: s.dateRange }),
+  dehydrateSettings,
 }
 
 export default widget

package/src/modules/dictionaries/api/[dictionaryId]/entries/route.ts

@@ -3,7 +3,11 @@ import { z } from 'zod'
 import { runWithCacheTenant } from '@open-mercato/cache'
 import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictionaries/data/entities'
 import { resolveDictionariesRouteContext, resolveDictionaryActorId } from '@open-mercato/core/modules/dictionaries/api/context'
-import { createDictionaryEntrySchema } from '@open-mercato/core/modules/dictionaries/data/validators'
+import {
+  createDictionaryEntrySchema,
+  listDictionaryEntriesQuerySchema,
+  DICTIONARY_ENTRIES_MAX_LIMIT,
+} from '@open-mercato/core/modules/dictionaries/data/validators'
 import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import {
   runCrudMutationGuardAfterSuccess,
@@ -14,6 +18,7 @@ import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/op
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import {
   createDictionaryEntrySchema as createEntryDocSchema,
+  dictionaryEntriesQuerySchema,
   dictionaryEntryListResponseSchema,
   dictionaryEntryResponseSchema,
   dictionaryIdParamsSchema,
@@ -45,8 +50,10 @@ function buildEntriesCacheKey(params: {
   dictionaryId: string
   organizationId: string | null
   sortMode: string
+  limit: number
+  offset: number
 }): string {
-  return `dictionaries:entries:${params.dictionaryId}:org=${params.organizationId ?? 'null'}:sort=${params.sortMode}`
+  return `dictionaries:entries:${params.dictionaryId}:org=${params.organizationId ?? 'null'}:sort=${params.sortMode}:limit=${params.limit}:offset=${params.offset}`
 }
 
 async function loadDictionary(
@@ -93,6 +100,11 @@ export async function GET(req: Request, ctx: { params?: { dictionaryId?: string
       return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
     }
     const { dictionaryId } = paramsSchema.parse({ dictionaryId: ctx.params?.dictionaryId })
+    const requestUrl = new URL(req.url)
+    const { limit, offset } = listDictionaryEntriesQuerySchema.parse({
+      limit: requestUrl.searchParams.get('limit') ?? undefined,
+      offset: requestUrl.searchParams.get('offset') ?? undefined,
+    })
     const dictionary = await loadDictionary(context, dictionaryId, { allowInherited: true })
     const dictionaryTenantId = dictionary.tenantId
     const dictionaryOrgId = dictionary.organizationId ?? null
@@ -102,9 +114,12 @@ export async function GET(req: Request, ctx: { params?: { dictionaryId?: string
     // decrypted+sorted options payload. The entry writes flow through the
     // command bus (resourceKind dictionaries.entry), which already flushes the
     // matching collection tag post-commit — no new invalidation wiring needed.
-    const cache = isCrudCacheEnabled() ? resolveCrudCache(context.container) : null
+    // Only the default page is cached: keying the cache on caller-supplied
+    // pagination would let any reader mint unbounded distinct cache entries.
+    const isDefaultPage = limit === DICTIONARY_ENTRIES_MAX_LIMIT && offset === 0
+    const cache = isCrudCacheEnabled() && isDefaultPage ? resolveCrudCache(context.container) : null
     const cacheKey = cache
-      ? buildEntriesCacheKey({ dictionaryId, organizationId: dictionaryOrgId, sortMode })
+      ? buildEntriesCacheKey({ dictionaryId, organizationId: dictionaryOrgId, sortMode, limit, offset })
       : null
 
     if (cache && cacheKey) {
@@ -114,15 +129,19 @@ export async function GET(req: Request, ctx: { params?: { dictionaryId?: string
       }
     }
 
+    const entriesFilter = {
+      dictionary,
+      organizationId: dictionary.organizationId,
+      tenantId: dictionary.tenantId,
+    }
+    const total = await context.em.count(DictionaryEntry, entriesFilter)
+    // Bound the decrypt+sort work per request: page membership is decided by a
+    // stable database ordering, and the dictionary's sort mode orders the page.
     const entries = await findWithDecryption(
       context.em,
       DictionaryEntry,
-      {
-        dictionary,
-        organizationId: dictionary.organizationId,
-        tenantId: dictionary.tenantId,
-      },
-      {},
+      entriesFilter,
+      { orderBy: { position: 'asc', id: 'asc' }, limit, offset },
       { tenantId: dictionary.tenantId, organizationId: dictionary.organizationId },
     )
     const sortedEntries = sortDictionaryEntries(entries, sortMode)
@@ -139,6 +158,14 @@ export async function GET(req: Request, ctx: { params?: { dictionaryId?: string
         createdAt: entry.createdAt,
         updatedAt: entry.updatedAt,
       })),
+      total,
+      limit,
+      offset,
+      hasMore: offset + sortedEntries.length < total,
+      // Page membership comes from the database ordering, while the page itself
+      // is ordered in memory. A client assembling several pages has to re-apply
+      // the same comparator, so it needs the mode that produced this ordering.
+      sortMode,
     }
 
     if (cache && cacheKey) {
@@ -265,8 +292,9 @@ export async function POST(req: Request, ctx: { params?: { dictionaryId?: string
 
 const dictionaryEntriesGetDoc: OpenApiMethodDoc = {
   summary: 'List dictionary entries',
-  description: 'Returns entries for the specified dictionary ordered by its configured entry sort mode.',
+  description: `Returns entries for the specified dictionary ordered by its configured entry sort mode. The number of entries returned per request is capped at ${DICTIONARY_ENTRIES_MAX_LIMIT}; use \`limit\` and \`offset\` with the \`total\`/\`hasMore\` response fields to page through larger dictionaries.`,
   tags: [dictionariesTag],
+  query: dictionaryEntriesQuerySchema,
   responses: [
     { status: 200, description: 'Dictionary entries.', schema: dictionaryEntryListResponseSchema },
   ],

package/src/modules/dictionaries/api/openapi.ts

@@ -5,6 +5,7 @@ import {
   updateDictionaryEntrySchema,
   reorderDictionaryEntriesSchema,
   setDefaultDictionaryEntrySchema,
+  DICTIONARY_ENTRIES_MAX_LIMIT,
 } from '@open-mercato/core/modules/dictionaries/data/validators'
 import { dictionaryEntrySortModeSchema } from '@open-mercato/core/modules/dictionaries/lib/entrySort'
 
@@ -57,6 +58,24 @@ export const dictionaryEntrySchema = z.object({
 
 export const dictionaryEntryListResponseSchema = z.object({
   items: z.array(dictionaryEntrySchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int(),
+  hasMore: z.boolean(),
+  sortMode: dictionaryEntrySortModeSchema.describe(
+    'Sort mode that ordered this page. Clients assembling multiple pages must re-apply it across the combined set.',
+  ),
+})
+
+export const dictionaryEntriesQuerySchema = z.object({
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(DICTIONARY_ENTRIES_MAX_LIMIT)
+    .optional()
+    .describe(`Maximum entries to return. Defaults to and is capped at ${DICTIONARY_ENTRIES_MAX_LIMIT}.`),
+  offset: z.coerce.number().int().min(0).optional().describe('Number of entries to skip. Defaults to 0.'),
 })
 
 export const dictionaryEntryResponseSchema = dictionaryEntrySchema

package/src/modules/dictionaries/components/hooks/useDictionaryEntries.ts

@@ -1,6 +1,5 @@
 "use client"
 
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import { useQuery, type QueryClient, type UseQueryResult } from '@tanstack/react-query'
 import {
   createDictionaryMap,
@@ -8,6 +7,7 @@ import {
   type DictionaryDisplayEntry,
   type DictionaryMap,
 } from '../dictionaryAppearance'
+import { fetchAllDictionaryEntries } from '../../lib/fetchAllEntries'
 
 export type DictionaryEntryRecord = DictionaryDisplayEntry & {
   id: string
@@ -28,47 +28,46 @@ const BASE_DICTIONARY_ENTRIES_KEY = ['dictionaries', 'entries'] as const
 export const dictionaryEntriesQueryKey = (dictionaryId: string, scopeVersion = 0) =>
   [...BASE_DICTIONARY_ENTRIES_KEY, dictionaryId, `scope:${scopeVersion}`] as const
 
+function parseDictionaryEntryItems(items: unknown[]): DictionaryEntryRecord[] {
+  const parsed: DictionaryEntryRecord[] = []
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue
+    const data = item as Record<string, unknown>
+    const id = typeof data.id === 'string' ? data.id : ''
+    const value = typeof data.value === 'string' ? data.value.trim() : ''
+    if (!id || !value) continue
+    const label =
+      typeof data.label === 'string' && data.label.trim().length ? data.label.trim() : value
+    const color =
+      typeof data.color === 'string' && /^#([0-9a-fA-F]{6})$/.test(data.color)
+        ? `#${data.color.slice(1).toLowerCase()}`
+        : null
+    const icon = typeof data.icon === 'string' && data.icon.trim().length ? data.icon.trim() : null
+    const createdAt = typeof data.createdAt === 'string' ? data.createdAt : null
+    const updatedAt = typeof data.updatedAt === 'string' ? data.updatedAt : null
+    parsed.push({
+      id,
+      value,
+      label,
+      color,
+      icon,
+      createdAt,
+      updatedAt,
+    })
+  }
+  return parsed
+}
+
 export const dictionaryEntriesQueryOptions = (dictionaryId: string, scopeVersion = 0) => ({
   queryKey: dictionaryEntriesQueryKey(dictionaryId, scopeVersion),
   staleTime: DICTIONARY_ENTRIES_STALE_TIME,
   gcTime: DICTIONARY_ENTRIES_STALE_TIME,
   queryFn: async (): Promise<DictionaryEntriesQueryData> => {
-    const call = await apiCall<Record<string, unknown>>(`/api/dictionaries/${dictionaryId}/entries`)
-    const payload = call.result ?? {}
-    if (!call.ok) {
-      const message =
-        typeof payload.error === 'string'
-          ? payload.error
-          : 'Failed to load dictionary entries.'
-      throw new Error(message)
-    }
-    const items = Array.isArray(payload.items) ? payload.items : []
-    const parsed: DictionaryEntryRecord[] = []
-    for (const item of items) {
-      if (!item || typeof item !== 'object') continue
-      const data = item as Record<string, unknown>
-      const id = typeof data.id === 'string' ? data.id : ''
-      const value = typeof data.value === 'string' ? data.value.trim() : ''
-      if (!id || !value) continue
-      const label =
-        typeof data.label === 'string' && data.label.trim().length ? data.label.trim() : value
-      const color =
-        typeof data.color === 'string' && /^#([0-9a-fA-F]{6})$/.test(data.color)
-          ? `#${data.color.slice(1).toLowerCase()}`
-          : null
-      const icon = typeof data.icon === 'string' && data.icon.trim().length ? data.icon.trim() : null
-      const createdAt = typeof data.createdAt === 'string' ? data.createdAt : null
-      const updatedAt = typeof data.updatedAt === 'string' ? data.updatedAt : null
-      parsed.push({
-        id,
-        value,
-        label,
-        color,
-        icon,
-        createdAt,
-        updatedAt,
-      })
+    const pages = await fetchAllDictionaryEntries(dictionaryId)
+    if (!pages.ok) {
+      throw new Error(pages.errorMessage ?? 'Failed to load dictionary entries.')
     }
+    const parsed = parseDictionaryEntryItems(pages.items)
     const normalized = normalizeDictionaryEntries(
       parsed.map(({ value, label, color, icon }) => ({ value, label, color, icon })),
       { sort: false },

package/src/modules/dictionaries/data/validators.ts

@@ -26,6 +26,20 @@ export const upsertDictionarySchema = z.object({
 
 export type UpsertDictionaryInput = z.infer<typeof upsertDictionarySchema>
 
+export const DICTIONARY_ENTRIES_MAX_LIMIT = 500
+
+export const listDictionaryEntriesQuerySchema = z.object({
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(DICTIONARY_ENTRIES_MAX_LIMIT)
+    .catch(DICTIONARY_ENTRIES_MAX_LIMIT),
+  offset: z.coerce.number().int().min(0).catch(0),
+})
+
+export type ListDictionaryEntriesQuery = z.infer<typeof listDictionaryEntriesQuerySchema>
+
 export const createDictionaryEntrySchema = z.object({
   value: z.string().trim().min(1).max(150),
   label: z.string().trim().min(1).max(150).optional(),

package/src/modules/dictionaries/lib/clientEntries.ts

@@ -1,6 +1,7 @@
 "use client"
 
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { fetchAllDictionaryEntries } from './fetchAllEntries'
 
 type DictionarySummary = {
   id: string
@@ -59,8 +60,8 @@ export async function loadDictionaryEntriesByKey(key: string): Promise<Dictionar
   const dictionary = normalizeDictionaryList(dictionariesCall.result?.items).find((item) => item.key === key)
   if (!dictionary) return []
 
-  const entriesCall = await apiCall<{ items?: unknown[] }>(`/api/dictionaries/${dictionary.id}/entries`)
-  if (!entriesCall.ok) return []
+  const entries = await fetchAllDictionaryEntries(dictionary.id)
+  if (!entries.ok) return []
 
-  return normalizeDictionaryEntries(entriesCall.result?.items)
+  return normalizeDictionaryEntries(entries.items)
 }

package/src/modules/dictionaries/lib/fetchAllEntries.ts

@@ -0,0 +1,72 @@
+"use client"
+
+import { fetchAllOffsetPages } from '@open-mercato/ui/backend/utils/fetchAllPages'
+import {
+  resolveDictionaryEntrySortMode,
+  sortDictionaryEntries,
+  type DictionaryEntrySortItem,
+} from './entrySort'
+
+export type DictionaryEntryItem = Record<string, unknown>
+
+export type DictionaryEntriesResult = {
+  ok: boolean
+  items: DictionaryEntryItem[]
+  pageCount: number
+  errorMessage: string | null
+}
+
+type DictionaryEntrySortView = DictionaryEntrySortItem & { entry: DictionaryEntryItem }
+
+function toRecords(items: unknown[]): DictionaryEntryItem[] {
+  return items.filter((item): item is DictionaryEntryItem => !!item && typeof item === 'object')
+}
+
+function toSortView(entry: DictionaryEntryItem): DictionaryEntrySortView {
+  const value = typeof entry.value === 'string' ? entry.value.trim() : ''
+  const label = typeof entry.label === 'string' ? entry.label.trim() : ''
+  return {
+    entry,
+    id: typeof entry.id === 'string' ? entry.id : null,
+    value: value.length ? value : null,
+    label: label.length ? label : null,
+    createdAt: typeof entry.createdAt === 'string' ? entry.createdAt : null,
+  }
+}
+
+/**
+ * Load every entry of a dictionary, walking the entries route's page cap.
+ *
+ * The route bounds each response, so any consumer that needs the full option
+ * list must page — reading `items` from a single request silently drops
+ * everything past the ceiling and makes those values unselectable.
+ */
+export async function fetchAllDictionaryEntries(
+  dictionaryId: string,
+): Promise<DictionaryEntriesResult> {
+  const pages = await fetchAllOffsetPages(`/api/dictionaries/${dictionaryId}/entries`)
+  const records = toRecords(pages.items)
+
+  if (!pages.ok) {
+    const error = pages.errorPayload?.error
+    return {
+      ok: false,
+      items: records,
+      pageCount: pages.pageCount,
+      errorMessage: typeof error === 'string' ? error : null,
+    }
+  }
+
+  // The route bounds each response and orders it in memory, so entries
+  // assembled from several pages are only sorted within each page. Re-apply the
+  // mode that produced them across the whole set. A single-page dictionary —
+  // every dictionary at or below the route ceiling — keeps the server ordering
+  // byte-for-byte.
+  if (pages.pageCount <= 1) {
+    return { ok: true, items: records, pageCount: pages.pageCount, errorMessage: null }
+  }
+
+  const sortMode = resolveDictionaryEntrySortMode(pages.firstPayload.sortMode)
+  const sorted = sortDictionaryEntries(records.map(toSortView), sortMode).map((view) => view.entry)
+  return { ok: true, items: sorted, pageCount: pages.pageCount, errorMessage: null }
+}

package/src/modules/entities/api/definitions.ts

@@ -14,6 +14,7 @@ import {
 } from './definitions.cache'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { filterSelectableSystemEntityIds, isSystemEntitySelectable } from '@open-mercato/shared/lib/entities/system-entities'
+import { isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { loadEntityFieldsetConfigs, CustomFieldsetDefinition } from '../lib/fieldsets'
 import { installCustomEntitiesFromModules } from '../lib/install-from-ce'
@@ -24,6 +25,12 @@ import {
   beginEntitiesMutationGuard,
   FIELD_DEFINITION_RESOURCE_KIND,
 } from './definitions.mutation-guard'
+import {
+  canReadAllEntityMetadata,
+  canReadEntityMetadata,
+  getDeclaredCustomEntityRestriction,
+  resolveEntityAclRequirement,
+} from '../lib/entityAcl'
 import {
   createExactDefinitionWhere,
   createScopedDefinitionTombstone,
@@ -226,8 +233,8 @@ export async function GET(req: Request) {
   const auth = await getAuthFromRequest(req)
   if (!auth) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
 
-  const entityIds = filterSelectableSystemEntityIds(requestedEntityIds)
-  if (!entityIds.length) {
+  const selectableEntityIds = filterSelectableSystemEntityIds(requestedEntityIds)
+  if (!selectableEntityIds.length) {
     return NextResponse.json({ items: [] })
   }
 
@@ -241,6 +248,48 @@ export async function GET(req: Request) {
   const organizationId = definitionScope.organizationId
   const { resolve } = container
   const em = resolve('em') as any
+  const rbac = resolve('rbacService') as RbacService
+  const acl = await rbac.loadAcl(auth.sub ?? '', {
+    tenantId,
+    organizationId,
+  })
+  const designerCanRead = canReadAllEntityMetadata(acl)
+  const customEntityRestrictions = new Map<string, boolean>()
+  for (const entityId of selectableEntityIds) {
+    if (isOrmBackedSystemEntityId(em, entityId)) continue
+    const declaredRestriction = getDeclaredCustomEntityRestriction(entityId)
+    if (declaredRestriction !== undefined) customEntityRestrictions.set(entityId, declaredRestriction)
+  }
+  if (!designerCanRead) {
+    const unresolvedEntityIds = selectableEntityIds.filter(
+      (entityId) => !resolveEntityAclRequirement(entityId) && !customEntityRestrictions.has(entityId),
+    )
+    if (unresolvedEntityIds.length) {
+      const registrations = await em.find(CustomEntity as any, {
+        entityId: { $in: unresolvedEntityIds },
+        isActive: true,
+        $and: [
+          { $or: [{ tenantId }, { tenantId: null }] },
+          { $or: [{ organizationId }, { organizationId: null }] },
+        ],
+      } as any)
+      for (const registration of registrations as any[]) {
+        const entityId = String(registration.entityId)
+        if (!isOrmBackedSystemEntityId(em, entityId)) {
+          customEntityRestrictions.set(entityId, registration.accessRestricted === true)
+        }
+      }
+    }
+  }
+  const entityIds = selectableEntityIds.filter((entityId) => canReadEntityMetadata({
+    entityId,
+    isCustomEntity: customEntityRestrictions.has(entityId),
+    isRestricted: customEntityRestrictions.get(entityId) === true,
+    acl,
+  }))
+  if (!entityIds.length) {
+    return NextResponse.json({ items: [], fieldsetsByEntity: {}, entitySettings: {} })
+  }
   let cache: CacheStrategy | undefined
   try {
     cache = resolve('cache') as CacheStrategy
@@ -249,7 +298,6 @@ export async function GET(req: Request) {
   let canManageDefinitions = false
   if (typeof auth.sub === 'string' && auth.sub.length > 0) {
     try {
-      const rbac = resolve('rbacService') as RbacService
       canManageDefinitions = await rbac.userHasAllFeatures(auth.sub, ['entities.definitions.manage'], {
         tenantId,
         organizationId,