@open-mercato/core 0.6.6-develop.6257.1.6d0af84d26 → 0.6.6-develop.6286.1.d985c5c374

package/src/modules/progress/lib/progressService.ts

@@ -16,11 +16,11 @@ export interface ProgressService {
   failJob(jobId: string, input: FailJobInput, ctx: ProgressServiceContext): Promise<ProgressJob>
   cancelJob(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob>
   markCancelled(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob>
-  isCancellationRequested(jobId: string, tenantId: string): Promise<boolean>
+  isCancellationRequested(jobId: string, tenantId: string, organizationId?: string | null): Promise<boolean>
   getActiveJobs(ctx: ProgressServiceContext): Promise<ProgressJob[]>
   getRecentlyCompletedJobs(ctx: ProgressServiceContext, sinceSeconds?: number): Promise<ProgressJob[]>
   getJob(jobId: string, ctx: ProgressServiceContext): Promise<ProgressJob | null>
-  markStaleJobsFailed(tenantId: string, timeoutSeconds?: number): Promise<number>
+  markStaleJobsFailed(tenantId: string, timeoutSeconds?: number, organizationId?: string | null): Promise<number>
 }
 
 export const HEARTBEAT_INTERVAL_MS = 5000

package/src/modules/progress/lib/progressServiceImpl.ts

@@ -54,7 +54,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async startJob(jobId, ctx) {
-      const job = await em.findOneOrFail(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOneOrFail(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (job.status === 'cancelled') {
         return job
       }
@@ -120,7 +124,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async incrementProgress(jobId, delta, ctx) {
-      const job = await em.findOneOrFail(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOneOrFail(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') {
         return job
       }
@@ -147,7 +155,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async completeJob(jobId, input, ctx) {
-      const job = await em.findOne(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOne(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (!job) throw new Error(`Job ${jobId} not found`)
       if (job.status === 'cancelled') {
         return job
@@ -174,7 +186,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async failJob(jobId, input, ctx) {
-      const job = await em.findOne(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOne(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (!job) throw new Error(`Job ${jobId} not found`)
       if (job.status === 'cancelled') {
         return job
@@ -226,7 +242,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async markCancelled(jobId, ctx) {
-      const job = await em.findOne(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOne(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (!job) throw new Error(`Job ${jobId} not found`)
       if (job.status === 'cancelled') {
         return job
@@ -249,8 +269,12 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
       return job
     },
 
-    async isCancellationRequested(jobId, tenantId) {
-      const job = await findOneWithDecryption(em, ProgressJob, { id: jobId, tenantId })
+    async isCancellationRequested(jobId, tenantId, organizationId) {
+      const job = await findOneWithDecryption(em, ProgressJob, {
+        id: jobId,
+        tenantId,
+        ...(organizationId ? { organizationId } : {}),
+      })
       return job?.cancelRequestedAt != null
     },
 
@@ -288,11 +312,12 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
       })
     },
 
-    async markStaleJobsFailed(tenantId: string, timeoutSeconds = STALE_JOB_TIMEOUT_SECONDS) {
+    async markStaleJobsFailed(tenantId: string, timeoutSeconds = STALE_JOB_TIMEOUT_SECONDS, organizationId?: string | null) {
       const cutoff = new Date(Date.now() - timeoutSeconds * 1000)
 
       const staleJobs = await em.find(ProgressJob, {
         tenantId,
+        ...(organizationId ? { organizationId } : {}),
         status: 'running',
         $or: [
           { heartbeatAt: { $lt: cutoff } },

package/src/modules/query_index/api/status.ts

@@ -4,7 +4,8 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { getEntityIds } from '@open-mercato/shared/lib/encryption/entityIds'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { sql } from 'kysely'
-import { readCoverageSnapshot, refreshCoverageSnapshot } from '../lib/coverage'
+import { readCoverageSnapshots, refreshCoverageSnapshot } from '../lib/coverage'
+import { mapWithConcurrency } from '@open-mercato/shared/lib/query/bounded-decrypt'
 import type { FullTextSearchStrategy } from '@open-mercato/search/strategies'
 import type { SearchModuleConfig } from '@open-mercato/shared/modules/search'
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
@@ -146,6 +147,7 @@ export async function GET(req: Request) {
 
   const HEARTBEAT_STALE_MS = 60_000
   const COVERAGE_STALE_MS = 60_000
+  const COVERAGE_REFRESH_CONCURRENCY = 8
 
   async function fetchJobSummary(entityType: string, tenantIdParam: string | null, organizationIdParam: string | null) {
     try {
@@ -288,40 +290,31 @@ export async function GET(req: Request) {
     return Number.isFinite(parsed) ? parsed : null
   }
 
-  const coverageSnapshots: Array<Awaited<ReturnType<typeof readCoverageSnapshot>>> = []
+  const coverageScope = {
+    tenantId: tenantId ?? null,
+    organizationId,
+    withDeleted: false,
+  } as const
   const entitiesNeedingRefresh = new Set<string>()
-  for (const entityId of entityIds) {
-    const scope = {
-      entityType: entityId,
-      tenantId: tenantId ?? null,
-      organizationId,
-      withDeleted: false,
-    } as const
-    const ensureSnapshot = async () => {
-      let snapshot = await readCoverageSnapshot(db, scope)
-      const refreshedAt = snapshot?.refreshed_at instanceof Date
-        ? snapshot.refreshed_at
-        : snapshot?.refreshed_at
-          ? new Date(snapshot.refreshed_at)
-          : null
-      const stale = !snapshot || !refreshedAt || (Date.now() - refreshedAt.getTime() > COVERAGE_STALE_MS)
-      if (forceRefresh || stale) {
-        await refreshCoverageSnapshot(em, scope).catch(() => undefined)
-        snapshot = await readCoverageSnapshot(db, scope)
-      }
-      const finalRefreshed = snapshot?.refreshed_at instanceof Date
-        ? snapshot.refreshed_at
-        : snapshot?.refreshed_at
-          ? new Date(snapshot.refreshed_at)
-          : null
-      if (!snapshot || !finalRefreshed || (Date.now() - finalRefreshed.getTime() > COVERAGE_STALE_MS)) {
-        entitiesNeedingRefresh.add(entityId)
-      }
-      return snapshot
-    }
-    coverageSnapshots.push(await ensureSnapshot())
+
+  // Read every entity's coverage snapshot in a single batched query. This endpoint is
+  // polled by the status table every few seconds, so the poll path must stay read-cheap:
+  // stale snapshots are refreshed asynchronously via the query_index.coverage.refresh
+  // event emitted below, never inline per entity.
+  const snapshotByEntity = await readCoverageSnapshots(db, { entityTypes: entityIds, ...coverageScope })
+
+  // An explicit refresh action (?refresh) is allowed to block: recompute every entity's
+  // coverage with bounded concurrency, then re-read the freshly written snapshots.
+  if (forceRefresh && entityIds.length > 0) {
+    await mapWithConcurrency(entityIds, COVERAGE_REFRESH_CONCURRENCY, (entityId) =>
+      refreshCoverageSnapshot(em, { entityType: entityId, ...coverageScope }).catch(() => undefined),
+    )
+    const refreshed = await readCoverageSnapshots(db, { entityTypes: entityIds, ...coverageScope })
+    for (const [entityId, snapshot] of refreshed) snapshotByEntity.set(entityId, snapshot)
   }
 
+  const coverageSnapshots = entityIds.map((entityId) => snapshotByEntity.get(entityId) ?? null)
+
   const jobs = await Promise.all(entityIds.map((eid) => fetchJobSummary(eid, tenantId, organizationId)))
 
   const items: any[] = []
@@ -467,6 +460,9 @@ export async function GET(req: Request) {
 
   const response = NextResponse.json({ items, errors, logs })
   const partial = items.find((item) => {
+    // Coverage not computed yet (no snapshot) — pending an async refresh, not a partial
+    // index. Do not raise the partial-index warning while counts are still unknown.
+    if (item.baseCount == null && item.indexCount == null) return false
     if (item.baseCount == null || item.indexCount == null) return true
     return item.baseCount !== item.indexCount
   })

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

@@ -16,6 +16,19 @@ type CoverageRow = {
   refreshed_at: Date | string | null
 }
 
+export type CoverageSnapshot = CoverageRow & {
+  baseCount: number
+  indexedCount: number
+  vectorIndexedCount: number
+}
+
+export type CoverageBatchScope = {
+  entityTypes: readonly string[]
+  tenantId?: string | null
+  organizationId?: string | null
+  withDeleted?: boolean
+}
+
 export type CoverageAdjustment = {
   entityType: string
   tenantId: string | null
@@ -186,6 +199,56 @@ export async function readCoverageSnapshot(
   }
 }
 
+export async function readCoverageSnapshots(
+  db: Kysely<any>,
+  batch: CoverageBatchScope
+): Promise<Map<string, CoverageSnapshot>> {
+  const entityTypes = Array.from(
+    new Set((batch.entityTypes ?? []).map((id) => String(id || '')).filter((id) => id.length > 0))
+  )
+  const result = new Map<string, CoverageSnapshot>()
+  if (entityTypes.length === 0) return result
+
+  const withDeleted = batch.withDeleted === true
+  let query = db
+    .selectFrom('entity_index_coverage' as any)
+    .select([
+      'entity_type' as any,
+      'base_count' as any,
+      'indexed_count' as any,
+      'vector_indexed_count' as any,
+      'refreshed_at' as any,
+      'organization_id' as any,
+    ])
+    .where('entity_type' as any, 'in', entityTypes)
+    .where('with_deleted' as any, '=', withDeleted)
+    .orderBy('refreshed_at' as any, 'desc')
+  query = batch.tenantId == null
+    ? query.where('tenant_id' as any, 'is', null as any)
+    : query.where('tenant_id' as any, '=', batch.tenantId)
+  query = applyOrganizationCondition(query as any, 'organization_id', batch.organizationId ?? null)
+
+  const rows = await query.execute() as Array<CoverageRow & { entity_type: string }>
+  for (const row of rows ?? []) {
+    const entityType = String(row.entity_type || '')
+    // Rows are ordered by refreshed_at desc, so the first row seen per entity is the latest.
+    if (!entityType || result.has(entityType)) continue
+    const refreshedAt = row.refreshed_at instanceof Date
+      ? row.refreshed_at
+      : (row.refreshed_at ? new Date(row.refreshed_at) : null)
+    result.set(entityType, {
+      base_count: row.base_count,
+      indexed_count: row.indexed_count,
+      vector_indexed_count: row.vector_indexed_count,
+      refreshed_at: refreshedAt ?? null,
+      baseCount: toCount(row.base_count),
+      indexedCount: toCount(row.indexed_count),
+      vectorIndexedCount: toCount(row.vector_indexed_count),
+    })
+  }
+  return result
+}
+
 export async function applyCoverageAdjustments(
   em: EntityManager,
   adjustments: CoverageAdjustment[]

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

@@ -3,6 +3,7 @@ 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'
 import { BasicQueryEngine, resolveEntityTableName, resolveRegisteredEntityTableName } from '@open-mercato/shared/lib/query/engine'
+import { isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 import { type Kysely, sql, type RawBuilder } from 'kysely'
 import type { EventBus } from '@open-mercato/events'
 import { readCoverageSnapshot, refreshCoverageSnapshot } from './coverage'
@@ -1064,32 +1065,44 @@ export class HybridQueryEngine implements QueryEngine {
     if (cached !== undefined) return cached
     let result = false
     try {
-      const db = this.getDb() as any
-      const row = await db
-        .selectFrom('custom_entities')
-        .select('id')
-        .where('entity_id', '=', entity)
-        .where('is_active', '=', true)
-        .executeTakeFirst()
-      if (row) {
-        result = true
-      } else if (resolveRegisteredEntityTableName(this.em, entity) !== null) {
-        // An id backed by a registered ORM table is never doc-storage-backed by
-        // inference: stray `custom_entities_storage` rows for such an id (e.g. written
-        // through the generic entities data engine) must not hijack every list/detail
-        // read for the whole entity type away from its base table (#2939). Surfaces
-        // that intentionally read doc records for a dual-declared id pass
-        // `forceCustomEntityStorage` in QueryOptions instead.
+      if (isOrmBackedSystemEntityId(this.em, entity)) {
+        // An id backed by a registered ORM table is never doc-storage-backed. Classify it
+        // as its base table BEFORE probing `custom_entities`, so neither a stray
+        // `custom_entities_storage` row nor an active `custom_entities` row (e.g. a
+        // presentation-metadata overlay for a system entity) can hijack every list/detail
+        // read for the whole entity type away from its base table (#2939). This mirrors the
+        // ORM-backed-first ordering already used by the records API (`classifyRecordsEntity`)
+        // and the doc-storage write guard (`assertCustomEntityStorageEntityId`); without it
+        // the read classifier alone trusted an active registration row over ORM-table
+        // resolution. Surfaces that intentionally read doc records for a dual-declared id
+        // pass `forceCustomEntityStorage` in QueryOptions instead.
         result = false
       } else {
-        // Read/write symmetry. Records written through the entities data engine
-        // (`de.createCustomEntityRecord`) always land in `custom_entities_storage`,
-        // even for module-declared custom entities whose id is also a frozen system
-        // id — those are NEVER registered in `custom_entities` (install treats a
-        // system id as non-registrable). Without this fallback the query routes to
-        // the empty ORM/index path and those records are write-only (created with
-        // 200 but unreadable on the edit form).
-        result = await this.hasCustomEntityStorageRows(entity)
+        const db = this.getDb() as any
+        const row = await db
+          .selectFrom('custom_entities')
+          .select('id')
+          .where('entity_id', '=', entity)
+          .where('is_active', '=', true)
+          .executeTakeFirst()
+        if (row) {
+          result = true
+        } else if (resolveRegisteredEntityTableName(this.em, entity) !== null) {
+          // A non-registry id whose entity segment collides with an ORM class name (e.g.
+          // `user:todo` vs the example module's `Todo`) resolves to a table but is NOT an
+          // ORM-backed system entity, so it is not short-circuited above. Stray
+          // `custom_entities_storage` rows for such an id must not hijack reads either.
+          result = false
+        } else {
+          // Read/write symmetry. Records written through the entities data engine
+          // (`de.createCustomEntityRecord`) always land in `custom_entities_storage`,
+          // even for module-declared custom entities whose id is also a frozen system
+          // id — those are NEVER registered in `custom_entities` (install treats a
+          // system id as non-registrable). Without this fallback the query routes to
+          // the empty ORM/index path and those records are write-only (created with
+          // 200 but unreadable on the edit form).
+          result = await this.hasCustomEntityStorageRows(entity)
+        }
       }
     } catch {
       result = false

package/src/modules/resources/api/resource-types.ts

@@ -3,11 +3,10 @@ import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
-import type { EntityManager } from '@mikro-orm/postgresql'
-import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-import { ResourcesResource, ResourcesResourceType } from '../data/entities'
+import { ResourcesResourceType } from '../data/entities'
 import { resourcesResourceTypeCreateSchema, resourcesResourceTypeUpdateSchema } from '../data/validators'
 import { sanitizeSearchTerm } from './helpers'
+import { attachResourceTypeCounts } from './resourceTypeCounts'
 import { E } from '#generated/entities.ids.generated'
 import { createResourcesCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from './openapi'
 
@@ -47,6 +46,7 @@ const listSchema = z
     ids: z.string().optional(),
     sortField: z.string().optional(),
     sortDir: z.enum(['asc', 'desc']).optional(),
+    withResourceCounts: z.string().optional(),
   })
   .passthrough()
 
@@ -131,47 +131,7 @@ const crud = makeCrudRoute({
     },
   },
   hooks: {
-    afterList: async (payload, ctx) => {
-      const items: Array<Record<string, unknown>> = Array.isArray(payload?.items)
-        ? (payload.items as Array<Record<string, unknown>>)
-        : []
-      if (!items.length) return
-      const typeIds = items
-        .map((item) => (typeof item.id === 'string' ? item.id : null))
-        .filter((id): id is string => typeof id === 'string' && id.length > 0)
-      if (!typeIds.length) return
-      const em = (ctx.container.resolve('em') as EntityManager).fork()
-      const tenantId = ctx.organizationScope?.tenantId ?? ctx.auth?.tenantId ?? null
-      const orgIds = ctx.organizationIds ?? ctx.organizationScope?.filterIds ?? null
-      const orgFilter =
-        Array.isArray(orgIds) && orgIds.length > 0
-          ? { $in: orgIds }
-          : ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null
-      const scope = { tenantId, organizationId: ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null }
-      const resources = await findWithDecryption(
-        em,
-        ResourcesResource,
-        {
-          resourceTypeId: { $in: typeIds },
-          deletedAt: null,
-          ...(tenantId ? { tenantId } : {}),
-          ...(orgFilter ? { organizationId: orgFilter } : {}),
-        },
-        { fields: ['id', 'resourceTypeId'] },
-        scope,
-      )
-      const countMap = new Map<string, number>()
-      resources.forEach((resource) => {
-        const typeId = resource.resourceTypeId ?? null
-        if (!typeId) return
-        countMap.set(typeId, (countMap.get(typeId) ?? 0) + 1)
-      })
-      items.forEach((item) => {
-        const id = typeof item.id === 'string' ? item.id : null
-        if (!id) return
-        item.resourceCount = countMap.get(id) ?? 0
-      })
-    },
+    afterList: (payload, ctx) => attachResourceTypeCounts(payload, ctx),
   },
 })
 

package/src/modules/resources/api/resourceTypeCounts.ts

@@ -0,0 +1,74 @@
+import type { Kysely } from 'kysely'
+import { sql } from 'kysely'
+import { parseBooleanFromUnknown } from '@open-mercato/shared/lib/boolean'
+import type { CrudCtx } from '@open-mercato/shared/lib/crud/factory'
+
+type ResourceCountDatabase = {
+  resources_resources: {
+    resource_type_id: string | null
+    deleted_at: Date | null
+    tenant_id: string | null
+    organization_id: string | null
+  }
+}
+
+type KyselyCapableEntityManager = { getKysely: () => Kysely<ResourceCountDatabase> }
+
+type ResourceTypeCountContext = Pick<
+  CrudCtx,
+  'container' | 'auth' | 'organizationScope' | 'organizationIds' | 'selectedOrganizationId'
+> & { query?: { withResourceCounts?: unknown } }
+
+type ResourceTypeListPayload = { items?: unknown } | null | undefined
+
+type ResourceCountRow = { resource_type_id: string | null; count: string | number }
+
+export async function attachResourceTypeCounts(
+  payload: ResourceTypeListPayload,
+  ctx: ResourceTypeCountContext,
+): Promise<void> {
+  // Resource counts are opt-in: only callers that render the count (the
+  // resource-types admin table and its delete gate) pass `withResourceCounts`.
+  // Select/filter callers (resource dropdowns, group labels) skip the scan
+  // entirely so ordinary type lookups no longer pay an O(resources) cost.
+  if (!parseBooleanFromUnknown(ctx.query?.withResourceCounts)) return
+
+  const items = Array.isArray(payload?.items)
+    ? (payload!.items as Array<Record<string, unknown>>)
+    : []
+  if (!items.length) return
+
+  const typeIds = items
+    .map((item) => (typeof item.id === 'string' ? item.id : null))
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+  if (!typeIds.length) return
+
+  const tenantId = ctx.organizationScope?.tenantId ?? ctx.auth?.tenantId ?? null
+  const orgIds = ctx.organizationIds ?? ctx.organizationScope?.filterIds ?? null
+  const singleOrgId = ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId ?? null
+
+  const db = (ctx.container.resolve('em') as unknown as KyselyCapableEntityManager).getKysely()
+  let query = db
+    .selectFrom('resources_resources')
+    .select(['resource_type_id', sql<string>`count(*)`.as('count')])
+    .where('resource_type_id', 'in', typeIds)
+    .where('deleted_at', 'is', null)
+  if (tenantId) query = query.where('tenant_id', '=', tenantId)
+  if (Array.isArray(orgIds) && orgIds.length > 0) {
+    query = query.where('organization_id', 'in', orgIds)
+  } else if (singleOrgId) {
+    query = query.where('organization_id', '=', singleOrgId)
+  }
+  const rows = (await query.groupBy('resource_type_id').execute()) as ResourceCountRow[]
+
+  const countMap = new Map<string, number>()
+  for (const row of rows) {
+    if (typeof row.resource_type_id !== 'string') continue
+    const count = typeof row.count === 'string' ? Number.parseInt(row.count, 10) : Number(row.count)
+    countMap.set(row.resource_type_id, Number.isFinite(count) ? count : 0)
+  }
+  for (const item of items) {
+    if (typeof item.id !== 'string') continue
+    item.resourceCount = countMap.get(item.id) ?? 0
+  }
+}

package/src/modules/resources/backend/resources/resource-types/[id]/edit/page.tsx

@@ -34,7 +34,7 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
       setIsNotFound(false)
       try {
         const payload = await readApiResultOrThrow<ResourceTypesResponse>(
-          `/api/resources/resource-types?ids=${encodeURIComponent(resourceTypeId)}&page=1&pageSize=1`,
+          `/api/resources/resource-types?ids=${encodeURIComponent(resourceTypeId)}&page=1&pageSize=1&withResourceCounts=true`,
           undefined,
           { errorMessage: t('resources.resourceTypes.errors.load', 'Failed to load resource types.') },
         )

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

@@ -208,6 +208,7 @@ export default function ResourcesResourceTypesPage() {
       const params = new URLSearchParams({
         page: String(page),
         pageSize: String(PAGE_SIZE),
+        withResourceCounts: 'true',
       })
       const sort = sorting[0]
       if (sort?.id) {

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

@@ -11,6 +11,7 @@ import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { normalizeCrudServerError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { computeAvailableReturnQuantity } from '@open-mercato/core/modules/sales/lib/returnQuantity'
 import { handleSectionMutationError } from './optimisticLock'
@@ -136,7 +137,9 @@ export function ReturnDialog({ open, orderId, lines, documentUpdatedAt, onClose,
         onClose()
         return
       }
-      flash(t('sales.returns.errors.create', 'Failed to create return.'), 'error')
+      const normalized = normalizeCrudServerError(err)
+      const fallback = t('sales.returns.errors.create', 'Failed to create return.')
+      flash(normalized.message || fallback, 'error')
     } finally {
       setSaving(false)
     }

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

@@ -255,6 +255,20 @@ const extractShipmentAddressSnapshot = (
   return normalizeAddressSnapshot(raw as Record<string, unknown>)
 }
 
+const addressOptionsSignature = (options: ShipmentAddressOption[]): string =>
+  options.map((option) => `${snapshotKey(option.snapshot) ?? ''}::${option.id}`).join('||')
+
+function useStableAddressOptions(options: ShipmentAddressOption[]): ShipmentAddressOption[] {
+  const signature = addressOptionsSignature(options)
+  const stableRef = React.useRef(options)
+  const signatureRef = React.useRef(signature)
+  if (signatureRef.current !== signature) {
+    signatureRef.current = signature
+    stableRef.current = options
+  }
+  return stableRef.current
+}
+
 export function ShipmentDialog({
   open,
   mode,
@@ -323,7 +337,7 @@ export function ShipmentDialog({
     [shipmentAddressSnapshot, t],
   )
 
-  const baseAddressOptions = React.useMemo(
+  const computedBaseAddressOptions = React.useMemo(
     () =>
       dedupeAddressOptions(
         [shippingAddressOption, shipmentAddressOption].filter(
@@ -332,6 +346,7 @@ export function ShipmentDialog({
       ),
     [shipmentAddressOption, shippingAddressOption],
   )
+  const baseAddressOptions = useStableAddressOptions(computedBaseAddressOptions)
 
   const preferredAddressId = React.useMemo(() => {
     const shipmentKey = snapshotKey(shipmentAddressSnapshot)
@@ -452,7 +467,10 @@ export function ShipmentDialog({
 
   const mergeAddressOptions = React.useCallback(
     (options: ShipmentAddressOption[]) =>
-      setAddressOptions((prev) => dedupeAddressOptions([...prev, ...options])),
+      setAddressOptions((prev) => {
+        const next = dedupeAddressOptions([...prev, ...options])
+        return next.length === prev.length ? prev : next
+      }),
     [],
   )
 

package/src/modules/sales/di.ts

@@ -7,6 +7,7 @@ import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/opt
 import { DefaultSalesCalculationService } from './services/salesCalculationService'
 import { DefaultTaxCalculationService } from './services/taxCalculationService'
 import { SalesDocumentNumberGenerator } from './services/salesDocumentNumberGenerator'
+import { DefaultSalesOrderService } from './services/salesOrderService'
 import {
   SalesOrder,
   SalesOrderLine,
@@ -85,6 +86,11 @@ export function register(container: AppContainer) {
     })
       .singleton()
       .proxy(),
+    salesOrderService: asFunction(({ em }: AppCradle) => {
+      return new DefaultSalesOrderService(em)
+    })
+      .singleton()
+      .proxy(),
     SalesOrder: asValue(SalesOrder),
     SalesOrderLine: asValue(SalesOrderLine),
     SalesOrderAdjustment: asValue(SalesOrderAdjustment),

package/src/modules/sales/services/salesOrderService.ts

@@ -0,0 +1,38 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { SalesOrder } from '../data/entities'
+
+export type SalesOrderLookupScope = {
+  organizationId: string
+  tenantId: string
+}
+
+export interface SalesOrderService {
+  findByExternalReference(
+    externalReference: string,
+    scope: SalesOrderLookupScope,
+  ): Promise<SalesOrder | null>
+}
+
+export class DefaultSalesOrderService implements SalesOrderService {
+  constructor(private readonly em: EntityManager) {}
+
+  async findByExternalReference(
+    externalReference: string,
+    scope: SalesOrderLookupScope,
+  ): Promise<SalesOrder | null> {
+    if (!externalReference) return null
+    return findOneWithDecryption(
+      this.em,
+      SalesOrder,
+      {
+        externalReference,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId: scope.tenantId, organizationId: scope.organizationId },
+    )
+  }
+}