@open-mercato/core 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/src/modules/directory/migrations/Migration20260607222259_directory.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260607222259_directory extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "organizations" add "logo_url" text null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "organizations" drop column "logo_url";`);
+  }
+
+}

package/src/modules/directory/subscribers/invalidateOrgScopeCache.ts

@@ -7,6 +7,8 @@
 // drop every cache entry tagged for that tenant; the TTL is the backstop
 // for races where the event fires after a request reads the cache.
 
+import { buildOrgScopeTenantCacheTag } from '@open-mercato/core/modules/directory/utils/organizationScope'
+
 type CacheService = {
   deleteByTags(tags: string[]): Promise<number>
 }
@@ -32,7 +34,7 @@ export default async function handle(
   }
   if (!cache) return
   try {
-    await cache.deleteByTags([`org-scope:tenant:${tenantId}`])
+    await cache.deleteByTags([buildOrgScopeTenantCacheTag(tenantId)])
   } catch {
     // best-effort; TTL is the backstop.
   }

package/src/modules/directory/utils/organizationScope.ts

@@ -21,9 +21,11 @@ export type OrganizationScope = {
 // OrganizationScope is a pure function of (userId, tenantId, selectedOrgId,
 // requestedTenant) between membership changes; caching it bypasses 1
 // SELECT on `organizations` per CRUD request. TTL is short (60s default)
-// to keep staleness bounded for membership/visibility changes. Tag-based
-// invalidation kicks the cache when user_organizations or organizations
-// mutate (wired via invalidateOrganizationScopeCacheFor).
+// to keep staleness bounded as a backstop. Tag-based invalidation also fires
+// eagerly: per-user entries are dropped by RbacService.invalidateUserCache
+// (every ACL/role grant change goes through it — see buildOrgScopeUserCacheTag)
+// and per-tenant entries by the directory.organization.* subscriber plus
+// RbacService.invalidateTenantCache (role-ACL changes).
 const ORG_SCOPE_CACHE_KEY_PREFIX = 'org-scope'
 // Phase 4 default-off until the same readiness probe (`GET /api/customers/people`)
 // stays green with the cache layer engaged. Set `OM_ORG_SCOPE_CACHE_TTL_MS=60000`
@@ -49,10 +51,23 @@ function buildOrgScopeCacheKey(parts: {
   return `${ORG_SCOPE_CACHE_KEY_PREFIX}:${parts.userId}:${parts.effectiveTenantId}:${selected}:${requested}`
 }
 
+// Tag builders are exported so the modules that own the "this user's scope
+// changed" / "this tenant's org tree changed" signals (auth RBAC invalidation,
+// the directory.organization.* subscriber) can drop the matching cross-request
+// cache entries without re-deriving the tag format. Keeping the format in one
+// place is what lets the TTL be enabled safely (issue #2259).
+export function buildOrgScopeUserCacheTag(userId: string): string {
+  return `${ORG_SCOPE_CACHE_KEY_PREFIX}:user:${userId}`
+}
+
+export function buildOrgScopeTenantCacheTag(tenantId: string): string {
+  return `${ORG_SCOPE_CACHE_KEY_PREFIX}:tenant:${tenantId}`
+}
+
 function buildOrgScopeCacheTags(parts: { userId: string; effectiveTenantId: string }): string[] {
   return [
-    `${ORG_SCOPE_CACHE_KEY_PREFIX}:user:${parts.userId}`,
-    `${ORG_SCOPE_CACHE_KEY_PREFIX}:tenant:${parts.effectiveTenantId}`,
+    buildOrgScopeUserCacheTag(parts.userId),
+    buildOrgScopeTenantCacheTag(parts.effectiveTenantId),
   ]
 }
 
@@ -82,7 +97,7 @@ export async function invalidateOrganizationScopeCacheForUser(
   const cache = resolveCacheFromContainer(container)
   if (!cache?.deleteByTags) return
   try {
-    await cache.deleteByTags([`${ORG_SCOPE_CACHE_KEY_PREFIX}:user:${userId}`])
+    await cache.deleteByTags([buildOrgScopeUserCacheTag(userId)])
   } catch (err) {
     console.warn('[org-scope:cache] invalidate user failed', err)
   }
@@ -95,12 +110,36 @@ export async function invalidateOrganizationScopeCacheForTenant(
   const cache = resolveCacheFromContainer(container)
   if (!cache?.deleteByTags) return
   try {
-    await cache.deleteByTags([`${ORG_SCOPE_CACHE_KEY_PREFIX}:tenant:${tenantId}`])
+    await cache.deleteByTags([buildOrgScopeTenantCacheTag(tenantId)])
   } catch (err) {
     console.warn('[org-scope:cache] invalidate tenant failed', err)
   }
 }
 
+// Issue #2259 — per-request memoization. resolveOrganizationScopeForRequest
+// runs at least twice per CRUD request: once for the route-level feature check
+// (resolveFeatureCheckContext) and once inside the shared factory's withCtx.
+// Those two call sites use different request-scoped DI containers but are handed
+// the SAME Request instance, so memoizing the resolved scope on a WeakMap keyed
+// by that request collapses the duplicate work — and the duplicate
+// `organizations` SELECT — into a single resolution. The inner map is keyed by
+// the same identity tuple as the cross-request cache key, so distinct explicit
+// selectedId/tenant overrides on one request stay independent. There is no
+// staleness risk: the memo lives only for the lifetime of one request and is
+// dropped with the request object by the GC.
+const orgScopeRequestMemo = new WeakMap<object, Map<string, Promise<OrganizationScope>>>()
+
+function getRequestScopeMemo(request: unknown): Map<string, Promise<OrganizationScope>> | null {
+  if (!request || (typeof request !== 'object' && typeof request !== 'function')) return null
+  const key = request as object
+  let memo = orgScopeRequestMemo.get(key)
+  if (!memo) {
+    memo = new Map<string, Promise<OrganizationScope>>()
+    orgScopeRequestMemo.set(key, memo)
+  }
+  return memo
+}
+
 function normalizeOrganizationId(value: unknown): string | null {
   if (typeof value !== 'string') return null
   const trimmed = value.trim()
@@ -402,35 +441,51 @@ export async function resolveOrganizationScopeForRequest({
       })
     : null
 
-  if (cache && cacheKey && typeof cache.get === 'function') {
-    try {
-      const cached = await cache.get(cacheKey)
-      if (isValidCachedScope(cached)) return cached
-    } catch (err) {
-      console.warn('[org-scope:cache] read failed', err)
-    }
+  const requestMemo = getRequestScopeMemo(request)
+  if (requestMemo && cacheKey) {
+    const memoized = requestMemo.get(cacheKey)
+    if (memoized) return memoized
   }
 
-  const baseScope = await resolveOrganizationScope({
-    em,
-    rbac,
-    auth: scopedAuth,
-    selectedId: rawSelected,
-    tenantId: effectiveTenantId,
-  })
+  const resolveScope = async (): Promise<OrganizationScope> => {
+    if (cache && cacheKey && typeof cache.get === 'function') {
+      try {
+        const cached = await cache.get(cacheKey)
+        if (isValidCachedScope(cached)) return cached
+      } catch (err) {
+        console.warn('[org-scope:cache] read failed', err)
+      }
+    }
 
-  if (cache && cacheKey && userId && typeof cache.set === 'function') {
-    try {
-      await cache.set(cacheKey, baseScope, {
-        ttl: ttlMs,
-        tags: buildOrgScopeCacheTags({ userId, effectiveTenantId }),
-      })
-    } catch (err) {
-      console.warn('[org-scope:cache] write failed', err)
+    const baseScope = await resolveOrganizationScope({
+      em,
+      rbac,
+      auth: scopedAuth,
+      selectedId: rawSelected,
+      tenantId: effectiveTenantId,
+    })
+
+    if (cache && cacheKey && userId && typeof cache.set === 'function') {
+      try {
+        await cache.set(cacheKey, baseScope, {
+          ttl: ttlMs,
+          tags: buildOrgScopeCacheTags({ userId, effectiveTenantId }),
+        })
+      } catch (err) {
+        console.warn('[org-scope:cache] write failed', err)
+      }
     }
+
+    return baseScope
+  }
+
+  if (requestMemo && cacheKey) {
+    const pending = resolveScope()
+    requestMemo.set(cacheKey, pending)
+    return pending
   }
 
-  return baseScope
+  return resolveScope()
 }
 
 export type FeatureCheckContext = {

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

@@ -13,16 +13,20 @@ export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
 }
 
+const MAX_DEFINITIONS_PER_BATCH = 1000
+
 const batchSchema = z
   .object({
     entityId: z.string().regex(/^[a-z0-9_]+:[a-z0-9_]+$/),
-    definitions: z.array(
-      upsertCustomFieldDefSchema
-        .omit({ entityId: true })
-        .extend({
-          configJson: z.any().optional(),
-        })
-    ),
+    definitions: z
+      .array(
+        upsertCustomFieldDefSchema
+          .omit({ entityId: true })
+          .extend({
+            configJson: z.any().optional(),
+          })
+      )
+      .max(MAX_DEFINITIONS_PER_BATCH),
   })
   .extend(customFieldEntityConfigSchema.shape)
 

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

@@ -7,6 +7,7 @@ import { getEntityIds } from '@open-mercato/shared/lib/encryption/entityIds'
 import { upsertCustomEntitySchema } from '@open-mercato/core/modules/entities/data/validators'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { isSystemEntitySelectable } from '@open-mercato/shared/lib/entities/system-entities'
+import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 
 export const metadata = {
   GET: { requireAuth: true },
@@ -107,6 +108,16 @@ export async function POST(req: Request) {
   const { resolve } = await createRequestContainer()
   const em = resolve('em') as any
 
+  // A registration for a module-declared, table-backed system entity would flip
+  // query-engine classification to doc storage for the whole entity type (#2939's
+  // failure mode via another door) — refuse to create one.
+  if (isOrmBackedSystemEntityId(em, input.entityId)) {
+    return NextResponse.json(
+      { error: 'System entities cannot be registered as custom entities', code: SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, entityId: input.entityId },
+      { status: 400 },
+    )
+  }
+
   const where: any = { entityId: input.entityId, organizationId: auth.orgId ?? null, tenantId: auth.tenantId ?? null }
   let ent = await em.findOne(CustomEntity, where)
   if (!ent) ent = em.create(CustomEntity, { ...where, createdAt: new Date() })

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

@@ -6,6 +6,7 @@ import type { QueryEngine, QueryOptions, Where, Sort } from '@open-mercato/share
 import { normalizeExportFormat, serializeExport, defaultExportFilename, ensureColumns } from '@open-mercato/shared/lib/crud/exporters'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { resolveOrganizationScope, getSelectedOrganizationFromRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { setRecordCustomFields } from '../lib/helpers'
 import { CustomFieldValue } from '../data/entities'
@@ -36,24 +37,34 @@ function isDeclaredCustomEntity(entityId: string): boolean {
 
 const CUSTOM_ENTITY_RECORD_RESOURCE_KIND = 'entities.record'
 
-async function detectCustomEntity(em: any, entityId: string): Promise<boolean> {
-  if (isDeclaredCustomEntity(entityId)) return true
+type RecordsEntityKind = 'system' | 'custom' | 'unknown'
+
+// This surface manages doc-storage records, which exist for CUSTOM entities only.
+// Module-declared ids backed by a registered ORM table are system entities — their
+// records live in their own module tables/APIs, and stray doc rows for them poisoned
+// read-path classification platform-wide (#2939) — so they are rejected outright. The
+// previous fallback that classified an entity by the mere presence of
+// `custom_entities_storage` rows is gone: within the allowed set, declaration (ce.ts)
+// or an active `custom_entities` registration is authoritative.
+async function classifyRecordsEntity(em: any, entityId: string): Promise<RecordsEntityKind> {
+  if (isOrmBackedSystemEntityId(em, entityId)) return 'system'
+  if (isDeclaredCustomEntity(entityId)) return 'custom'
   try {
     const { CustomEntity } = await import('../data/entities')
-    const found = await em.findOne(CustomEntity as any, { entityId, isActive: true })
-    if (found) return true
+    // Any registration row — active or soft-deleted — proves the id is a custom
+    // entity. Records persist beyond the definition's soft delete (TC-ENTITIES-006)
+    // and must stay readable/deletable, e.g. for the restore flow and cleanup.
+    const found = await em.findOne(CustomEntity as any, { entityId })
+    if (found) return 'custom'
   } catch {}
-  try {
-    const db = em.getKysely()
-    const row = await db
-      .selectFrom('custom_entities_storage' as any)
-      .select(['entity_id' as any])
-      .where('entity_type' as any, '=', entityId)
-      .limit(1)
-      .executeTakeFirst()
-    return !!row
-  } catch {}
-  return false
+  return 'unknown'
+}
+
+function systemEntityRecordsRejection(entityId: string) {
+  return NextResponse.json(
+    { error: 'Records are available for custom entities only', code: SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, entityId },
+    { status: 400 },
+  )
 }
 
 async function readCustomEntityRecordUpdatedAt(
@@ -148,13 +159,13 @@ export async function GET(req: Request) {
     const rbac = resolve('rbacService') as RbacService
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     let organizationIds: string[] | null = scope.filterIds
-    // Read/write symmetry: this endpoint writes every record to custom_entities_storage
-    // via the data engine, including module-declared custom entities whose id is a
-    // frozen system id and therefore never registered in `custom_entities`. detectCustomEntity
-    // covers the declared-entity registry plus the custom_entities / doc-storage fallbacks
-    // (mirrors HybridQueryEngine.isCustomEntity) so mapRow strips the cf_ prefix and the edit
-    // form can read back saved values.
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    // Module-declared custom entities (ce.ts) carry frozen system-style ids and are never
+    // registered in `custom_entities`, so classification checks the declared registry plus
+    // active registrations. System (table-backed) ids are rejected above; for the allowed
+    // set `isCustomEntity` drives mapRow's cf_ stripping so the edit form reads back values.
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'view', isCustomEntity, rbac })
     if (organizationIds && organizationIds.length === 0) {
       return NextResponse.json({ items: [], total: 0, page, pageSize, totalPages: 0 })
@@ -230,6 +241,10 @@ export async function GET(req: Request) {
     if (organizationIds && organizationIds.length) {
       qopts.organizationIds = organizationIds
     }
+    // Allowed entities are doc-storage-backed by definition (system ids were rejected
+    // above) — direct the engine to doc storage explicitly so reads stay deterministic
+    // even before the first record exists.
+    if (isCustomEntity) qopts.forceCustomEntityStorage = true
     for (const [k, v] of qpEntries) buildFilter(k, v, isCustomEntity)
     const res = await qe.query(entityId as any, qopts)
     const rawItems = res.items || []
@@ -363,7 +378,9 @@ export async function POST(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     const norm = normalizeValues(values)
 
@@ -427,7 +444,9 @@ export async function PUT(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     const norm = normalizeValues(values)
 
@@ -516,7 +535,9 @@ export async function DELETE(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     await de.deleteCustomEntityRecord({ entityId, recordId, organizationId: targetOrgId, tenantId: auth.tenantId!, soft: true })
     return NextResponse.json({ ok: true })

package/src/modules/entities/backend/entities/user/[entityId]/records/[recordId]/page.tsx

@@ -6,6 +6,8 @@ import { z } from 'zod'
 import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError, raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type UpdateRecordRequest = (payload: { entityId: string; recordId: string; values: Record<string, unknown> }) => Promise<void>
 
@@ -38,6 +40,19 @@ export async function submitCustomEntityRecordUpdate(options: {
 type RecordsResponse = { items: any[] }
 
 export default function EditRecordPage({ params }: { params: { entityId?: string; recordId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard === 'blocked') {
+    return <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+  }
+  if (guard === 'checking') {
+    return <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+  }
+  return <EditRecordPageInner params={params} />
+}
+
+function EditRecordPageInner({ params }: { params: { entityId?: string; recordId?: string } }) {
   const t = useT()
   const entityId = decodeURIComponent(params?.entityId || '')
   const recordId = decodeURIComponent(params?.recordId || '')

package/src/modules/entities/backend/entities/user/[entityId]/records/create/page.tsx

@@ -6,6 +6,8 @@ import { CrudForm, type CrudField } from '@open-mercato/ui/backend/CrudForm'
 import { z } from 'zod'
 import { createCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type CreateRecordRequest = (payload: { entityId: string; values: Record<string, unknown> }) => Promise<void>
 
@@ -30,6 +32,19 @@ export async function submitCustomEntityRecord(options: {
 }
 
 export default function CreateRecordPage({ params }: { params: { entityId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard === 'blocked') {
+    return <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+  }
+  if (guard === 'checking') {
+    return <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+  }
+  return <CreateRecordPageInner params={params} />
+}
+
+function CreateRecordPageInner({ params }: { params: { entityId?: string } }) {
   const t = useT()
   const router = useRouter()
   const entityId = decodeURIComponent(params?.entityId || '')

package/src/modules/entities/backend/entities/user/[entityId]/records/page.tsx

@@ -17,6 +17,9 @@ import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type RecordsResponse = {
   items: any[]
@@ -44,6 +47,26 @@ function normalizeCell(v: any): string {
 }
 
 export default function RecordsPage({ params }: { params: { entityId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard !== 'allowed') {
+    return (
+      <Page>
+        <PageBody>
+          {guard === 'blocked' ? (
+            <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+          ) : (
+            <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+          )}
+        </PageBody>
+      </Page>
+    )
+  }
+  return <RecordsPageInner params={params} />
+}
+
+function RecordsPageInner({ params }: { params: { entityId?: string } }) {
   const entityId = decodeURIComponent(params?.entityId || '')
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'id', desc: false }])
   const [page, setPage] = React.useState(1)

package/src/modules/entities/components/useRecordsEntityGuard.ts

@@ -0,0 +1,41 @@
+"use client"
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+
+export type RecordsEntityGuardState = 'checking' | 'blocked' | 'allowed'
+
+// Mirrors SYSTEM_ENTITY_RECORDS_BLOCKED_CODE from @open-mercato/shared/lib/data/engine —
+// kept as a literal so client bundles do not pull the server-side data engine in.
+const SYSTEM_ENTITY_RECORDS_BLOCKED_CODE = 'system_entity_records_blocked'
+
+/**
+ * The records surface serves custom entities only; the API rejects system
+ * (table-backed) entity ids with 400 + `system_entity_records_blocked` (#2939
+ * hardening). Records pages are URL-addressable for any entity id, so they probe
+ * once and render a dedicated error state instead of a broken table/form.
+ * Fails open on transport errors — the page's own data calls surface those.
+ */
+export function useRecordsEntityGuard(entityId: string): RecordsEntityGuardState {
+  const [state, setState] = React.useState<RecordsEntityGuardState>(entityId ? 'checking' : 'allowed')
+  React.useEffect(() => {
+    if (!entityId) {
+      setState('allowed')
+      return
+    }
+    let cancelled = false
+    setState('checking')
+    apiCall<{ code?: string }>(`/api/entities/records?entityId=${encodeURIComponent(entityId)}&page=1&pageSize=1`)
+      .then((res) => {
+        if (cancelled) return
+        const blocked = res.status === 400 && res.result?.code === SYSTEM_ENTITY_RECORDS_BLOCKED_CODE
+        setState(blocked ? 'blocked' : 'allowed')
+      })
+      .catch(() => {
+        if (!cancelled) setState('allowed')
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [entityId])
+  return state
+}

package/src/modules/entities/i18n/de.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Datensatz konnte nicht gelöscht werden",
   "entities.userEntities.records.errors.entityIdRequired": "Entitätskennung ist erforderlich",
   "entities.userEntities.records.errors.recordIdRequired": "Datensatzkennung ist erforderlich",
+  "entities.userEntities.records.errors.systemEntity": "Diese Entität wird vom System verwaltet. Datensätze sind nur für benutzerdefinierte Entitäten verfügbar.",
   "entities.userEntities.records.form.createTitle": "Datensatz erstellen",
   "entities.userEntities.records.form.editTitle": "Datensatz bearbeiten",
   "entities.userEntities.records.form.submitCreate": "Erstellen",

package/src/modules/entities/i18n/en.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Failed to delete record",
   "entities.userEntities.records.errors.entityIdRequired": "Entity identifier is required",
   "entities.userEntities.records.errors.recordIdRequired": "Record identifier is required",
+  "entities.userEntities.records.errors.systemEntity": "This entity is system-managed. Records are available for custom entities only.",
   "entities.userEntities.records.form.createTitle": "Create record",
   "entities.userEntities.records.form.editTitle": "Edit record",
   "entities.userEntities.records.form.submitCreate": "Create",

package/src/modules/entities/i18n/es.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "No se pudo eliminar el registro",
   "entities.userEntities.records.errors.entityIdRequired": "Se requiere el identificador de la entidad",
   "entities.userEntities.records.errors.recordIdRequired": "Se requiere el identificador del registro",
+  "entities.userEntities.records.errors.systemEntity": "Esta entidad está gestionada por el sistema. Los registros solo están disponibles para entidades personalizadas.",
   "entities.userEntities.records.form.createTitle": "Crear registro",
   "entities.userEntities.records.form.editTitle": "Editar registro",
   "entities.userEntities.records.form.submitCreate": "Crear",

package/src/modules/entities/i18n/pl.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Nie udało się usunąć rekordu",
   "entities.userEntities.records.errors.entityIdRequired": "Wymagany jest identyfikator encji",
   "entities.userEntities.records.errors.recordIdRequired": "Wymagany jest identyfikator rekordu",
+  "entities.userEntities.records.errors.systemEntity": "Ta encja jest zarządzana systemowo. Rekordy są dostępne wyłącznie dla encji niestandardowych.",
   "entities.userEntities.records.form.createTitle": "Utwórz rekord",
   "entities.userEntities.records.form.editTitle": "Edytuj rekord",
   "entities.userEntities.records.form.submitCreate": "Utwórz",

package/src/modules/query_index/data/entities.ts

@@ -254,6 +254,7 @@ export class IndexerStatusLog {
 @Entity({ tableName: 'search_tokens' })
 @Index({ name: 'search_tokens_lookup_idx', properties: ['entityType', 'field', 'tokenHash', 'tenantId', 'organizationId'] })
 @Index({ name: 'search_tokens_entity_idx', properties: ['entityType', 'entityId'] })
+@Index({ name: 'search_tokens_tenant_token_hash_idx', properties: ['tenantId', 'tokenHash'] })
 export class SearchToken {
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string

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

@@ -2,7 +2,7 @@ import type { QueryEngine, QueryOptions, QueryResult, FilterOp, Filter, QueryCus
 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 } from '@open-mercato/shared/lib/query/engine'
+import { BasicQueryEngine, resolveEntityTableName, resolveRegisteredEntityTableName } from '@open-mercato/shared/lib/query/engine'
 import { type Kysely, sql, type RawBuilder } from 'kysely'
 import type { EventBus } from '@open-mercato/events'
 import { readCoverageSnapshot, refreshCoverageSnapshot } from './coverage'
@@ -219,7 +219,7 @@ export class HybridQueryEngine implements QueryEngine {
       const debugEnabled = this.isDebugVerbosity()
       if (debugEnabled) this.debug('query:start', { entity })
 
-      const isCustom = await this.isCustomEntity(entity)
+      const isCustom = opts.forceCustomEntityStorage === true || await this.isCustomEntity(entity)
       if (isCustom) {
         if (debugEnabled) this.debug('query:custom-entity', { entity })
         const section = profiler.section('custom_entity')
@@ -1005,6 +1005,14 @@ export class HybridQueryEngine implements QueryEngine {
         .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.
+        result = false
       } else {
         // Read/write symmetry. Records written through the entities data engine
         // (`de.createCustomEntityRecord`) always land in `custom_entities_storage`,
@@ -1012,9 +1020,7 @@ export class HybridQueryEngine implements QueryEngine {
         // 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). A real ORM entity never writes rows
-        // to `custom_entities_storage`, so this can only ever re-classify genuine
-        // doc-storage entities — it cannot misroute table-backed entities.
+        // 200 but unreadable on the edit form).
         result = await this.hasCustomEntityStorageRows(entity)
       }
     } catch {

package/src/modules/query_index/migrations/.snapshot-open-mercato.json

@@ -1354,6 +1354,17 @@
           "primary": false,
           "unique": false
         },
+        {
+          "columnNames": [
+            "tenant_id",
+            "token_hash"
+          ],
+          "composite": true,
+          "constraint": false,
+          "keyName": "search_tokens_tenant_token_hash_idx",
+          "primary": false,
+          "unique": false
+        },
         {
           "columnNames": [
             "id"