feat(docs): nested-entity 'This deal' / 'From client' split (B4 #8 phase 4)

Finishes B4 #8 by completing the UI half of the per-interest filing
model. Backend foundations (files.interest_id column, ensureEntityFolder
for 'interest', upload-zone scope radio, outcome rename hook, backfill)
shipped earlier in this audit cycle.

- listFiles validator + service: optional interestId filter
- listFilesAggregatedByEntity: routes entityType='interest' to a new
  helper that returns "THIS DEAL" + "FROM CLIENT" + symmetric-reach
  company/yacht groups
- InterestDocumentsTab: Attachments section now renders two cohorts
  via two paginated queries, with client-side de-duplication so files
  filed under this deal don't double-count under "From client"
- FileRow type exposes the optional interestId so the de-dupe filter
  doesn't need a re-fetch

src/lib/services/files.ts

@@ -22,6 +22,7 @@ import { documentFolders } from '@/lib/db/schema/documents';
 import { clients } from '@/lib/db/schema/clients';
 import { companies, companyMemberships } from '@/lib/db/schema/companies';
 import { yachts } from '@/lib/db/schema/yachts';
+import { interests } from '@/lib/db/schema/interests';
 import type { EntityType } from '@/lib/services/document-folders.service';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -267,7 +268,8 @@ export async function deleteFile(id: string, portId: string, meta: AuditMeta) {
 // ─── List ─────────────────────────────────────────────────────────────────────
 
 export async function listFiles(portId: string, query: ListFilesInput) {
-  const { page, limit, sort, order, search, clientId, yachtId, companyId, category } = query;
+  const { page, limit, sort, order, search, clientId, yachtId, companyId, interestId, category } =
+    query;
 
   const filters = [];
 
@@ -280,6 +282,9 @@ export async function listFiles(portId: string, query: ListFilesInput) {
   if (companyId) {
     filters.push(eq(files.companyId, companyId));
   }
+  if (interestId) {
+    filters.push(eq(files.interestId, interestId));
+  }
   if (category) {
     filters.push(eq(files.category, category));
   }
@@ -333,7 +338,7 @@ export type AggregatedFileRow = Omit<typeof files.$inferSelect, 'storagePath' |
 
 export interface AggregatedFileGroup {
   label: string;
-  source: 'direct' | 'client' | 'company' | 'yacht';
+  source: 'direct' | 'client' | 'company' | 'yacht' | 'this_deal' | 'other_deals';
   files: AggregatedFileRow[];
   total: number;
 }
@@ -351,6 +356,74 @@ const GROUP_LIMIT = 20;
  * Source of truth: each file's snapshotted entity FKs.
  * Defense-in-depth: port_id at every entity / membership / yacht / file join.
  */
+async function listFilesAggregatedForInterest(
+  portId: string,
+  interestId: string,
+  clientId: string | null,
+): Promise<AggregatedFilesResult> {
+  const groups: AggregatedFileGroup[] = [];
+
+  // "THIS DEAL" — files explicitly tagged with this interest_id.
+  const thisDeal = await fetchGroupRows(portId, eq(files.interestId, interestId), GROUP_LIMIT);
+  if (thisDeal.rows.length > 0) {
+    groups.push({
+      label: 'THIS DEAL',
+      source: 'this_deal',
+      files: thisDeal.rows,
+      total: thisDeal.total,
+    });
+  }
+
+  if (clientId) {
+    // "FROM CLIENT" — files on the same client that aren't tagged to
+    // this interest. NULL interest_id = client-level, non-deal-specific.
+    // A different interest id = another deal's docs, still useful to
+    // surface so the rep can pull from history without leaving the
+    // current detail page.
+    const fromClient = await fetchGroupRows(
+      portId,
+      and(
+        eq(files.clientId, clientId),
+        or(isNull(files.interestId), sql`${files.interestId} <> ${interestId}`),
+      )!,
+      GROUP_LIMIT,
+    );
+    if (fromClient.rows.length > 0) {
+      groups.push({
+        label: 'FROM CLIENT',
+        source: 'other_deals',
+        files: fromClient.rows,
+        total: fromClient.total,
+      });
+    }
+
+    // Symmetric reach via the client's related companies + yachts.
+    const related = await collectRelatedEntities(portId, 'client', clientId);
+    for (const { id, name } of related.companies) {
+      const g = await fetchGroupRows(portId, eq(files.companyId, id), GROUP_LIMIT);
+      if (g.rows.length === 0) continue;
+      groups.push({
+        label: `FROM COMPANY: ${name.toUpperCase()}`,
+        source: 'company',
+        files: g.rows,
+        total: g.total,
+      });
+    }
+    for (const { id, name } of related.yachts) {
+      const g = await fetchGroupRows(portId, eq(files.yachtId, id), GROUP_LIMIT);
+      if (g.rows.length === 0) continue;
+      groups.push({
+        label: `FROM YACHT: ${name.toUpperCase()}`,
+        source: 'yacht',
+        files: g.rows,
+        total: g.total,
+      });
+    }
+  }
+
+  return { groups };
+}
+
 export async function listFilesAggregatedByEntity(
   portId: string,
   entityType: EntityType,
@@ -359,6 +432,20 @@ export async function listFilesAggregatedByEntity(
   const entityExists = await assertEntityInPort(portId, entityType, entityId);
   if (!entityExists) return { groups: [] };
 
+  // Interest view: split direct-attached files into "this deal" (files
+  // explicitly tagged with this interestId) + "from client" (files on
+  // the same client but no interestId OR a different interest). The
+  // client-level companies/yachts walk is reused via the underlying
+  // client.
+  if (entityType === 'interest') {
+    const interest = await db.query.interests.findFirst({
+      where: and(eq(interests.id, entityId), eq(interests.portId, portId)),
+      columns: { id: true, clientId: true },
+    });
+    if (!interest) return { groups: [] };
+    return listFilesAggregatedForInterest(portId, interest.id, interest.clientId ?? null);
+  }
+
   const related = await collectRelatedEntities(portId, entityType, entityId);
   const groups: AggregatedFileGroup[] = [];
 
@@ -434,6 +521,13 @@ export async function assertEntityInPort(
     });
     return Boolean(c);
   }
+  if (entityType === 'interest') {
+    const i = await db.query.interests.findFirst({
+      where: and(eq(interests.id, entityId), eq(interests.portId, portId)),
+      columns: { id: true },
+    });
+    return Boolean(i);
+  }
   const y = await db.query.yachts.findFirst({
     where: and(eq(yachts.id, entityId), eq(yachts.portId, portId)),
     columns: { id: true },

src/lib/validators/files.ts

@@ -23,14 +23,18 @@ export const listFilesSchema = baseListQuerySchema
     clientId: z.string().optional(),
     yachtId: z.string().optional(),
     companyId: z.string().optional(),
+    interestId: z.string().optional(),
     category: z.string().optional(),
     folderId: z
       .string()
       .uuid()
       .optional()
       .transform((v) => (v === '' ? null : v)),
-    /** Entity-aggregated projection params - mutually exclusive with folderId. */
-    entityType: z.enum(['client', 'company', 'yacht']).optional(),
+    /** Entity-aggregated projection params - mutually exclusive with folderId.
+     *  'interest' splits direct-attached into "This deal" (files.interestId
+     *  matches) and "From client" (client-level + other deals); the other
+     *  values fall through to the legacy symmetric-reach aggregator. */
+    entityType: z.enum(['client', 'company', 'yacht', 'interest']).optional(),
     entityId: z.string().uuid().optional(),
   })
   .refine(