@open-mercato/core 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/src/modules/customer_accounts/services/domainMappingService.ts

@@ -9,9 +9,17 @@ import {
 import { Organization } from '@open-mercato/core/modules/directory/data/entities'
 import { emitCustomerAccountsEvent } from '@open-mercato/core/modules/customer_accounts/events'
 import { normalizeHostname, tryNormalizeHostname } from '@open-mercato/core/modules/customer_accounts/lib/hostname'
+import { findOrganizationInTenant } from '@open-mercato/core/modules/customer_accounts/lib/organizationLookup'
 import { platformDomains } from '@open-mercato/core/modules/customer_accounts/lib/platformDomains'
 import { detectProxy, isInKnownProxyRange } from '@open-mercato/core/modules/customer_accounts/lib/proxyRanges'
 
+export class DomainMappingOrgScopeError extends Error {
+  constructor(organizationId: string) {
+    super(`[internal] organizationId ${organizationId} does not belong to the caller's tenant`)
+    this.name = 'DomainMappingOrgScopeError'
+  }
+}
+
 const DOMAIN_ROUTING_TAG = 'domain_routing'
 const RESOLVE_KEY_PREFIX = 'domain_routing:resolve'
 const ACTIVE_BY_ORG_KEY_PREFIX = 'domain_routing:active-by-org'
@@ -269,6 +277,8 @@ export class DomainMappingService {
 
   async register(input: RegisterInput): Promise<DomainMapping> {
     const hostname = normalizeHostname(input.hostname)
+    const organization = await findOrganizationInTenant(this.em, input.organizationId, input.tenantId)
+    if (!organization) throw new DomainMappingOrgScopeError(input.organizationId)
 
     let replacesDomain: DomainMapping | null = null
     if (input.replacesDomainId) {

package/src/modules/customers/ai-tools/companies-pack.ts

@@ -85,7 +85,7 @@ const listCompaniesTool = defineApiBackedAiTool<
   name: 'customers.list_companies',
   displayName: 'List companies',
   description:
-    'Search / list companies for the caller tenant + organization. Returns { items, total, limit, offset }.',
+    'Search / list companies for the caller tenant + organization. Returns { items, total, totalIsCapped, limit, offset }. When totalIsCapped is true, total is a floor ("at least N", render it as "N+"), and pagination is exhausted only when a page returns fewer than limit items — never when offset reaches total.',
   inputSchema: listCompaniesInput,
   requiredFeatures: ['customers.companies.view'],
   toOperation: (input, ctx) => {
@@ -122,6 +122,9 @@ const listCompaniesTool = defineApiBackedAiTool<
         sizeBucket: row.size_bucket ?? row.sizeBucket ?? null,
       })),
       total: typeof data.total === 'number' ? data.total : 0,
+      // A capped count reports a floor: phrase the total as "at least N" and
+      // never treat it as proof that pagination is exhausted.
+      totalIsCapped: (data as { totalIsCapped?: boolean }).totalIsCapped === true,
       limit,
       offset,
     }

package/src/modules/customers/ai-tools/deal-analyzer-pack.ts

@@ -192,14 +192,29 @@ const analyzeDealsToolDefinition: CustomersAiToolDefinition<AnalyzeDealsInput, A
     // has no encrypted columns, but the linked CustomerEntity.display_name is
     // encrypted, so resolve names via findWithDecryption rather than
     // populating the relation through raw em.find.
+    // Defense-in-depth: `customer_deal_people` carries no tenant/org columns,
+    // so DB-level scoping is via the tenant-filtered `dealIds` set. Filter the
+    // returned rows against the caller-scoped deals map so a future refactor
+    // that widens `dealIds` cannot surface cross-tenant links.
+    const dealById = new Map<string, CustomerDeal>(deals.map((deal) => [deal.id, deal]))
+    const scopedDealIds = Array.from(dealById.keys())
     const personLinkWhere: Record<string, unknown> = {
-      deal: { $in: dealIds },
+      deal: { $in: scopedDealIds },
     }
-    const personLinks = await em.find(
+    const personLinksRaw = await em.find(
       CustomerDealPersonLink,
       personLinkWhere as any,
       { limit: 500 },
     )
+    const personLinks = personLinksRaw.filter((link) => {
+      const dealRefId = refIdOf((link as { deal?: unknown }).deal)
+      if (!dealRefId) return false
+      const scopedDeal = dealById.get(dealRefId)
+      if (!scopedDeal) return false
+      if (scopedDeal.tenantId !== tenantId) return false
+      if (ctx.organizationId && scopedDeal.organizationId !== ctx.organizationId) return false
+      return true
+    })
 
     const linksByDeal = new Map<string, string>() // dealId → personId (first link wins)
     for (const link of personLinks) {

package/src/modules/customers/ai-tools/deals-pack.ts

@@ -27,6 +27,11 @@ import {
   CustomerDeal,
   CustomerPipelineStage,
 } from '../data/entities'
+import {
+  dealClosureOutcomeFromStatus,
+  loadClosurePipelineStageSnapshot,
+} from '../lib/closureStage'
+import { canonicalDealStatus, isClosedDealStatus } from '../lib/dealStatus'
 import {
   assertTenantScope,
   type CustomersAiToolDefinition,
@@ -99,7 +104,7 @@ const listDealsTool = defineApiBackedAiTool<ListDealsInput, ListDealsApiResponse
   name: 'customers.list_deals',
   displayName: 'List deals',
   description:
-    'Search / list deals for the caller tenant + organization. Optional filters include linked person / company / pipeline stage.',
+    'Search / list deals for the caller tenant + organization. Optional filters include linked person / company / pipeline stage. Returns { items, total, totalIsCapped, limit, offset }. When totalIsCapped is true, total is a floor ("at least N", render it as "N+"), and pagination is exhausted only when a page returns fewer than limit items — never when offset reaches total.',
   inputSchema: listDealsInput,
   requiredFeatures: ['customers.deals.view'],
   toOperation: (input, ctx) => {
@@ -155,6 +160,9 @@ const listDealsTool = defineApiBackedAiTool<ListDealsInput, ListDealsApiResponse
         }
       }),
       total: typeof data.total === 'number' ? data.total : 0,
+      // A capped count reports a floor: phrase the total as "at least N" and
+      // never treat it as proof that pagination is exhausted.
+      totalIsCapped: (data as { totalIsCapped?: boolean }).totalIsCapped === true,
       limit,
       offset,
     }
@@ -466,10 +474,48 @@ const updateDealStageTool: CustomersAiToolDefinition = {
       afterPipelineStageLabel = stage?.label ?? input.toPipelineStageId
     } else if (input.toStage) {
       afterStatus = input.toStage
+      // The update command derives a closure outcome from terminal status spellings and
+      // relocates the deal to the pipeline's terminal stage (#5107) — preview that same
+      // projection so the approval card states the full blast radius.
+      const organizationId = deal.organizationId ?? ctx.organizationId ?? null
+      const outcome = dealClosureOutcomeFromStatus(input.toStage)
+      if (outcome && organizationId) {
+        const terminalStage = await loadClosurePipelineStageSnapshot(em, {
+          pipelineId: deal.pipelineId ?? null,
+          closureOutcome: outcome,
+          tenantId,
+          organizationId,
+        })
+        if (terminalStage) {
+          afterPipelineStageId = terminalStage.id
+          afterPipelineStageLabel = terminalStage.label
+        }
+      }
     }
     const beforeStatus = deal.status ?? null
     const beforePipelineStageId = deal.pipelineStageId ?? null
     const beforePipelineStageLabel = deal.pipelineStage ?? beforePipelineStageId
+    const beforeClosureOutcome = deal.closureOutcome ?? null
+    const beforeLossReasonId = deal.lossReasonId ?? null
+    const beforeLossNotes = deal.lossNotes ?? null
+    // Mirror the update command exactly (#5107): a status-only write derives the closure
+    // outcome for terminal spellings, clears outcome plus loss columns for non-closed
+    // non-terminal ones (reopen), and leaves `closed` and stage-only writes untouched.
+    // `toStage` is free-form model text, so canonicalize before the `closed` check — the
+    // command does the same, and the two must stay in lockstep or the approval card would
+    // preview a different write than the one that lands.
+    const requestedOutcome = dealClosureOutcomeFromStatus(input.toStage)
+    const clearsClosure =
+      input.toPipelineStageId === undefined &&
+      input.toStage !== undefined &&
+      !requestedOutcome &&
+      !isClosedDealStatus(canonicalDealStatus(input.toStage))
+    const afterClosureOutcome = clearsClosure
+      ? null
+      : requestedOutcome ?? beforeClosureOutcome
+    const closureOutcomeCleared = beforeClosureOutcome !== null && afterClosureOutcome === null
+    const afterLossReasonId = closureOutcomeCleared ? null : beforeLossReasonId
+    const afterLossNotes = closureOutcomeCleared ? null : beforeLossNotes
     return {
       recordId: deal.id,
       entityType: 'customers.deal',
@@ -477,23 +523,42 @@ const updateDealStageTool: CustomersAiToolDefinition = {
       before: {
         status: beforeStatus,
         pipelineStageId: beforePipelineStageId,
+        closureOutcome: beforeClosureOutcome,
+        lossReasonId: beforeLossReasonId,
+        lossNotes: beforeLossNotes,
       },
       after: {
         status: afterStatus,
         pipelineStageId: afterPipelineStageId,
+        closureOutcome: afterClosureOutcome,
+        lossReasonId: afterLossReasonId,
+        lossNotes: afterLossNotes,
       },
       display: {
         fieldLabels: {
           status: 'Status',
           pipelineStageId: 'Pipeline stage',
+          closureOutcome: 'Closure outcome',
+          lossReasonId: 'Loss reason',
+          lossNotes: 'Loss notes',
         },
         before: {
           ...(beforeStatus ? { status: titleStatus(beforeStatus) } : {}),
           ...(beforePipelineStageLabel ? { pipelineStageId: beforePipelineStageLabel } : {}),
+          ...(beforeClosureOutcome ? { closureOutcome: titleStatus(beforeClosureOutcome) } : {}),
+          ...(beforeLossReasonId ? { lossReasonId: beforeLossReasonId } : {}),
+          ...(beforeLossNotes ? { lossNotes: beforeLossNotes } : {}),
         },
         after: {
           ...(afterStatus ? { status: titleStatus(afterStatus) } : {}),
           ...(afterPipelineStageLabel ? { pipelineStageId: afterPipelineStageLabel } : {}),
+          ...(afterClosureOutcome
+            ? { closureOutcome: titleStatus(afterClosureOutcome) }
+            : closureOutcomeCleared
+              ? { closureOutcome: '—' }
+              : {}),
+          ...(afterLossReasonId ? { lossReasonId: afterLossReasonId } : {}),
+          ...(afterLossNotes ? { lossNotes: afterLossNotes } : {}),
         },
       },
     }

package/src/modules/customers/ai-tools/people-pack.ts

@@ -90,7 +90,7 @@ const listPeopleTool = defineApiBackedAiTool<ListPeopleInput, ListPeopleApiRespo
   name: 'customers.list_people',
   displayName: 'List people',
   description:
-    'Search / list people (CRM persons) for the caller tenant + organization. Returns { items, total, limit, offset }.',
+    'Search / list people (CRM persons) for the caller tenant + organization. Returns { items, total, totalIsCapped, limit, offset }. When totalIsCapped is true, total is a floor ("at least N", render it as "N+"), and pagination is exhausted only when a page returns fewer than limit items — never when offset reaches total.',
   inputSchema: listPeopleInput,
   requiredFeatures: ['customers.people.view'],
   toOperation: async (input, ctx) => {
@@ -144,6 +144,9 @@ const listPeopleTool = defineApiBackedAiTool<ListPeopleInput, ListPeopleApiRespo
     return {
       items: rawItems.map((row) => toCustomerListSummary(row)),
       total: typeof data.total === 'number' ? data.total : 0,
+      // A capped count reports a floor: phrase the total as "at least N" and
+      // never treat it as proof that pagination is exhausted.
+      totalIsCapped: (data as { totalIsCapped?: boolean }).totalIsCapped === true,
       limit,
       offset,
     }

package/src/modules/customers/api/activities/route.ts

@@ -284,7 +284,22 @@ async function listCanonicalActivities(
   organizationIds: string[] | null,
   query: z.infer<typeof listSchema>,
   options?: { includeDeleted?: boolean; source?: string | string[] | null; paginate?: boolean },
+  isUnrestricted?: boolean,
 ): Promise<CanonicalActivityListResult> {
+  if (organizationIds && organizationIds.length === 0 && !isUnrestricted) {
+    return {
+      items: [],
+      total: 0,
+      bridgeIds: new Set(),
+    }
+  }
+  if (organizationIds === null && !isUnrestricted) {
+    return {
+      items: [],
+      total: 0,
+      bridgeIds: new Set(),
+    }
+  }
   const where: Record<string, unknown> = {
     tenantId,
     interactionType: { $ne: 'task' },
@@ -361,7 +376,14 @@ async function listLegacyActivities(
   query: z.infer<typeof listSchema>,
   options?: { paginate?: boolean },
   selectedOrganizationId?: string | null,
+  isUnrestricted?: boolean,
 ): Promise<{ items: ActivityItem[]; total: number }> {
+  if (organizationIds && organizationIds.length === 0 && !isUnrestricted) {
+    return { items: [], total: 0 }
+  }
+  if (organizationIds === null && !isUnrestricted) {
+    return { items: [], total: 0 }
+  }
   const where: Record<string, unknown> = { tenantId }
   if (organizationIds && organizationIds.length > 0) {
     where.organizationId = { $in: organizationIds }
@@ -410,12 +432,31 @@ export async function GET(request: Request): Promise<Response> {
       organizationIds,
       container,
       selectedOrganizationId,
+      scope,
     } = await resolveCustomersRequestContext(request)
     const flags = await resolveCustomerInteractionFeatureFlags(container, auth.tenantId)
     if (!flags.legacyAdapters) {
       return await legacyAdaptersDisabledResponse()
     }
 
+    const isUnrestricted = auth.isSuperAdmin === true || scope?.allowedIds === null
+    if (!isUnrestricted && (!organizationIds || organizationIds.length === 0)) {
+      logger.warn('activities.list collapsed organization scope — returning empty page', {
+        tenantId: auth.tenantId,
+        organizationIds,
+        scope,
+      })
+      return withAdapterHeaders(
+        NextResponse.json({
+          items: [],
+          total: 0,
+          page: query.page,
+          pageSize: query.pageSize,
+          totalPages: 1,
+        }),
+      )
+    }
+
     const sortDir = query.sortDir ?? 'desc'
 
     const result = flags.unified
@@ -427,6 +468,8 @@ export async function GET(request: Request): Promise<Response> {
           auth.tenantId,
           organizationIds,
           query,
+          undefined,
+          isUnrestricted,
         )
       : await (async () => {
         const windowSize = Math.min(
@@ -442,6 +485,7 @@ export async function GET(request: Request): Promise<Response> {
             windowedQuery,
             { paginate: true },
             selectedOrganizationId,
+            isUnrestricted,
           ),
           listCanonicalActivities(
             em,
@@ -456,6 +500,7 @@ export async function GET(request: Request): Promise<Response> {
               paginate: true,
               source: CUSTOMER_INTERACTION_ACTIVITY_ADAPTER_SOURCE,
             },
+            isUnrestricted,
           ),
         ])
         const merged = sortActivityItems(

package/src/modules/customers/api/companies/[id]/people/route.ts

@@ -7,17 +7,10 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
-import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
-import {
-  CustomerEntity,
-  CustomerPersonCompanyLink,
-  CustomerPersonProfile,
-} from '../../../../data/entities'
-import {
-  filterActivePersonCompanyLinks,
-  withActiveCustomerPersonCompanyLinkFilter,
-} from '../../../../lib/personCompanyLinkTable'
+import { CustomerEntity } from '../../../../data/entities'
+import { loadCompanyPeopleUnion } from '../../../../lib/personCompanies'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('customers')
@@ -119,73 +112,31 @@ export async function GET(req: Request, ctx: { params?: { id?: string } }) {
       throw notFound(translate('customers.errors.company_not_found', 'Company not found'))
     }
 
+    // Existence oracle (#5504): deny a cross-org read as not-found — identical to
+    // the parent-not-found above — so it cannot reveal that a company exists in an
+    // organization the caller cannot see.
     if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: company.organizationId })) {
-      throw new CrudHttpError(403, { error: translate('customers.errors.access_denied', 'Access denied') })
+      throw notFound(translate('customers.errors.company_not_found', 'Company not found'))
     }
 
     const entityScope = { tenantId: auth.tenantId, organizationId: company.organizationId }
-    const linkWhere = await withActiveCustomerPersonCompanyLinkFilter(
-      em,
-      {
-        company: company.id,
-        tenantId: company.tenantId,
-        organizationId: company.organizationId,
-      },
-      'customers.companies.people.GET',
-    )
-    const links = filterActivePersonCompanyLinks(
-      await findWithDecryption(
-        em,
-        CustomerPersonCompanyLink,
-        linkWhere,
-        { populate: ['person'] },
-        entityScope,
-      ),
-    )
-
-    const personIds = links
-      .map((link) => link.person?.id)
-      .filter((personId): personId is string => typeof personId === 'string' && personId.length > 0)
-
-    const profiles = personIds.length > 0
-      ? await findWithDecryption(
-          em,
-          CustomerPersonProfile,
-          {
-            entity: { $in: personIds },
-            tenantId: company.tenantId,
-            organizationId: company.organizationId,
-          },
-          {},
-          entityScope,
-        )
-      : []
-    const profileByPersonId = new Map(
-      profiles.map((profile) => [(profile.entity as { id: string }).id, profile]),
-    )
-
-    const items = links
-      .map((link) => {
-        const person = link.person
-        if (!person?.id) return null
-        const profile = profileByPersonId.get(person.id) ?? null
-        return {
-          id: person.id,
-          displayName: person.displayName ?? person.primaryEmail ?? person.id,
-          primaryEmail: person.primaryEmail ?? null,
-          primaryPhone: person.primaryPhone ?? null,
-          status: person.status ?? null,
-          lifecycleStage: person.lifecycleStage ?? null,
-          jobTitle: profile?.jobTitle ?? null,
-          department: profile?.department ?? null,
-          createdAt: person.createdAt.toISOString(),
-          organizationId: person.organizationId,
-          temperature: person.temperature ?? null,
-          source: person.source ?? null,
-          linkedAt: link.createdAt ? link.createdAt.toISOString() : null,
-        } satisfies CompanyPersonItem
-      })
-      .filter((item): item is CompanyPersonItem => item !== null)
+    const union = await loadCompanyPeopleUnion(em, company, entityScope)
+
+    const items = union.map(({ entity: person, profile, linkedAt }) => ({
+      id: person.id,
+      displayName: person.displayName ?? person.primaryEmail ?? person.id,
+      primaryEmail: person.primaryEmail ?? null,
+      primaryPhone: person.primaryPhone ?? null,
+      status: person.status ?? null,
+      lifecycleStage: person.lifecycleStage ?? null,
+      jobTitle: profile?.jobTitle ?? null,
+      department: profile?.department ?? null,
+      createdAt: person.createdAt.toISOString(),
+      organizationId: person.organizationId,
+      temperature: person.temperature ?? null,
+      source: person.source ?? null,
+      linkedAt,
+    } satisfies CompanyPersonItem))
 
     const filtered = query.search?.trim().length ? items.filter((item) => matchesSearch(item, query.search ?? '')) : items
     const sorted = sortItems(filtered, query.sort)

package/src/modules/customers/api/companies/[id]/route.ts

@@ -17,8 +17,6 @@ import {
   CustomerDealCompanyLink,
   CustomerDeal,
   CustomerTodoLink,
-  CustomerPersonCompanyLink,
-  CustomerPersonProfile,
   CustomerInteraction,
 } from '../../../data/entities'
 import { User } from '@open-mercato/core/modules/auth/data/entities'
@@ -47,11 +45,12 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { parseBooleanFromUnknown } from '@open-mercato/shared/lib/boolean'
 import {
-  filterActivePersonCompanyLinks,
-  withActiveCustomerPersonCompanyLinkFilter,
-} from '../../../lib/personCompanyLinkTable'
+  countCompanyPeopleUnion,
+  loadCompanyPeopleUnion,
+  type CompanyPersonUnionEntry,
+} from '../../../lib/personCompanies'
 import { normalizeCustomerDetailCustomFields } from '../../detailCustomFields'
-import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
+import { denyCustomerDetailReadAsNotFound } from '../../../lib/detailReadAccess'
 import { runWithCacheTenant } from '@open-mercato/cache'
 import {
   buildCollectionTags,
@@ -146,10 +145,6 @@ function parseIncludeParams(request: Request): Set<string> {
   return tokens
 }
 
-function forbidden(message: string) {
-  return NextResponse.json({ error: message }, { status: 403 })
-}
-
 function notFound(message: string) {
   return NextResponse.json({ error: message }, { status: 404 })
 }
@@ -463,9 +458,16 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
   )
   if (!company) return notFound('Company not found')
 
-  if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: company.organizationId })) {
-    return forbidden('Access denied')
-  }
+  // Existence oracle (issue #5504): a caller who holds customers.companies.view
+  // but whose scope excludes the record's organization must get the SAME
+  // response as for a non-existent id, so 403-when-present / 404-when-absent
+  // collapses to a uniform 404 not-found. The dispatcher already returns a
+  // uniform 403 for callers who lack the feature entirely.
+  const organizationReadDenied = denyCustomerDetailReadAsNotFound(
+    { scope, auth, organizationId: company.organizationId },
+    'Company not found',
+  )
+  if (organizationReadDenied) return organizationReadDenied
 
   const companyScope = {
     tenantId: company.tenantId ?? auth.tenantId ?? null,
@@ -801,79 +803,13 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
             deal.organizationId === company.organizationId,
         )
 
-  let relatedPeople: Array<{
-    entity: CustomerEntity
-    profile: CustomerPersonProfile | null
-    linkedAt: string | null
-  }> = []
+  const peopleUnionScope = {
+    tenantId: company.tenantId ?? auth.tenantId ?? null,
+    organizationId: company.organizationId ?? scope?.selectedId ?? auth.orgId ?? null,
+  }
+  let relatedPeople: CompanyPersonUnionEntry[] = []
   if (includePeople) {
-    const peopleDecryptionScope = {
-      tenantId: company.tenantId ?? auth.tenantId ?? null,
-      organizationId: company.organizationId ?? scope?.selectedId ?? auth.orgId ?? null,
-    }
-    const relatedPeopleById = new Map<
-      string,
-      { entity: CustomerEntity; profile: CustomerPersonProfile | null; linkedAt: string | null }
-    >()
-    const companyLinkWhere = await withActiveCustomerPersonCompanyLinkFilter(
-      em,
-      {
-        company: company.id,
-        organizationId: company.organizationId,
-        tenantId: company.tenantId,
-      },
-      'customers.companies.GET',
-    )
-    const companyLinks = filterActivePersonCompanyLinks(
-      await findWithDecryption(
-        em,
-        CustomerPersonCompanyLink,
-        companyLinkWhere,
-        {
-          populate: ['person', 'person.personProfile'],
-          orderBy: { isPrimary: 'desc', createdAt: 'asc' },
-        },
-        peopleDecryptionScope,
-      ),
-    )
-    companyLinks.forEach((link) => {
-      const entity = typeof link.person === 'string' ? null : link.person
-      if (!entity || entity.kind !== 'person' || entity.deletedAt) return
-      const personProfile =
-        entity.personProfile && typeof entity.personProfile !== 'string'
-          ? entity.personProfile
-          : null
-      relatedPeopleById.set(entity.id, {
-        entity,
-        profile: personProfile,
-        linkedAt: link.createdAt instanceof Date ? link.createdAt.toISOString() : null,
-      })
-    })
-
-    const profiles = await findWithDecryption(
-      em,
-      CustomerPersonProfile,
-      {
-        company: company.id,
-        tenantId: company.tenantId,
-        organizationId: company.organizationId,
-        entity: { deletedAt: null },
-      },
-      { populate: ['entity'] },
-      peopleDecryptionScope,
-    )
-    profiles.forEach((entry) => {
-      const entity = entry.entity as CustomerEntity | null
-      if (!entity || entity.kind !== 'person' || entity.deletedAt) return
-      if (!relatedPeopleById.has(entity.id)) {
-        relatedPeopleById.set(entity.id, {
-          entity,
-          profile: entry ?? null,
-          linkedAt: entry.createdAt instanceof Date ? entry.createdAt.toISOString() : null,
-        })
-      }
-    })
-    relatedPeople = Array.from(relatedPeopleById.values())
+    relatedPeople = await loadCompanyPeopleUnion(em, company, peopleUnionScope)
   }
 
   // Entity custom fields, profile custom fields, and the routing lookup do not
@@ -919,26 +855,7 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
   // instead of a waterfall (issue #3203).
   const peopleCountQuery = includePeople
     ? Promise.resolve(relatedPeople.length)
-    : (async () => {
-        const peopleLinkWhere = await withActiveCustomerPersonCompanyLinkFilter(
-          em,
-          {
-            company: company.id,
-            organizationId: company.organizationId,
-            tenantId: company.tenantId,
-          },
-          'customers.companies.GET',
-        )
-        return filterActivePersonCompanyLinks(
-          await findWithDecryption(
-            em,
-            CustomerPersonCompanyLink,
-            peopleLinkWhere,
-            {},
-            { tenantId: company.tenantId, organizationId: company.organizationId },
-          ),
-        ).length
-      })()
+    : countCompanyPeopleUnion(em, company)
   const [
     activityCount,
     interactionCount,
@@ -1486,8 +1403,8 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Invalid identifier', schema: companyDetailErrorSchema },
         { status: 401, description: 'Unauthorized', schema: companyDetailErrorSchema },
-        { status: 403, description: 'Forbidden for tenant/organization scope', schema: companyDetailErrorSchema },
-        { status: 404, description: 'Company not found', schema: companyDetailErrorSchema },
+        { status: 403, description: 'Forbidden — caller lacks the required feature', schema: companyDetailErrorSchema },
+        { status: 404, description: 'Company not found, or its organization is not in the caller’s scope', schema: companyDetailErrorSchema },
       ],
     },
   },