@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/modules/customers/lib/dealsOrganizationScope.ts

@@ -25,8 +25,9 @@ export async function resolveDealsOrganizationIds(params: {
   tenantId: string
 }): Promise<string[]> {
   const { em, scope, auth, tenantId } = params
-  if (Array.isArray(scope.filterIds) && scope.filterIds.length > 0) {
-    return scope.filterIds.filter((id) => typeof id === 'string' && id.length > 0)
+  if (Array.isArray(scope.filterIds)) {
+    const ids = scope.filterIds.filter((id) => typeof id === 'string' && id.length > 0)
+    return ids.length > 0 ? ids : [NO_ORGANIZATION_SENTINEL]
   }
   if (scope.filterIds === null) {
     const rows = await em.getConnection().execute<Array<{ id: string }>>(
@@ -35,6 +36,7 @@ export async function resolveDealsOrganizationIds(params: {
     )
     const ids = rows.map((row: { id: string }) => String(row.id)).filter((id: string) => id.length > 0)
     if (ids.length > 0) return ids
+    if (auth.orgId) return [auth.orgId]
   }
-  return auth.orgId ? [auth.orgId] : [NO_ORGANIZATION_SENTINEL]
+  return [NO_ORGANIZATION_SENTINEL]
 }

package/src/modules/customers/lib/interactionRequestContext.ts

@@ -3,6 +3,7 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveSingleOrganizationIdOrDeny } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 
 type AuthContext = NonNullable<Awaited<ReturnType<typeof getAuthFromRequest>>>
@@ -35,7 +36,7 @@ export async function resolveCustomersRequestContext(request: Request): Promise<
   }
 
   const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
-  const selectedOrganizationId = scope?.selectedId ?? auth.orgId ?? null
+  const selectedOrganizationId = resolveSingleOrganizationIdOrDeny(scope, auth) ?? null
   const organizationIds = scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null)
 
   return {

package/src/modules/customers/lib/link-channel-message-handler.ts

@@ -114,6 +114,11 @@ export default async function handler(
   //
   // We look up the channel only when channelId is provided in the event payload.
   let channelUserId: string | null = null
+  // Denormalized onto each interaction so a read path can ask "is this row's
+  // channel shared?" without a three-join hop. NULL when the event carried no
+  // channelId — every predicate treats that as not shared (fail closed).
+  const resolvedChannelId: string | null =
+    typeof payload.channelId === 'string' && payload.channelId ? payload.channelId : null
   if (typeof payload.channelId === 'string' && payload.channelId) {
     const channel = (await findOneWithDecryption(
       em,
@@ -190,7 +195,7 @@ export default async function handler(
   // Early exit: no addresses AND no hint → nothing to link.
   if (normalized.length === 0 && !crmPersonId) {
     // Before giving up, try threading-inheritance (TC-CRM-EMAIL-005).
-    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson, occurredAt)
+    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, resolvedChannelId, metaJson, payloadJson, occurredAt)
     return
   }
 
@@ -201,7 +206,7 @@ export default async function handler(
 
   if (personIdSet.size === 0) {
     // Try threading-inheritance before giving up.
-    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, metaJson, payloadJson, occurredAt)
+    await handleThreadingInheritance(em, link, linkId, tenantId, organizationId, channelUserId, resolvedChannelId, metaJson, payloadJson, occurredAt)
     return
   }
 
@@ -247,6 +252,7 @@ export default async function handler(
       occurredAt,
       visibility,
       channelProviderKey: providerKey,
+      channelId: resolvedChannelId,
     },
   )
 }
@@ -272,6 +278,7 @@ async function handleThreadingInheritance(
   tenantId: string,
   organizationId: string | null,
   channelUserId: string | null,
+  channelId: string | null,
   metaJson: Record<string, unknown> | null,
   payloadJson: Record<string, unknown> | null,
   occurredAt: Date,
@@ -353,8 +360,14 @@ async function handleThreadingInheritance(
         body: bodyText,
         authorUserId: channelUserId,
         occurredAt,
-        visibility: channelUserId ? 'private' : 'shared',
+        // Single source of truth for the ingestion default (see resolveVisibility).
+        // The threading-inheritance path deliberately passes no metadata and no
+        // direction: a reply is matched by parent-thread lookup and its metadata is
+        // provider-derived, so it must never be able to downgrade privacy via the
+        // `crmVisibility` override.
+        visibility: resolveVisibility(null, channelUserId, null),
         channelProviderKey: providerKey,
+        channelId,
       })
       return
     }
@@ -432,7 +445,9 @@ async function handleThreadingInheritance(
 
   if (inheritedPersonIdSet.size === 0) return
 
-  const visibility: 'private' | 'shared' = channelUserId ? 'private' : 'shared'
+  // Same single source of truth as the primary ingestion path; no metadata and no
+  // direction on the inheritance path (see the sibling call above).
+  const visibility: 'private' | 'shared' = resolveVisibility(null, channelUserId, null)
   const link = _link
   const inheritedMeta = (link.channelMetadata ?? null) as Record<string, unknown> | null
   const subject =
@@ -454,6 +469,7 @@ async function handleThreadingInheritance(
       occurredAt,
       visibility,
       channelProviderKey: providerKey,
+      channelId,
     },
   )
 }
