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

package/src/modules/customers/components/detail/PersonEmailThreadsTab.tsx

@@ -21,6 +21,7 @@ import {
   type ComposeEmailChannel,
   type ComposeEmailValues,
 } from './ComposeEmailDialog'
+import { PersonEmailShareControl } from './PersonEmailShareControl'
 
 type PersonEmailThreadsTabProps = {
   personId: string
@@ -93,6 +94,11 @@ function readEventMessageId(event: unknown): string | null {
 export function PersonEmailThreadsTab({ personId, defaultRecipient }: PersonEmailThreadsTabProps) {
   const t = useT()
   const [threads, setThreads] = React.useState<EmailThread[]>([])
+  // Incremented after every thread fetch. The share control's visibility depends
+  // on server state that lands asynchronously (the outbound email becomes a
+  // CustomerInteraction on a queue worker), so it re-reads on this signal rather
+  // than only on mount — see #6455.
+  const [threadsRevision, setThreadsRevision] = React.useState(0)
   const [optimistic, setOptimistic] = React.useState<OptimisticSend[]>([])
   const [channels, setChannels] = React.useState<ComposeEmailChannel[]>([])
   const [loading, setLoading] = React.useState(true)
@@ -137,6 +143,10 @@ export function PersonEmailThreadsTab({ personId, defaultRecipient }: PersonEmai
         setError(err instanceof Error ? err.message : t('customers.email.threads.loadFailed', 'Failed to load emails'))
       } finally {
         if (opts?.showLoading) setLoading(false)
+        // Whether the fetch succeeded or not, this is a point at which the
+        // server state may have moved on — the share control mirrors the same
+        // data (#6455) and rides this cadence instead of polling on its own.
+        setThreadsRevision((value) => value + 1)
       }
     },
     [personId, t],
@@ -211,6 +221,10 @@ export function PersonEmailThreadsTab({ personId, defaultRecipient }: PersonEmai
         direction: 'outbound',
         fromName: null,
         fromEmail: channel?.externalIdentifier ?? null,
+        // The viewer just composed this one, so it renders as "You" before the
+        // server round-trip replaces it with the persisted message.
+        authoredByViewer: true,
+        authorName: null,
         to: values.to,
         cc: values.cc ?? [],
         subject: values.subject,
@@ -422,6 +436,18 @@ export function PersonEmailThreadsTab({ personId, defaultRecipient }: PersonEmai
 
   return (
     <>
+      <PersonEmailShareControl
+        personId={personId}
+        // Re-read whenever the thread list does. The control appears only once
+        // the caller owns a private email with this Person, and that row is
+        // written by a queue worker after the send — so on a first send the
+        // mount-time read is always too early (#6455). The tab's burst poll
+        // already covers exactly that window.
+        reloadToken={threadsRevision}
+        // Flipping the share changes which messages the read filter admits, so
+        // refetch rather than waiting for the background heartbeat.
+        onChanged={() => { void loadThreads() }}
+      />
       <EmailThreadsPanel
         threads={mergedThreads}
         loading={loading}

package/src/modules/customers/components/detail/ScheduleActivityDialog.tsx

@@ -422,14 +422,22 @@ export function ScheduleActivityDialog({
         if (callOutcome) customValues.callOutcome = callOutcome
         if (phoneNumberForPayload) customValues.callPhoneNumber = phoneNumberForPayload
       }
+      // On edit, pin the payload to the activity's own linked entity when the
+      // caller provided one (`editData.entityId`) rather than the `entityId` prop,
+      // which tracks the host page's currently-selected entity and can differ from
+      // the activity's record on multi-entity pages like the deal detail view. This
+      // dialog has no entity picker, so an edit must never silently re-link (#6050).
+      const payloadEntityId = isSaveEdit && editData?.entityId ? editData.entityId : entityId
       const payload = {
         ...(isSaveEdit ? { id: editData!.id } : {}),
-        entityId,
+        entityId: payloadEntityId,
         dealId,
         interactionType: state.activityType,
         title: state.title.trim(),
         body: state.description.trim() || null,
-        status: 'planned',
+        // The dialog has no status control, so an edit must leave the stored status
+        // (and its `occurredAt`) alone instead of re-opening a completed activity (#6481).
+        ...(isSaveEdit ? {} : { status: 'planned' }),
         date: trimmedDate || null,
         time: trimmedDate ? timeForPayload || null : null,
         phoneNumber: state.activityType === 'call' ? phoneNumberForPayload : undefined,

package/src/modules/customers/components/detail/create/CreateDealForm.tsx

@@ -8,6 +8,7 @@ import { translateWithFallback } from '@open-mercato/shared/lib/i18n/translate'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { createCrud } from '@open-mercato/ui/backend/utils/crud'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { useCurrentUserId } from '@open-mercato/ui/backend/utils/useCurrentUserId'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
@@ -47,6 +48,27 @@ export function CreateDealForm({ returnTo, initialValues }: CreateDealFormProps)
   const [errors, setErrors] = React.useState<Record<string, string>>({})
   const [isSubmitting, setIsSubmitting] = React.useState(false)
 
+  // Default the owner to the current user, matching the pipeline quick-create dialog so a
+  // deal created here does not start unowned (an unowned deal notifies nobody when it closes).
+  // useCurrentUserId resolves asynchronously, so this seeds once the id arrives and never
+  // overrides an explicit seed or a choice the user has already made.
+  const currentUserId = useCurrentUserId()
+  // Seeds the picker for the self-assigned id, which may not be on the assignable roster
+  // (an admin who is not a staff team member, or any user when the `staff` module is off).
+  const ownerInitialOption = React.useMemo(
+    () => (currentUserId
+      ? { id: currentUserId, name: tr('customers.filters.currentUser', 'Current user') }
+      : null),
+    [currentUserId, tr],
+  )
+  const ownerSeeded = React.useRef(false)
+  React.useEffect(() => {
+    if (ownerSeeded.current || !currentUserId) return
+    ownerSeeded.current = true
+    if (initialValues?.ownerUserId) return
+    setValues((current) => (current.ownerUserId ? current : { ...current, ownerUserId: currentUserId }))
+  }, [currentUserId, initialValues?.ownerUserId])
+
   const { pipelines, stages, loadStages } = useDealPipelines()
   const {
     customValues,
@@ -73,6 +95,9 @@ export function CreateDealForm({ returnTo, initialValues }: CreateDealFormProps)
   )
 
   const patch = React.useCallback((partial: Partial<BaseValues>) => {
+    // A user touching the owner before useCurrentUserId resolves must not be overridden by
+    // the seeding effect below.
+    if ('ownerUserId' in partial) ownerSeeded.current = true
     setValues((current) => ({ ...current, ...partial }))
   }, [])
 
@@ -135,6 +160,10 @@ export function CreateDealForm({ returnTo, initialValues }: CreateDealFormProps)
         probability: typeof data.probability === 'number' ? data.probability : undefined,
         expectedCloseAt,
         description: data.description && data.description.length ? data.description : undefined,
+        // `null`, not omitted — matching DealForm, so both create surfaces send the same
+        // shape. `dealCreateSchema.ownerUserId` is `.optional().nullable()` (validators.ts:183)
+        // and createDealCommand maps null to null (commands/deals.ts:591).
+        ownerUserId: data.ownerUserId && data.ownerUserId.length ? data.ownerUserId : null,
         personIds: values.personIds.length ? values.personIds : undefined,
         companyIds: values.companyIds.length ? values.companyIds : undefined,
       }
@@ -227,6 +256,7 @@ export function CreateDealForm({ returnTo, initialValues }: CreateDealFormProps)
               pipelines={pipelines}
               stages={stages}
               statusLabels={statusLabels}
+              ownerInitialOption={ownerInitialOption}
               tr={tr}
             />
           </DealSectionCard>

package/src/modules/customers/components/detail/create/DealDetailsFields.tsx

@@ -13,6 +13,7 @@ import { PipelineSelect } from './PipelineSelect'
 import { PipelineStageSelect } from './PipelineStageSelect'
 import { SuffixInput } from './SuffixInput'
 import { DealCurrencyField } from './DealCurrencyField'
+import { DealOwnerSelect, type DealOwnerOption } from '../DealOwnerSelect'
 import { sanitizeAmount, sanitizeProbability } from './dealNumericInput'
 import type { BaseValues } from './dealFormTypes'
 import type { PipelineOption, PipelineStageOption } from './useDealPipelines'
@@ -28,6 +29,8 @@ export type DealDetailsFieldsProps = {
   pipelines: PipelineOption[]
   stages: PipelineStageOption[]
   statusLabels: ReturnType<typeof createDictionarySelectLabels>
+  /** Seeds the owner picker so a self-assigned user outside the roster still renders by name. */
+  ownerInitialOption?: DealOwnerOption | null
   tr: Translate
 }
 
@@ -46,6 +49,7 @@ export function DealDetailsFields({
   pipelines,
   stages,
   statusLabels,
+  ownerInitialOption,
   tr,
 }: DealDetailsFieldsProps) {
   return (
@@ -155,6 +159,14 @@ export function DealDetailsFields({
             placeholder={tr('customers.deals.create.fields.datePlaceholder', 'Pick a date')}
           />
         </DealFormField>
+        <DealFormField fieldId="ownerUserId" label={tr('customers.deals.fields.owner', 'Owner')}>
+          <DealOwnerSelect
+            value={values.ownerUserId ? values.ownerUserId : null}
+            onChange={(next) => patch({ ownerUserId: next ?? '' })}
+            initialOption={ownerInitialOption ?? null}
+            disabled={isSubmitting}
+          />
+        </DealFormField>
       </div>
 
       <DealFormField fieldId="description" label={tr('customers.people.detail.deals.fields.description', 'Description')}>

package/src/modules/customers/components/detail/create/DealSectionCard.tsx

@@ -22,7 +22,10 @@ export function DealSectionCard({
 }: DealSectionCardProps) {
   return (
     <section className={cn('rounded-lg border border-border bg-card shadow-sm p-6 space-y-6', className)}>
-      <div className="flex items-center justify-between gap-3">
+      {/* Stacked below `sm`: in one row the actions stay `shrink-0` while the title column is
+          `min-w-0`, so at phone width the heading collapses to a sliver and breaks word by word
+          under the buttons — worse in languages with longer labels than English (#6858). */}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
         <div className="flex min-w-0 items-center gap-3">
           <div className="flex size-8 shrink-0 items-center justify-center rounded-md bg-brand-violet/10">
             <Icon className="size-4 text-brand-violet" />
@@ -32,7 +35,9 @@ export function DealSectionCard({
             {subtitle ? <p className="text-xs text-muted-foreground">{subtitle}</p> : null}
           </div>
         </div>
-        {actions ? <div className="flex shrink-0 items-center gap-2">{actions}</div> : null}
+        {actions ? (
+          <div className="flex flex-wrap items-center gap-2 sm:shrink-0">{actions}</div>
+        ) : null}
       </div>
       <div className="space-y-4">{children}</div>
     </section>

package/src/modules/customers/components/detail/create/dealFormTypes.ts

@@ -9,6 +9,8 @@ export type BaseValues = {
   valueCurrency: string
   probability: string
   expectedCloseAt: string
+  /** Optional so out-of-tree code constructing a BaseValues literal keeps compiling. */
+  ownerUserId?: string
   description: string
   personIds: string[]
   companyIds: string[]
@@ -23,6 +25,7 @@ export const EMPTY_VALUES: BaseValues = {
   valueCurrency: '',
   probability: '',
   expectedCloseAt: '',
+  ownerUserId: '',
   description: '',
   personIds: [],
   companyIds: [],

package/src/modules/customers/components/detail/schedule/useScheduleFormState.ts

@@ -22,6 +22,14 @@ export type ScheduleActivityEditData = {
   id: string
   /** Record version for the OSS optimistic-lock header on edit (#2055). */
   updatedAt?: string | null
+  /**
+   * The activity's own linked person/company id, captured at edit time. Callers
+   * that show activities from more than one entity (e.g. the deal detail page's
+   * multi-entity activity list) must set this so `ScheduleActivityDialog` keeps
+   * the edit payload's `entityId` pinned to the activity's actual record instead
+   * of whichever entity happens to be selected in the host page's picker (#6050).
+   */
+  entityId?: string | null
   interactionType?: string
   title?: string | null
   body?: string | null
@@ -159,12 +167,16 @@ export function useScheduleFormState({ open, editData }: UseScheduleFormStatePar
         const resolvedType = (editData.interactionType as ActivityType) ?? 'meeting'
         setActivityType(resolvedType)
         setTitle(editData.title ?? '')
-        // For historical activities the canonical timestamp is `occurredAt`; for
-        // planned/future ones it's `scheduledAt`. Without this fallback editing a
-        // past activity prefilled to "today" instead of its actual moment (#1807).
+        // `scheduledAt` is the canonical term of anything that was ever planned, so it
+        // wins whenever it is set: the save path recomputes `scheduledAt` from these
+        // seeded date/time fields, and seeding from `occurredAt` first silently
+        // overwrote a completed task's due date on unrelated edits (#5939).
+        // `occurredAt` stays the fallback for purely historical entries (a logged call
+        // or note) that never had a `scheduledAt`, so editing those still restores
+        // their actual moment instead of falling back to "today" (#1807).
         // Keep seed values in the user's local timezone, matching the cluster-E
         // local-day convention.
-        const sourceTimestamp = editData.occurredAt ?? editData.scheduledAt ?? null
+        const sourceTimestamp = editData.scheduledAt ?? editData.occurredAt ?? null
         const seedDate = sourceTimestamp ? new Date(sourceTimestamp) : null
         const seedDateValid = seedDate !== null && !Number.isNaN(seedDate.getTime())
         // A real edit of an undated task must stay undated: falling back to a

package/src/modules/customers/components/formConfig.tsx

@@ -124,6 +124,7 @@ export type CompanyFormValues = {
 } & Record<string, unknown>
 
 type DictionarySelectFieldProps = {
+  id?: string
   kind: CustomerDictionaryKind
   value?: string
   onChange: (value: string | undefined) => void
@@ -155,6 +156,7 @@ const createSectionHeadingField = (id: string, title: string): CrudField => ({
 })
 
 export function DictionarySelectField({
+  id,
   kind,
   value,
   onChange,
@@ -267,6 +269,7 @@ export function DictionarySelectField({
 
   return (
     <DictionaryEntrySelect
+      id={id}
       value={value}
       onChange={onChange}
       fetchOptions={fetchOptions}

package/src/modules/customers/components/linking/LinkEntityDialog.tsx

@@ -26,6 +26,7 @@ import {
 import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 import { Input } from '@open-mercato/ui/primitives/input'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
 
 const logger = createLogger('customers')
 
@@ -467,6 +468,13 @@ export function LinkEntityDialog<TDetails = unknown, TLinkSettings = Record<stri
         linkSettings,
       })
       onOpenChange(false)
+    } catch (error) {
+      try {
+        getTelemetryRuntime()?.reportError(error, { module: 'customers', code: 'customers.link_confirmation_failed' })
+      } catch (reportingError) {
+        logger.warn('Failed to report link confirmation error', { err: reportingError })
+      }
+      return
     } finally {
       setSaving(false)
     }

package/src/modules/customers/data/enrichers.ts

@@ -3,6 +3,9 @@ import type { CustomerKysely } from '../lib/kysely'
 import { resolveKyselyClient } from '../lib/kysely'
 import { fetchStuckThresholdDays } from '../lib/stuckDeals'
 import { TERMINAL_INTERACTION_STATUS_LIST } from '../lib/interactionStatus'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { listGrantsForViewer, listSharedChannelIds } from '../lib/conversationShares'
+import { applyEmailHiddenFilter, isEmailHiddenFrom } from '../lib/visibilityFilter'
 
 type DealRecord = Record<string, unknown> & {
   id: string
@@ -262,17 +265,34 @@ export const privateEmailCountEnricher: ResponseEnricher<
       return records.map((record) => ({ ...record, _privateEmailCount: 0 }))
     }
 
-    const rows = await (db as CustomerKysely)
+    // The count is the complement of what the read filter admits, so it derives
+    // from the SAME shared rule (`applyEmailHiddenFilter`) rather than restating
+    // `visibility = 'private'` in raw SQL here. Keeping the two in one place is
+    // what stops the Person page reporting "3 private emails" for emails the
+    // caller can actually read once the predicate widens.
+    const baseQuery = (db as CustomerKysely)
       .selectFrom('customer_interactions')
       .select(['entity_id'])
       .select((eb) => eb.fn.countAll().as('count'))
       .where('tenant_id', '=', context.tenantId)
       .where('organization_id', '=', context.organizationId)
-      .where('interaction_type', '=', 'email')
-      .where('visibility', '=', 'private')
       .where('deleted_at', 'is', null)
       .where('entity_id', 'in', personIds)
-      .where('author_user_id', '!=', userId)
+
+    // A conversation the owner shared is no longer "private" to this caller, so it
+    // must not be counted as hidden.
+    const countScope = { tenantId: context.tenantId, organizationId: context.organizationId }
+    const [sharedConversations, sharedChannelIds] = await Promise.all([
+      listGrantsForViewer(context.em as EntityManager, countScope, userId).catch(() => []),
+      listSharedChannelIds(context.em as EntityManager, countScope, userId).catch(() => []),
+    ])
+
+    const rows = await applyEmailHiddenFilter(baseQuery, {
+      currentUserId: userId,
+      userFeatures: undefined,
+      sharedConversations,
+      sharedChannelIds,
+    })
       .groupBy('entity_id')
       .execute()
 
@@ -297,6 +317,24 @@ type InteractionRecord = Record<string, unknown> & {
   externalMessageId?: string | null
 }
 
+/**
+ * The Person an interaction is anchored to, needed to match a conversation-share
+ * grant. Different projections spell the column differently (`entityId` on the
+ * canonical CRUD shape, `entity_id` on raw rows, `entity` when the relation is
+ * serialized), so read all three and fail closed to `null`.
+ */
+function readPersonEntityId(record: Record<string, unknown>): string | null {
+  for (const key of ['entityId', 'entity_id', 'entity'] as const) {
+    const value = record[key]
+    if (typeof value === 'string' && value.length > 0) return value
+    if (value && typeof value === 'object') {
+      const nested = (value as Record<string, unknown>).id
+      if (typeof nested === 'string' && nested.length > 0) return nested
+    }
+  }
+  return null
+}
+
 type EmailIntegrationFields = {
   externalMessageId?: string | null
   rfcMessageId?: string | null
@@ -412,6 +450,13 @@ export const interactionEmailCardEnricher: ResponseEnricher<
     }
 
     const currentUserId = ctx.userId
+    // Conversation shares widen which private emails this caller may act on, so
+    // the card actions derive from the same grants as the read filter.
+    const cardScope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+    const [sharedConversations, sharedChannelIds] = await Promise.all([
+      listGrantsForViewer(ctx.em as EntityManager, cardScope, currentUserId).catch(() => []),
+      listSharedChannelIds(ctx.em as EntityManager, cardScope, currentUserId).catch(() => []),
+    ])
 
     return records.map((r) => {
       if (
@@ -434,7 +479,21 @@ export const interactionEmailCardEnricher: ResponseEnricher<
       // private row is enriched only for its author. The normal read paths
       // already drop these rows; this keeps the globally-registered enricher
       // safe-by-construction for any future consumer that opts into it.
-      if (visibility === 'private' && !isAuthor) {
+      //
+      // Derives from the shared rule so the card actions can never disagree with
+      // the read filter about who may act on an email.
+      if (
+        isEmailHiddenFrom({
+          interactionType: r.interactionType,
+          visibility,
+          authorUserId,
+          currentUserId,
+          personEntityId: readPersonEntityId(r),
+          sharedConversations,
+          channelId: typeof r.channelId === 'string' ? r.channelId : null,
+          sharedChannelIds,
+        })
+      ) {
         return r
       }
       const existingIntegrations = (r._integrations ?? {}) as Record<string, unknown>

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

@@ -565,8 +565,13 @@ export class CustomerActivity {
   expression:
     `create index "customer_interactions_email_visibility_idx" on "customer_interactions" ("entity_id", "interaction_type", "visibility", "author_user_id") where "interaction_type" = 'email' and "deleted_at" is null`,
 })
+@Index({
+  name: 'customer_interactions_email_channel_idx',
+  expression:
+    `create index "customer_interactions_email_channel_idx" on "customer_interactions" ("channel_id", "entity_id") where "interaction_type" = 'email' and "channel_id" is not null and "deleted_at" is null`,
+})
 export class CustomerInteraction {
-  [OptionalProps]?: 'status' | 'pinned' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'durationMinutes' | 'location' | 'allDay' | 'recurrenceRule' | 'recurrenceEnd' | 'participants' | 'reminderMinutes' | 'visibility' | 'linkedEntities' | 'guestPermissions' | 'externalMessageId' | 'channelProviderKey'
+  [OptionalProps]?: 'status' | 'pinned' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'durationMinutes' | 'location' | 'allDay' | 'recurrenceRule' | 'recurrenceEnd' | 'participants' | 'reminderMinutes' | 'visibility' | 'linkedEntities' | 'guestPermissions' | 'externalMessageId' | 'channelProviderKey' | 'channelId'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -604,6 +609,28 @@ export class CustomerInteraction {
   @Property({ name: 'channel_provider_key', type: 'text', nullable: true })
   channelProviderKey?: string | null
 
+  /**
+   * Denormalized `CommunicationChannel.id` this email arrived through.
+   *
+   * Required to answer "is this row's originating channel shared?" without a
+   * three-join hop (`external_message_id` → `message_channel_links` →
+   * `external_conversations` → `communication_channels`); `message_channel_links`
+   * carries no channel id, so there is no shorter path.
+   *
+   * Deliberately NOT resolved from `author_user_id`: an owner with one shared and
+   * one private mailbox has the same author on both, so an author-keyed rule would
+   * expose the private mailbox too.
+   *
+   * NULL means "unknown channel", which every predicate treats as NOT shared —
+   * fail closed. Backfilled once for pre-existing rows; rows whose chain cannot be
+   * resolved stay NULL.
+   *
+   * The cross-module link is declared in `data/extensions.ts` rather than as a raw
+   * FK (root AGENTS.md: no direct ORM relationships between modules).
+   */
+  @Property({ name: 'channel_id', type: 'uuid', nullable: true })
+  channelId?: string | null
+
   @Property({ name: 'status', type: 'text', default: 'planned' })
   status: string = 'planned'
 
@@ -1223,3 +1250,80 @@ export class CustomerPersonCompanyRole {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 }
+
+/**
+ * One owner-granted share of an email conversation: "mailbox owner
+ * `ownerUserId` has shared their email history with Person `personEntity` with
+ * the team."
+ *
+ * The row is a READ GRANT, not a state change. Nothing in
+ * `customer_interactions` is rewritten when a conversation is shared, so:
+ *   - sharing is retroactive (existing private rows become readable),
+ *   - un-sharing is instant and lossless (delete the row; per-message
+ *     `visibility` decisions the owner made by hand are untouched),
+ *   - the query index cannot go stale, because no indexed row is written.
+ *
+ * `lib/visibilityFilter.ts` widens its predicate with an arm matching
+ * `(entity_id, author_user_id)` against live rows of this table. Both columns are
+ * already covered by `customer_interactions_email_visibility_idx`, which is why
+ * the share is keyed on the OWNER rather than on a channel: it needs no
+ * denormalised `channel_id` and no extra join.
+ *
+ * Owner-only by construction: the write route derives `ownerUserId` from the
+ * authenticated caller and accepts no field naming another owner, so there is no
+ * escalation path to guard. `sharedByUserId` is recorded separately so a future
+ * delegated-sharing capability is additive rather than a column-meaning change.
+ */
+@Entity({ tableName: 'customer_email_conversation_shares' })
+@Index({
+  name: 'customer_email_conv_shares_lookup_idx',
+  expression:
+    `create index "customer_email_conv_shares_lookup_idx" on "customer_email_conversation_shares" ("tenant_id", "organization_id", "person_entity_id") where "deleted_at" is null`,
+})
+@Index({
+  name: 'customer_email_conv_shares_owner_idx',
+  expression:
+    `create index "customer_email_conv_shares_owner_idx" on "customer_email_conversation_shares" ("tenant_id", "owner_user_id") where "deleted_at" is null`,
+})
+@Index({
+  name: 'customer_email_conv_shares_uq',
+  expression:
+    `create unique index "customer_email_conv_shares_uq" on "customer_email_conversation_shares" ("tenant_id", "person_entity_id", "owner_user_id") where "deleted_at" is null`,
+})
+export class CustomerEmailConversationShare {
+  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  /** The Person whose conversation is shared (`customer_entities`, kind='person'). */
+  @ManyToOne(() => CustomerEntity, { fieldName: 'person_entity_id' })
+  personEntity!: CustomerEntity
+
+  /**
+   * The mailbox owner whose email becomes readable. Matches
+   * `customer_interactions.author_user_id` on the rows this grant unlocks.
+   */
+  @Property({ name: 'owner_user_id', type: 'uuid' })
+  ownerUserId!: string
+
+  /** Actor who created the share, for audit. Equals `ownerUserId` today. */
+  @Property({ name: 'shared_by_user_id', type: 'uuid' })
+  sharedByUserId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  /** Required for OSS optimistic locking (default ON) on the share toggle. */
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date(), nullable: true })
+  updatedAt?: Date | null
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}

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

@@ -566,6 +566,11 @@ const interactionUpdateBaseSchema = z
   .merge(
     scopedSchema
       .extend({
+        // Re-link an existing interaction to a different person/company, the same way
+        // `dealId` below already re-links it to a different deal (#5938). Not nullable:
+        // `CustomerInteraction.entity` is a required relation, so there is no "detach"
+        // state to express — that depends on #5935 making the column nullable first.
+        entityId: z.string().uuid().optional(),
         interactionType: z.string().trim().min(1).max(100).optional(),
         title: z.string().trim().max(500).optional().nullable(),
         body: z.string().trim().max(10000).optional().nullable(),
@@ -798,6 +803,23 @@ export const labelUnassignCommandSchema = scopedSchema.extend({
 export type LabelAssignCommandInput = z.infer<typeof labelAssignCommandSchema>
 export type LabelUnassignCommandInput = z.infer<typeof labelUnassignCommandSchema>
 
+/**
+ * Set (or clear) the caller's own email-conversation share for one Person.
+ *
+ * Deliberately carries NO owner field: the command derives the owner from the
+ * authenticated actor, so there is no request shape that could share another
+ * user's mailbox.
+ */
+export const emailConversationShareSetCommandSchema = scopedSchema.extend({
+  personEntityId: uuid(),
+  shared: z.boolean(),
+  expectedUpdatedAt: z.string().min(1).nullable().optional(),
+})
+
+export type EmailConversationShareSetCommandInput = z.infer<
+  typeof emailConversationShareSetCommandSchema
+>
+
 export const personCompanyLinkCreateSchema = scopedSchema.extend({
   personEntityId: uuid(),
   companyEntityId: uuid(),

package/src/modules/customers/events.ts

@@ -105,6 +105,11 @@ const events = [
   // ── Email integration (2026-05-27) ────────────────────────────────────────
   { id: 'customers.email.linked', label: 'Email Linked To Person', entity: 'email_link', category: 'lifecycle', clientBroadcast: true },
   { id: 'customers.email.visibility_changed', label: 'Email Visibility Changed', entity: 'email_link', category: 'lifecycle', clientBroadcast: true },
+  // Audit only, deliberately NOT clientBroadcast: the payload names a Person and
+  // a mailbox owner with no recipient hint, so the SSE bridge would fan it out to
+  // the whole tenant/org audience — telling every connected client that user X had
+  // a private conversation with Person P, on the UN-share edge especially.
+  { id: 'customers.email.conversation_visibility_changed', label: 'Email Conversation Visibility Changed', entity: 'email_conversation_share', category: 'lifecycle' },
 ] as const
 
 export const eventsConfig = createModuleEvents({