@@ -498,6 +514,12 @@ interface InteractionData {
   occurredAt: Date
   visibility: 'private' | 'shared'
   channelProviderKey: string | null
+  /**
+   * Denormalized channel id, so a read path can ask "is this row's channel
+   * shared?" without a three-join hop. NULL when the event carried no channelId
+   * (the predicate then treats the row as not shared — fail closed).
+   */
+  channelId: string | null
 }
 
 async function persistInteractions(
@@ -531,6 +553,7 @@ async function persistInteractions(
       externalMessageId: data.linkId,
       visibility: data.visibility,
       channelProviderKey: data.channelProviderKey,
+      channelId: data.channelId,
     } as any)
     try {
       await rowEm.flush()

package/src/modules/customers/lib/personDetailCacheTags.ts

@@ -0,0 +1,68 @@
+import { buildCollectionTags, canonicalizeResourceTag } from '@open-mercato/shared/lib/crud/cache'
+
+/**
+ * Resources whose collection tags the cached person-detail payload depends on.
+ *
+ * Single source of truth, shared by the READ side (`api/people/[id]/route.ts`,
+ * which stores under these tags) and every WRITE side that must invalidate them.
+ * Hand-formatting the tag strings at a write site is how they silently stop
+ * matching: the canonical shape is `crud:<resource>:tenant:<t>:org:<o>:collection`
+ * and it is produced only by `buildCollectionTags`.
+ */
+export const PERSON_DETAIL_TAG_RESOURCES = [
+  'customers.person',
+  'customers.address',
+  'customers.tagAssignment',
+  'customers.labelAssignment',
+  'customers.personCompanyLink',
+  'customers.interaction',
+  'customers.activity',
+] as const
+
+/**
+ * Collection tags the cached person-detail payload is stored under.
+ *
+ * The resource ids are canonicalized with `canonicalizeResourceTag` (they are
+ * already canonical today, but going through the helper keeps this aligned if the
+ * canonical form ever changes).
+ */
+export function buildPersonDetailCacheTags(
+  tenantId: string | null,
+  organizationId: string | null,
+): string[] {
+  const tags: string[] = []
+  for (const resource of PERSON_DETAIL_TAG_RESOURCES) {
+    const canonical = canonicalizeResourceTag(resource) ?? resource
+    tags.push(...buildCollectionTags(canonical, tenantId, [organizationId]))
+  }
+  return tags
+}
+
+type CacheLike = { invalidateTags?: (tags: string[]) => Promise<void> }
+
+/**
+ * Invalidate the person-detail collection tags after a write that widens or
+ * narrows email visibility.
+ *
+ * Both email-sharing write paths (per-Person conversation share, whole-channel
+ * flag) change which rows the read filter admits without writing any resource the
+ * person-detail cache tags observe, so neither would otherwise invalidate. The
+ * revoke direction is the one that matters: without this a teammate keeps reading
+ * now-private email from their own warm cache entry until the TTL expires.
+ *
+ * Best effort — a stale cached page is a TTL-bounded annoyance, and the write is
+ * already committed by the time this runs.
+ */
+export async function invalidatePersonDetailCache(
+  container: { resolve: (name: string) => unknown },
+  tenantId: string | null,
+  organizationId: string | null,
+): Promise<void> {
+  try {
+    const cache = container.resolve('cache') as CacheLike | undefined
+    if (!cache?.invalidateTags) return
+    await cache.invalidateTags(buildPersonDetailCacheTags(tenantId, organizationId))
+  } catch {
+    /* best effort — never fail a committed write over cache invalidation */
+  }
+}

package/src/modules/customers/lib/personEmailThreads.ts

@@ -1,7 +1,9 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { CustomerInteraction } from '../data/entities'
+import { resolveUserNames } from './userNames'
 import { buildEmailVisibilityMikroFilter } from './visibilityFilter'
+import type { ConversationShareGrant } from './conversationShares'
 
 /**
  * Read model that turns a Person's email `CustomerInteraction` rows into
@@ -30,6 +32,15 @@ export type PersonEmailMessage = {
   direction: EmailThreadDirection
   fromName: string | null
   fromEmail: string | null
+  /**
+   * True when the viewer is the author of this message. Outbound email carries
+   * no `from` header in `channelMetadata`, so the sender label cannot be derived
+   * from the addresses — and since conversation/channel sharing lets a teammate
+   * read someone else's outbound mail, direction alone is not the author either.
+   */
+  authoredByViewer: boolean
+  /** Display label of the sending colleague; null for the viewer's own mail and for inbound. */
+  authorName: string | null
   to: string[]
   cc: string[]
   subject: string | null
@@ -56,6 +67,13 @@ export type BuildPersonEmailThreadsOptions = {
   organizationId: string | null
   viewerUserId: string | null
   userFeatures: string[] | null | undefined
+  /**
+   * Conversation shares that widen this viewer's access. Optional and fail-closed:
+   * omitting it yields the strict owner-only view.
+   */
+  sharedConversations?: ConversationShareGrant[]
+  /** Channels marked as shared team mailboxes; optional and fail-closed. */
+  sharedChannelIds?: string[]
   maxThreads?: number
   maxMessagesPerThread?: number
 }
@@ -128,6 +146,8 @@ export async function buildPersonEmailThreads(
     organizationId,
     viewerUserId,
     userFeatures,
+    sharedConversations,
+    sharedChannelIds,
     maxThreads = DEFAULT_MAX_THREADS,
     maxMessagesPerThread = DEFAULT_MAX_MESSAGES_PER_THREAD,
   } = opts
@@ -154,10 +174,18 @@ export async function buildPersonEmailThreads(
   //     CRM history is never silently hidden.
   // Fail-closed: a null viewer (API-key caller) never matches the author arm, so
   // it only ever sees shared/legacy rows — never anyone's private email.
-  interactionWhere.$or = buildEmailVisibilityMikroFilter({
-    currentUserId: viewerUserId,
-    userFeatures,
-  }).$or
+  // Merge the WHOLE fragment. Cherry-picking `.$or` here would silently discard
+  // any other arm the predicate grows, which fails OPEN at a compile-clean call
+  // site — the exact hazard the fragment contract now documents.
+  Object.assign(
+    interactionWhere,
+    buildEmailVisibilityMikroFilter({
+      currentUserId: viewerUserId,
+      userFeatures,
+      sharedConversations,
+      sharedChannelIds,
+    }),
+  )
 
   // `customer_interaction.title`/`body` are encrypted at rest, so reads go
   // through `findWithDecryption` even though we only consume non-encrypted
@@ -171,12 +199,15 @@ export async function buildPersonEmailThreads(
     dscope,
   )) as CustomerInteraction[]
 
-  const linkIdByInteraction = new Map<string, { occurredAt: Date }>()
+  const linkIdByInteraction = new Map<string, { occurredAt: Date; authorUserId: string | null }>()
   const linkIds: string[] = []
   for (const interaction of interactions) {
     const linkId = interaction.externalMessageId
     if (!linkId || linkIdByInteraction.has(linkId)) continue
-    linkIdByInteraction.set(linkId, { occurredAt: interaction.occurredAt ?? interaction.createdAt })
+    linkIdByInteraction.set(linkId, {
+      occurredAt: interaction.occurredAt ?? interaction.createdAt,
+      authorUserId: interaction.authorUserId ?? null,
+    })
     linkIds.push(linkId)
   }
   if (linkIds.length === 0) return []
@@ -216,6 +247,23 @@ export async function buildPersonEmailThreads(
     }
   }
 
+  // ── (3b) Resolve sender labels for colleagues' messages ─────────────────
+  //
+  // Only for authors other than the viewer: their own mail renders as "You" and
+  // needs no lookup. A shared conversation is exactly the case where a message
+  // the viewer did not write shows up in their thread list, so without this the
+  // UI would have to fall back on direction and misattribute it to the reader.
+  const foreignAuthorIds = Array.from(
+    new Set(
+      Array.from(linkIdByInteraction.values())
+        .map((entry) => entry.authorUserId)
+        .filter((id): id is string => !!id && id !== viewerUserId),
+    ),
+  )
+  const authorNames = foreignAuthorIds.length
+    ? await resolveUserNames(em, tenantId, organizationId, foreignAuthorIds)
+    : new Map<string, string>()
+
   // ── (4) Build per-message DTOs grouped by thread ────────────────────────
   const threadsByKey = new Map<string, PersonEmailThread>()
 
@@ -223,6 +271,11 @@ export async function buildPersonEmailThreads(
     const linkId = typeof link.id === 'string' ? (link.id as string) : null
     if (!linkId) continue
     const direction: EmailThreadDirection = link.direction === 'outbound' ? 'outbound' : 'inbound'
+    // `authorUserId` on the interaction is the MAILBOX OWNER, which on an
+    // inbound message is the recipient, not the sender — so authorship is an
+    // outbound-only notion. Inbound senders are named by the `from` header.
+    const authorUserId = direction === 'outbound' ? linkIdByInteraction.get(linkId)?.authorUserId ?? null : null
+    const authoredByViewer = !!viewerUserId && !!authorUserId && authorUserId === viewerUserId
     const providerKey = typeof link.providerKey === 'string' ? (link.providerKey as string) : null
     const payload = (link.channelPayload ?? null) as JsonRecord | null
     const meta = (link.channelMetadata ?? null) as JsonRecord | null
@@ -269,6 +322,8 @@ export async function buildPersonEmailThreads(
       direction,
       fromName: fromList[0]?.name ?? null,
       fromEmail: fromList[0]?.email ?? null,
+      authoredByViewer,
+      authorName: authoredByViewer ? null : authorUserId ? authorNames.get(authorUserId) ?? null : null,
       to: toList.map((a) => a.email),
       cc: ccList.map((a) => a.email),
       subject,

package/src/modules/customers/lib/reassignDealOwner.ts

@@ -0,0 +1,51 @@
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import type { BulkActionExecuteResult } from '@open-mercato/ui/backend/DataTable'
+
+export const BULK_UPDATE_OWNER_ENDPOINT = '/api/customers/deals/bulk-update-owner'
+
+type BulkUpdateOwnerResponse = {
+  ok: boolean
+  progressJobId: string | null
+  message: string
+}
+
+/**
+ * Posts a bulk owner reassignment and returns the queued job id.
+ *
+ * Split out of the deals list page so the request shape and the progress-id passthrough are
+ * testable without rendering the page. `errorMessage` is supplied by the caller because the
+ * page owns translation; it is thrown as-is so the guarded-mutation wrapper surfaces the same
+ * text it did before this was extracted.
+ */
+export async function requestBulkOwnerReassignment(params: {
+  ids: string[]
+  ownerUserId: string
+  errorMessage: string
+}): Promise<{ progressJobId: string | null }> {
+  const call = await apiCall<BulkUpdateOwnerResponse>(BULK_UPDATE_OWNER_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ids: params.ids, ownerUserId: params.ownerUserId }),
+  })
+  if (!call.ok) throw new Error(params.errorMessage)
+  return { progressJobId: call.result?.progressJobId ?? null }
+}
+
+/**
+ * The success shape handed back to `DataTable`. Returning `ok: true` with a `progressJobId` is
+ * what makes the table clear the row selection and track the job in the top bar — that side of
+ * the contract is covered by `DataTable.propBulkActions.test.tsx`; this builder is what keeps
+ * our half of it honest.
+ */
+export function buildReassignOwnerSuccess(params: {
+  ids: string[]
+  progressJobId: string | null
+  message: string
+}): BulkActionExecuteResult {
+  return {
+    ok: true,
+    progressJobId: params.progressJobId,
+    affectedCount: params.ids.length,
+    message: params.message,
+  }
+}

package/src/modules/customers/lib/userNames.ts

@@ -0,0 +1,39 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { User } from '@open-mercato/core/modules/auth/data/entities'
+
+/**
+ * Resolves display labels for a set of user ids, tenant/organization scoped.
+ *
+ * Used wherever the CRM attributes something to the colleague who did it — the
+ * "Shared by {name}" badge on the Emails tab, and the per-message sender label
+ * a teammate sees on a shared conversation. Best effort by design: a caller
+ * renders a generic fallback for any id that resolves to no label, so a failed
+ * lookup degrades the wording rather than the read.
+ */
+export async function resolveUserNames(
+  em: EntityManager,
+  tenantId: string,
+  organizationId: string | null,
+  userIds: Array<string | null | undefined>,
+): Promise<Map<string, string>> {
+  const names = new Map<string, string>()
+  const unique = Array.from(new Set(userIds.filter((id): id is string => typeof id === 'string' && !!id)))
+  if (unique.length === 0) return names
+  try {
+    const users = (await findWithDecryption(
+      em,
+      User,
+      { id: { $in: unique } } as never,
+      undefined,
+      { tenantId, organizationId },
+    )) as Array<{ id: string; name?: string | null; email?: string | null }>
+    for (const user of Array.isArray(users) ? users : []) {
+      const label = user.name?.trim() || user.email?.trim() || null
+      if (label) names.set(user.id, label)
+    }
+  } catch {
+    /* best effort — callers fall back to a generic label without a name */
+  }
+  return names
+}

package/src/modules/customers/lib/visibilityFilter.ts

@@ -1,6 +1,7 @@
 import type { FilterQuery } from '@mikro-orm/postgresql'
 import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 import { CustomerInteraction } from '../data/entities'
+import type { ConversationShareGrant } from './conversationShares'
 
 /**
  * The ACL feature that grants admins the right to see private emails authored
@@ -52,6 +53,29 @@ export function canChangeEmailVisibility(opts: {
 export interface ApplyEmailVisibilityFilterOptions {
   currentUserId: string | null
   userFeatures: string[] | null | undefined
+  /**
+   * Conversation shares that widen what this caller may read: each grant means
+   * "the owner of this mailbox handed their email history with this Person to the
+   * team" (`lib/conversationShares.ts`).
+   *
+   * OPTIONAL and fail-closed by design — omitting it (or passing `[]`) yields the
+   * byte-identical strict owner-only predicate that shipped in v1, so a read path
+   * that has not been taught about sharing can only ever under-share.
+   */
+  sharedConversations?: ConversationShareGrant[]
+  /**
+   * Ids of channels the caller may read in full because their owner marked them
+   * as a shared team mailbox (`CommunicationChannel.visibility = 'shared'`).
+   *
+   * Matched against the denormalized `customer_interactions.channel_id`, NOT
+   * against `author_user_id`: an owner with one shared and one private mailbox has
+   * the same author on both, so an author-keyed rule would leak the private one.
+   *
+   * OPTIONAL and fail-closed — omitting it (or passing `[]`) yields the predicate
+   * as it stood before channel sharing existed, so an unconverted read path can
+   * only ever under-share. A row with `channel_id IS NULL` never matches.
+   */
+  sharedChannelIds?: string[]
 }
 
 /**
@@ -81,6 +105,8 @@ export function applyEmailVisibilityFilter<T extends { where: (...args: any[]) =
   //   - legacy/unset rows where `visibility IS NULL` (e.g. email-log entries
   //     created before per-email visibility shipped) — these must remain
   //     visible to avoid silently hiding pre-existing CRM history.
+  const grants = opts.sharedConversations ?? []
+  const sharedChannelIds = opts.sharedChannelIds ?? []
   return query.where((eb: any) =>
     eb.or([
       eb('interaction_type', '!=', 'email'),
@@ -89,10 +115,119 @@ export function applyEmailVisibilityFilter<T extends { where: (...args: any[]) =
       currentUserId
         ? eb('author_user_id', '=', currentUserId)
         : eb.val(false),
+      // Conversation shares: the owner handed their history with this Person to
+      // the team. One arm per grant, each an AND of the two columns the covering
+      // index already leads with.
+      ...grants.map((grant) =>
+        eb.and([
+          eb('entity_id', '=', grant.personEntityId),
+          eb('author_user_id', '=', grant.ownerUserId),
+        ]),
+      ),
+      // Shared team mailboxes: the whole channel was handed to the team. One arm
+      // for the whole set, matching the indexed `channel_id` column.
+      ...(sharedChannelIds.length > 0
+        ? [eb('channel_id', 'in', sharedChannelIds)]
+        : []),
     ]),
   )
 }
 
+/**
+ * Row-level predicate: is this email interaction HIDDEN from the caller?
+ *
+ * The exact logical complement of {@link applyEmailVisibilityFilter}, extracted so
+ * every enforcement point derives from one definition of the rule. Any change to
+ * the visibility predicate MUST be mirrored here and in
+ * {@link applyEmailHiddenFilter} in the same commit — the unit tests assert the
+ * three agree on a shared row matrix.
+ */
+export function isEmailHiddenFrom(opts: {
+  interactionType: string | null | undefined
+  visibility: string | null | undefined
+  authorUserId: string | null | undefined
+  currentUserId: string | null | undefined
+  /** The Person this interaction is anchored to; required to match a share grant. */
+  personEntityId?: string | null | undefined
+  sharedConversations?: ConversationShareGrant[]
+  /** The channel this email arrived through; required to match a shared mailbox. */
+  channelId?: string | null | undefined
+  sharedChannelIds?: string[]
+}): boolean {
+  if (opts.interactionType !== 'email') return false
+  if (opts.visibility !== 'private') return false
+  if (opts.currentUserId && opts.authorUserId && opts.authorUserId === opts.currentUserId) {
+    return false
+  }
+  // A shared team mailbox makes every one of its rows readable. Checked before the
+  // per-Person grants because it is the broader escalation.
+  const sharedChannelIds = opts.sharedChannelIds ?? []
+  if (sharedChannelIds.length > 0 && opts.channelId && sharedChannelIds.includes(opts.channelId)) {
+    return false
+  }
+  const grants = opts.sharedConversations ?? []
+  if (grants.length > 0 && opts.personEntityId && opts.authorUserId) {
+    const shared = grants.some(
+      (grant) =>
+        grant.personEntityId === opts.personEntityId && grant.ownerUserId === opts.authorUserId,
+    )
+    if (shared) return false
+  }
+  return true
+}
+
+/**
+ * Kysely complement of {@link applyEmailVisibilityFilter}: narrows a query to the
+ * email rows the caller may NOT read. Used to count another user's private email
+ * without duplicating the rule in raw SQL.
+ *
+ * Note the SQL NULL semantics deliberately preserved from the original inline
+ * query: `author_user_id != caller` does not match rows whose author is NULL, so a
+ * private row with no author is neither visible nor counted. Private rows always
+ * carry the channel owner as author, so this is unreachable in practice; it is
+ * documented rather than "fixed" so counts do not shift silently.
+ */
+export function applyEmailHiddenFilter<T extends { where: (...args: any[]) => T }>(
+  query: T,
+  opts: ApplyEmailVisibilityFilterOptions,
+): T {
+  const currentUserId = opts.currentUserId
+  const grants = opts.sharedConversations ?? []
+  const sharedChannelIds = opts.sharedChannelIds ?? []
+  return query
+    .where('interaction_type', '=', 'email')
+    .where('visibility', '=', 'private')
+    .where((eb: any) =>
+      currentUserId ? eb('author_user_id', '!=', currentUserId) : eb.val(true),
+    )
+    // Subtract shared team mailboxes, or the Person page would keep reporting
+    // "3 private emails" for a mailbox the caller can now read end to end.
+    // `channel_id IS NULL` must still COUNT, so the NULL case is explicit rather
+    // than left to SQL's three-valued `not in`.
+    .where((eb: any) =>
+      sharedChannelIds.length === 0
+        ? eb.val(true)
+        : eb.or([
+            eb('channel_id', 'is', null),
+            eb('channel_id', 'not in', sharedChannelIds),
+          ]),
+    )
+    // Subtract the shared conversations. Without this the Person page would keep
+    // reporting "3 private emails" for emails the caller can now actually read.
+    .where((eb: any) =>
+      grants.length === 0
+        ? eb.val(true)
+        : eb.and(
+            grants.map((grant) =>
+              eb.or([
+                eb('entity_id', '!=', grant.personEntityId),
+                eb('author_user_id', '!=', grant.ownerUserId),
+              ]),
+            ),
+          ),
+    )
+}
+
 type RbacServiceLike = {
   getEffectiveFeatures?: (
     userId: string,
@@ -138,17 +273,49 @@ export async function resolveCallerEmailFeatures(
  * privacy (v1: strict owner-only): no admin bypass — a private email is hidden
  * from everyone except its author. `opts.userFeatures` is reserved for v2.
  */
-export type EmailVisibilityMikroFilter = { $or?: FilterQuery<CustomerInteraction>[] }
+/**
+ * @deprecated Use {@link EmailVisibilityFilterFragment}. The old shape exposed
+ * `$or` as the only possible key, which invited callers to consume the fragment
+ * as `where.$or = build(...).$or` and silently drop any other arm the predicate
+ * grows. Retained for one minor per the deprecation protocol in
+ * `BACKWARD_COMPATIBILITY.md`.
+ */
+export type EmailVisibilityMikroFilter = EmailVisibilityFilterFragment
+
+/**
+ * Opaque where-fragment to merge (implicit AND) into a `CustomerInteraction`
+ * where-clause. Callers MUST merge the WHOLE fragment — `{ ...fragment }` or
+ * `Object.assign(where, fragment)` — and never cherry-pick a single key, so the
+ * predicate can grow arms without leaking private rows at compile-clean call
+ * sites.
+ */
+export type EmailVisibilityFilterFragment = { $or: FilterQuery<CustomerInteraction>[] }
 
 export function buildEmailVisibilityMikroFilter(
   opts: ApplyEmailVisibilityFilterOptions,
-): EmailVisibilityMikroFilter {
+): EmailVisibilityFilterFragment {
+  // Deliberately a SINGLE `$or` key. Several callers merge this fragment by
+  // object spread into a where-clause that may itself carry other keys; keeping
+  // the whole predicate inside one `$or` means such a spread can never split the
+  // predicate into independently-satisfiable arms. Any future widening MUST be
+  // added as another arm of THIS `$or`, not as a sibling top-level key.
+  const grants = opts.sharedConversations ?? []
+  const sharedChannelIds = opts.sharedChannelIds ?? []
   return {
     $or: [
       { interactionType: { $ne: 'email' } },
       { visibility: null },
       { visibility: { $ne: 'private' } },
       ...(opts.currentUserId ? [{ authorUserId: opts.currentUserId }] : []),
+      // Mirrors the kysely share arm: one AND-pair per grant, kept flat inside
+      // this single `$or` so the fragment stays a one-key object.
+      ...grants.map((grant) => ({
+        entity: grant.personEntityId,
+        authorUserId: grant.ownerUserId,
+      })),
+      // Mirrors the kysely channel arm. Still flat inside this single `$or`, so
+      // the fragment stays a one-key object every caller can spread losslessly.
+      ...(sharedChannelIds.length > 0 ? [{ channelId: { $in: sharedChannelIds } }] : []),
     ],
-  }
+  } as EmailVisibilityFilterFragment
 }